heyspex 0.1.0 → 0.2.1

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

@@ -0,0 +1,3377 @@
+// How the on-deck brief is rendered: heyspex_next_on_deck / next_review /
+// next_resolution / suggest_pillar / resolve_prerequisite, the enrichOnDeckWith*
+// pipeline (plans, breakage, conflicts, amendments, alignment gate, WIP block,
+// claim target, run front, agent orchestration, memories) and the HTTP augments. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// Amendment tier ([[HS-6DMR-EPIC-amendment-tier-reverse-resolver-amended]]) —
+// partial (non-terminal) supersession. `amends:` lives ONLY on the amending
+// (newer, canonical) doc; the targets are never edited. The reverse map ("what
+// amends spec X") is COMPUTED by scanning every spec's `amends:` list. On the
+// /hs-next brief we warn the breakdown / execution agent that the on-deck epic
+// is amended and inject the source's `## Amends` delta rows so the override is
+// read BEFORE decomposing. Mirrors enrichOnDeckWithConflicts. Contract: AMENDS
+// v1 (specs/research/HS-3RU4-RES-partial-supersession-amendment-tier-for-.md).
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// ────────────────────────────────────────────────────────────────────────────
+// Claim-target banner ([[HS-TASK-NJPH]]) — the legibility surface for the
+// /hs-next on-deck response. Bookended at top + bottom of prompt_markdown
+// so the user always sees the hierarchy + intent verb before authorizing a
+// claim. Vault invariant: a spec is claimable iff it is its own current
+// ClaimTarget (console endpoint enforces this in T4).
+// ────────────────────────────────────────────────────────────────────────────
+//
+// ────────────────────────────────────────────────────────────────────────────
+// Agent orchestration composer — produces two outputs:
+//   • `user_prompt`     — user-facing markdown (claim question, drift summary)
+//   • `agent_dispatch`  — structured routing object (reply→action, failure modes)
+//
+// The split exists because the prior single-`prompt_markdown` shape leaked the
+// "🤖 Agent dispatch (do not paraphrase)" tables + "Failure modes" bullets into
+// the user's terminal output. The agent now reads `agent_dispatch` as a typed
+// object it decodes, and the leak surface is gone. Schema:
+// `specs/schemas/agent-dispatch.schema.json`. Filed under [[HS-TASK-HSNX]];
+// part of the [[HS-EPIC-MCPX]] wire-protocol redesign.
+//
+// The orchestration originally lived in `.claude/commands/hs-next.md` —
+// migrated here to close the SaaS-customer corruption surface
+// ([[workflow-orchestration-belongs-in-mcp-not-claude-commands]],
+// [[HS-RES-J6CD-migrate-slash-command-orchestration-from]]).
+//
+// State-dispatched: fresh-summary, drift-summary, needs-breakdown-summary, and
+// full-mode each get phase-appropriate dispatch.
+// ────────────────────────────────────────────────────────────────────────────
+
+import { ConsoleUnreachableCloudModeError, readViaSelector, resolveReadTier, resolveVaultWriteMode, withDegradationScope } from './read-path.mjs';
+import { consoleFetch, controlError, controlOk, enrichConsoleFailurePayloadAsync } from './console-transport.mjs';
+import { disambiguateClaimSpecId, findSpecFile, loadRoadmap, loadSpec, loadSpecByIdViaTier, loadTask, loadTaskViaGraph, parseFrontmatter, prefetchCloudTaskGraph, wikilinkTarget } from './vault-io.mjs';
+import { isAbsolute, join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { detectUITags, extractSummary, loadDesignMemories, loadDesignMemoriesViaTier } from './memory-tools.mjs';
+import { attachWhyNowFields, buildDesignContextSection, buildOnDeckExplanation, deriveTaskBrief, extractNextStepBlock, loadFocusOverride, loadPillarTierMapViaTier, loadVaultSpecsForSchedulerViaTier, readSchedulerCacheOrderIds, resolveNextOnDeck } from './on-deck-scheduler.mjs';
+import { normalizeRunFrontToken, shouldAutoClaimOnDeck } from './run-front.mjs';
+import { assessBriefReadiness, buildClarificationPrompt, buildDecompositionPromptMarkdown, buildDriftResolutionPrompt, childKindFor, detectCorpusDrift, extractDecompositionContext, getChildRefs, readReadinessFloorSettings } from './alignment-gate.mjs';
+import { formatDisplayId, parseSpecId } from './spec-id-lib.mjs';
+import { hydratePromptWithPlans } from './plan-ingest.mjs';
+import { collectEpicRelatedLinks, detectSpecConflicts } from './plan-push.mjs';
+import { computeClaimTarget, mapStateToHint } from './blocker-resolver.mjs';
+import { detectAgentIdentity, effectiveConsoleUrl } from './mcp-config.mjs';
+import { buildSummaryConsoleWritePrompt, buildSummaryFillInPrompt } from './summary-contract.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { resolveNextResolutionPayload } from './next-resolution.mjs';
+import { resolveNextReviewPayload } from './next-review.mjs';
+import { injectNeonFocusPin } from './focus-tools.mjs';
+import { walkSpecListPages } from './list-tools.mjs';
+import { importDevModeCore } from './dev-mode-core.mjs';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// scripts/lib/dev-mode.mjs is a CODE-repo artifact that ships with this
+// package — since the repo split (2026-08-31) the vault root no longer holds
+// it, so resolve it relative to THIS file's checkout first and fall back to
+// the vault root only for pre-split layouts where they were the same repo.
+// `HS_PKG_ROOT` wins when set (same precedence as dev-tools.mjs's
+// CHECKOUT_ROOT / plan-review.mjs's resolveCodeAuditRoots).
+const CHECKOUT_ROOT = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+
+/**
+ * Internals exposed for the [[HS-TASK-I2Y8]] corpus-diff regression test (the
+ * derived path vs the historical NEXT-STEP-excerpt path across the whole vault).
+ * Not part of the public MCP surface.
+ */
+export const __briefTestables = {
+  deriveTaskBrief,
+  extractNextStepBlock,
+  loadSpec,
+};
+
+/**
+ * Append canonical / resolved external plan content to on-deck prompts.
+ * @param {string} vaultRoot
+ * @param {object} result
+ * @param {object} [args]
+ */
+export function enrichOnDeckWithPlans(vaultRoot, result, args = {}) {
+  if (!result?.spec_path || !result?.prompt_markdown) return result;
+
+  const spec = loadSpec(vaultRoot, result.spec_path);
+  if (!spec) return result;
+
+  const persist =
+    args.persist_plan_ingest === true || args.persist_plan_ingest === 'true';
+
+  const hydrated = hydratePromptWithPlans(
+    vaultRoot,
+    result.spec_path,
+    spec.body,
+    result.prompt_markdown,
+    { persist },
+  );
+
+  const enriched = {
+    ...result,
+    prompt_markdown: hydrated.prompt_markdown,
+    plan_hydration: {
+      had_canonical_in_spec: hydrated.had_canonical_in_spec,
+      plans_in_prompt: hydrated.plans_in_prompt,
+      missing_plans: hydrated.missing_plans,
+    },
+  };
+
+  if (hydrated.persist_result?.written) {
+    enriched.plan_hydration.persisted_to_spec = true;
+    enriched.plan_hydration.spec_path = hydrated.persist_result.spec_path;
+  }
+
+  return enriched;
+}
+
+/**
+ * Pull the `## Expected Breakage & Consequences` section out of a spec body
+ * verbatim ([[spec-hierarchy]] §Expected Breakage & Consequences). Returns the
+ * heading-through-next-heading slice, or null when the section is absent.
+ */
+export function extractBreakageSection(body) {
+  if (!body) return null;
+  const lines = body.split('\n');
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Expected Breakage & Consequences\s*$/i.test(lines[i].trim())) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,2}\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  const section = lines.slice(start, end).join('\n').trim();
+  return section.length > 0 ? section : null;
+}
+
+/**
+ * Surface the spec's `## Expected Breakage & Consequences` section at the top of
+ * the execution body, just above NEXT STEP, so the agent reads the anticipated
+ * cascade *before* coding and a transient rise in tsc/test errors reads as the
+ * expected consequence, not a regression ([[spec-hierarchy]]). No-op when the
+ * spec carries no such section.
+ */
+export function enrichOnDeckWithExpectedBreakage(vaultRoot, result) {
+  if (!result?.spec_path || !result?.prompt_markdown) return result;
+  const spec = loadSpec(vaultRoot, result.spec_path);
+  if (!spec) return result;
+  const section = extractBreakageSection(spec.body);
+  if (!section) return result;
+  return {
+    ...result,
+    prompt_markdown: `${section}\n\n---\n\n${result.prompt_markdown}`,
+    expected_breakage: { present: true },
+  };
+}
+
+export function buildConflictPromptSection(conflicts, relatedLinks) {
+  const lines = ['## Spec conflicts (pre-flight)', ''];
+  if (conflicts.length === 0) {
+    lines.push(
+      'No behavioral conflicts detected between this epic’s NEXT STEP / acceptance criteria and linked specs.',
+    );
+    if (relatedLinks.length > 0) {
+      lines.push('', '**Linked context:**', ...relatedLinks.map((r) => `- [[${r}]]`));
+    }
+    return lines.join('\n');
+  }
+  lines.push(
+    `⚠️ **${conflicts.length} conflict(s)** — resolve before implementation (Console On Deck · \`/hs-resolve\`):`,
+    '',
+  );
+  for (const c of conflicts) {
+    lines.push(`- **Epic:** ${c.epic_claim}`);
+    lines.push(`  **[[${c.spec}]]:** ${c.spec_claim} (${c.section})`);
+  }
+  lines.push('', 'Run **`/hs-resolve`** or update the epic / protocol before proceeding.');
+  return lines.join('\n');
+}
+
+export function enrichOnDeckWithConflicts(vaultRoot, result) {
+  if (!result?.spec_path) return result;
+
+  const spec = loadSpec(vaultRoot, result.spec_path);
+  if (!spec || spec.frontmatter.type !== 'epic') return result;
+
+  const relatedLinks = collectEpicRelatedLinks(
+    spec.frontmatter.related || [],
+    spec.body,
+  );
+  const { conflicts, linked_specs_checked } = detectSpecConflicts(
+    vaultRoot,
+    spec.body,
+    relatedLinks,
+  );
+
+  const conflictSection = buildConflictPromptSection(conflicts, relatedLinks);
+  const referencesBlock =
+    relatedLinks.length > 0
+      ? `\n\n## Related context (read before implementing)\n\n${relatedLinks.map((r) => `- [[${r}]]`).join('\n')}`
+      : '';
+
+  return {
+    ...result,
+    prompt_markdown: `${conflictSection}${referencesBlock}\n\n---\n\n${result.prompt_markdown}`,
+    conflict_analysis: {
+      has_conflicts: conflicts.length > 0,
+      conflict_count: conflicts.length,
+      conflicts,
+      linked_specs_checked,
+      related_links: relatedLinks,
+      resolve_command: `/hs-resolve ${result.spec_id}`,
+    },
+  };
+}
+
+// Normalize a spec reference (wikilink | basename | id) to its stable id token
+// (`HS-AGDG-MIL`), falling back to the bare basename when the token is
+// unrecognizable. Matching on the id token — not the full slugged basename —
+// keeps the reverse map robust to slug drift between an epic's `milestone:`
+// back-ref and a source's `amends:` entry, while still honoring the contract's
+// basename comparison (both share the same leading id token).
+export function amendTargetKey(ref) {
+  const inner = wikilinkTarget(String(ref ?? ''));
+  if (!inner) return null;
+  const trimmed = inner.trim();
+  if (!trimmed) return null;
+  const m = trimmed.match(
+    /^(HS-[A-Z0-9]+-(?:TASK|EPIC|MIL|ROADMAP|RES|CAP|REV|IDEA|FLOW))/i,
+  );
+  return m ? m[1] : trimmed;
+}
+
+// Bare basename of a vault-relative spec path (tolerates `/` or `\` separators).
+export function specPathBasename(specPath) {
+  if (typeof specPath !== 'string') return '';
+  const tail = specPath.split(/[\\/]/).pop() || '';
+  return tail.replace(/\.md$/i, '');
+}
+
+// Parse the `## Amends` delta table out of an amending doc's body. Returns one
+// entry per data row: { target (raw first-cell wikilink basename), targetKey,
+// epics, override }. Tolerates the canonical HS-VZCL column shape
+// (`Amended target | Epic(s) | What this milestone overrides`), the header +
+// separator rows, and any trailing prose after the table.
+export function parseAmendsDeltaTable(body) {
+  if (typeof body !== 'string' || !body) return [];
+  const lines = body.split(/\r?\n/);
+  const startIdx = lines.findIndex((l) => /^#{1,6}\s+Amends\b/i.test(l.trim()));
+  if (startIdx === -1) return [];
+  const rows = [];
+  let seenTable = false;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (/^#{1,6}\s/.test(trimmed)) {
+      if (seenTable) break;
+      continue;
+    }
+    if (!trimmed.startsWith('|')) {
+      if (seenTable) break; // table (and any leading prose) ended
+      continue;
+    }
+    seenTable = true;
+    const cells = trimmed
+      .replace(/^\|/, '')
+      .replace(/\|$/, '')
+      .split('|')
+      .map((c) => c.trim());
+    // Skip the `|---|---|` separator row.
+    if (cells.every((c) => c === '' || /^:?-{2,}:?$/.test(c))) continue;
+    const firstCell = cells[0] || '';
+    // Only wikilink-bearing rows are data; the `Amended target` header is skipped.
+    if (!/\[\[/.test(firstCell)) continue;
+    rows.push({
+      target: wikilinkTarget(firstCell),
+      targetKey: amendTargetKey(firstCell),
+      epics: cells[1] || '',
+      override: cells[2] || '',
+    });
+  }
+  return rows;
+}
+
+// Scan the vault for amending sources whose `amends:` list contains any of the
+// on-deck spec's target keys (its own id and/or its parent milestone). Returns
+// `{ source, matchedKey, rows }[]`, rows being the delta-table entries that
+// resolve to one of those targets.
+export function collectAmendmentSources(vaultRoot, targetKeys, selfKey) {
+  const out = [];
+  const dirs = [
+    'specs/milestones',
+    'specs/epics',
+    'specs/tasks',
+    'specs/roadmaps',
+    'specs/research',
+  ];
+  for (const dir of dirs) {
+    const full = join(vaultRoot, dir);
+    if (!existsSync(full)) continue;
+    let files;
+    try {
+      files = readdirSync(full);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      let parsed;
+      try {
+        parsed = parseFrontmatter(readFileSync(join(full, file), 'utf-8'));
+      } catch {
+        continue;
+      }
+      const amends = parsed.frontmatter?.amends;
+      if (!Array.isArray(amends) || amends.length === 0) continue;
+      const sourceBasename = file.replace(/\.md$/i, '');
+      const sourceKey = amendTargetKey(parsed.frontmatter.id || sourceBasename);
+      // Never report a spec as amended by itself.
+      if (sourceKey && selfKey && sourceKey === selfKey) continue;
+      let matchedKey = null;
+      for (const entry of amends) {
+        const k = amendTargetKey(entry);
+        if (k && targetKeys.has(k)) {
+          matchedKey = k;
+          break;
+        }
+      }
+      if (!matchedKey) continue;
+      const rows = parseAmendsDeltaTable(parsed.body).filter(
+        (r) => r.targetKey && targetKeys.has(r.targetKey),
+      );
+      out.push({ source: sourceBasename, matchedKey, rows });
+    }
+  }
+  return out;
+}
+
+/**
+ * Cloud-reliant sibling of `collectAmendmentSources` ([[HS-DJWP-MCPC-TASK]]
+ * "Amendment scan" family, round 2 — `amends` is now a projectable
+ * `GET /api/specs?fields=` field, added to `SpecSummary`
+ * (`spex-console/src/lib/vault-shared.ts` + `vault.ts` `toSummary()`,
+ * [[HS-DJWP-MCPC-TASK]] round-2 correction: the task Scope explicitly allows
+ * extending that ONE route's projection).
+ *
+ * `collectAmendmentSources` itself stays untouched (the `diskRead` branch).
+ * In `neon` tier:
+ *   1. ONE `GET /api/specs?fields=amends,basename,type` lists every spec's
+ *      normalized `amends` targets — no per-file frontmatter read.
+ *   2. Filtered client-side to the five kinds the disk scan walks
+ *      (milestone/epic/task/roadmap/research) and to non-empty `amends`.
+ *   3. Body text (`parseAmendsDeltaTable`) is fetched via `GET
+ *      /api/specs/[id]` ONLY for sources whose `amends` genuinely matches one
+ *      of `targetKeys` — the rare case — never for the full candidate set.
+ *
+ * NOT wired into `enrichOnDeckWithAmendments` (this function's only caller
+ * today): that enricher runs inside `resolveNextOnDeckPayload`'s fully
+ * synchronous `runEnricherChain`, which 14+ call sites in `cli.test.mjs` call
+ * directly and destructure `{ result, error }` with no `await` — the exact
+ * same "must stay sync" hazard `handleRunPreflight` / `handleRecordAlignment`
+ * hit in round 1. Converting it would need `resolveNextOnDeckPayload` itself
+ * to go async, breaking all of them. This function is a genuine, tested,
+ * ready-to-call primitive; wiring it into the live on-deck enricher chain is
+ * the same larger, deferred piece of work as the rest of that chain
+ * (conflicts / WIP / alignment-drift / claim-target), not a gap specific to
+ * amendments.
+ */
+export async function collectAmendmentSourcesViaTier(vaultRoot, targetKeys, selfKey, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => collectAmendmentSources(vaultRoot, targetKeys, selfKey),
+    neonRead: async () => {
+      // The route answers a bounded page now
+      // ([[HS-C6FO-8KK5-TASK-keyset-spec-list-endpoint-query-layer]]); this
+      // scan needs every candidate, so it follows `next_cursor` to the end
+      // ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).
+      const rows = await walkSpecListPages(consoleFetch, '/api/specs?fields=amends,basename,type');
+      const wantedTypes = new Set(['milestone', 'epic', 'task', 'roadmap', 'research']);
+      const candidates = rows.filter(
+        (r) => wantedTypes.has(r.type) && Array.isArray(r.amends) && r.amends.length > 0,
+      );
+
+      const out = [];
+      for (const row of candidates) {
+        const sourceBasename = row.basename;
+        const sourceKey = amendTargetKey(row.id || sourceBasename);
+        // Never report a spec as amended by itself.
+        if (sourceKey && selfKey && sourceKey === selfKey) continue;
+        let matchedKey = null;
+        for (const entry of row.amends) {
+          const k = amendTargetKey(entry);
+          if (k && targetKeys.has(k)) {
+            matchedKey = k;
+            break;
+          }
+        }
+        if (!matchedKey) continue;
+
+        // Body text is only fetched for a genuine match — the rare case.
+        let body = '';
+        const specRes = await consoleFetch(`/api/specs/${encodeURIComponent(row.id)}`);
+        if (specRes.ok) body = specRes.body?.spec?.body ?? '';
+        const deltaRows = parseAmendsDeltaTable(body).filter(
+          (r) => r.targetKey && targetKeys.has(r.targetKey),
+        );
+        out.push({ source: sourceBasename, matchedKey, rows: deltaRows });
+      }
+      return out;
+    },
+    routeLabel: 'GET /api/specs?fields=amends',
+    consoleUrl,
+  });
+}
+
+export function buildAmendmentPromptSection(sources) {
+  const lines = ['## Amendments (partial supersession — read before implementing)', ''];
+  for (const s of sources) {
+    lines.push(
+      `⚠️ **Amended by [[${s.source}]]** — read it first; it overrides these sections on conflict.`,
+      '',
+    );
+    if (s.rows.length > 0) {
+      lines.push('| Amended target | Epic(s) | Override |', '|---|---|---|');
+      for (const r of s.rows) {
+        const target = r.target ? `[[${r.target}]]` : '';
+        lines.push(`| ${target} | ${r.epics || ''} | ${r.override || ''} |`);
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n').trimEnd();
+}
+
+// Prepend an amendment warning + the source's `## Amends` delta rows when the
+// on-deck epic (or its parent milestone) is amended. Mirrors
+// enrichOnDeckWithConflicts: loads the spec, epics only, prepends above the
+// existing brief with a `---` separator, and attaches a structured
+// `amendment_analysis` field. Additive / no-op when nothing amends the spec.
+export function enrichOnDeckWithAmendments(vaultRoot, result) {
+  if (!result?.spec_path || !result?.prompt_markdown) return result;
+
+  const spec = loadSpec(vaultRoot, result.spec_path);
+  if (!spec || spec.frontmatter.type !== 'epic') return result;
+
+  // The on-deck epic is "amended" when it — OR its parent milestone — is a
+  // target of some source's `amends:` list. In HS-VZCL's real case the targets
+  // are the MILESTONES and the /hs-next unit is an epic under them, so resolve
+  // the epic UP to its milestone (and parent) and match on all three keys.
+  const selfKey = amendTargetKey(spec.frontmatter.id || specPathBasename(result.spec_path));
+  const targetKeys = new Set(
+    [
+      selfKey,
+      amendTargetKey(spec.frontmatter.milestone),
+      amendTargetKey(spec.frontmatter.parent),
+    ].filter(Boolean),
+  );
+  if (targetKeys.size === 0) return result;
+
+  const sources = collectAmendmentSources(vaultRoot, targetKeys, selfKey);
+  if (sources.length === 0) return result;
+
+  const section = buildAmendmentPromptSection(sources);
+  return {
+    ...result,
+    prompt_markdown: `${section}\n\n---\n\n${result.prompt_markdown}`,
+    amendment_analysis: {
+      is_amended: true,
+      amended_by: sources.map((s) => s.source),
+      matched_target_keys: [...targetKeys],
+      sources: sources.map((s) => ({
+        source: s.source,
+        matched_target_key: s.matchedKey,
+        rows: s.rows,
+      })),
+    },
+  };
+}
+
+export const ALIGNMENT_SKIP_STATUSES = new Set([
+  'in_review',
+  'closed',
+  'approved',
+  'hibernated',
+  'deferred',
+]);
+
+/**
+ * Pre-execution alignment gate ([[pre-execution-alignment-gate]]) — the FIRST
+ * pre-flight, upstream of conflict resolution. Runs on the focus-pinned epic or
+ * milestone before the agent executes its chain:
+ *
+ *   - **no children** → HARD breakdown gate (robust decomposition brief).
+ *   - **children + checkpoint fires** → HARD alignment-review gate (revisit the
+ *     breakdown for drift). "Fire" = never reviewed, the breakdown changed, or
+ *     the 7-day fuse expired.
+ *   - **checkpoint ok** → pass the underlying result through untouched.
+ *
+ * Hard for both per the user's "AI agents are good at executing the wrong thing
+ * perfectly" stance; the auditable escape valve is `heyspex_record_alignment`
+ * with an `override_reason`. The gate REPLACES the result (no task brief) so the
+ * agent cannot skim past it — mirrors how a conflict-on-push blocks.
+ *
+ * SSOT invariant (locked by cli.test.mjs "alignment gate reads children from
+ * disk"): the breakdown decision is governed by the focus epic's children as
+ * parsed from the FILE (`loadSpec` → `readFileSync`), never by any index /
+ * cohort / console-response field. A stale derived index therefore cannot trip
+ * a phantom `needs_breakdown` gate. Do not refactor `getChildRefs(fm, …)` below
+ * to read from an index — that reintroduces the cache-vs-SSOT divergence that
+ * cost a session ~15 tool calls of forensic archaeology on HS-EPIC-FCSM.
+ */
+/**
+ * Which spec does the alignment gate actually run against?
+ *
+ * A milestone or epic pin gates itself. A TASK pin used to skip the gate
+ * outright ("task pins are not gated in v1") — and that was the back door: pin
+ * the task rather than its epic and the drift check never ran, even though a
+ * task brief is precisely what goes stale when its epic's corpus moves. A task
+ * has no children to break down, so it gates its PARENT epic instead.
+ *
+ * Returns `{ grain, fm, body, gatedVia }`, or null when there is nothing to gate
+ * (an unknown kind, a task with no resolvable parent, or a parent that is not
+ * actionable).
+ */
+export function resolveAlignmentGateTarget(vaultRoot, focus, focusSpec, deps = {}) {
+  const loadRef = deps.loadRef ?? ((ref) => {
+    try {
+      return loadTask(vaultRoot, ref);
+    } catch {
+      return null;
+    }
+  });
+  const fm = focusSpec?.frontmatter || {};
+  const kind = String(focus?.kind || fm.type || '').toLowerCase();
+
+  if (kind === 'milestone') {
+    return { grain: 'milestone', fm, body: focusSpec?.body || '', gatedVia: 'self' };
+  }
+  if (kind === 'epic') {
+    return { grain: 'epic', fm, body: focusSpec?.body || '', gatedVia: 'self' };
+  }
+  if (kind !== 'task') return null;
+
+  const parentRef = fm.parent || fm.epic || fm.milestone || null;
+  if (!parentRef) return null;
+  const parent = loadRef(parentRef);
+  const parentFm = parent?.frontmatter || null;
+  if (!parentFm) return null;
+
+  const parentType = String(parentFm.type || '').toLowerCase();
+  if (parentType !== 'epic' && parentType !== 'milestone') return null;
+  // A closed/parked parent is not actionable — same rule the focus spec gets.
+  if (ALIGNMENT_SKIP_STATUSES.has(String(parentFm.status || '').toLowerCase())) return null;
+
+  return {
+    grain: parentType,
+    fm: parentFm,
+    body: parent.body || '',
+    gatedVia: 'task_parent',
+  };
+}
+
+export function enrichOnDeckWithAlignment(vaultRoot, result, args = {}) {
+  if (!result || result.error) return result;
+  if (args.ignore_focus === true || args.ignore_focus === 'true') return result;
+
+  const focus = loadFocusOverride(vaultRoot, {
+    neonPinSpecId: args.neon_pin_spec_id,
+    neonSelectionSpecPath: args.neon_selection_spec_path,
+  });
+  if (!focus || !focus.spec_path) return result;
+  const focusSpec = loadSpec(vaultRoot, focus.spec_path);
+  if (!focusSpec) return result;
+
+  const focusFm = focusSpec.frontmatter || {};
+  const status = (focusFm.status || '').toLowerCase();
+  if (ALIGNMENT_SKIP_STATUSES.has(status)) return result; // not actionable — don't gate
+
+  // A task pin gates its parent epic rather than skipping the gate entirely.
+  const target = resolveAlignmentGateTarget(vaultRoot, focus, focusSpec);
+  if (!target) return result;
+  const { grain, fm } = target;
+
+  const id = fm.id || focus.spec_path;
+  const name = fm.name || id;
+  const loadRef = (ref) => loadTask(vaultRoot, ref);
+  const node = { id, name, frontmatter: fm, body: target.body };
+  const context = extractDecompositionContext(node, loadRef, grain);
+  const roadmapId = result.roadmap_id || args.roadmap_id;
+
+  const childRefs = getChildRefs(fm, grain);
+  const childSpecs = [];
+  for (const ref of childRefs) {
+    const child = loadRef(ref);
+    if (!child) continue;
+    childSpecs.push({
+      id: child.id || ref,
+      name: child.name || child.frontmatter?.name || ref,
+      status: child.status || child.frontmatter?.status || 'unknown',
+      body: child.body || '',
+    });
+  }
+
+  // No children (or none resolve) → HARD breakdown gate.
+  if (childSpecs.length === 0) {
+    const floor = readReadinessFloorSettings(vaultRoot);
+    const readiness = assessBriefReadiness({ name, context, floor });
+    if (!readiness.ready) {
+      const promptMarkdown = buildClarificationPrompt({
+        id,
+        name,
+        status: fm.status,
+        roadmapId,
+        missing: readiness.missing,
+        focusSpecPath: focus.spec_path,
+        grain,
+      });
+      return {
+        ...buildAlignmentGateResponse({
+          gate: 'needs_breakdown',
+          grain,
+          id,
+          name,
+          status: fm.status,
+          roadmapId,
+          focusSpecPath: focus.spec_path,
+          focusReason: focus.reason,
+          promptMarkdown,
+          suggestedActions: [],
+        }),
+        status: 'needs_clarification',
+        source_kind: 'needs_clarification_gate',
+      };
+    }
+    const promptMarkdown = buildDecompositionPromptMarkdown({
+      grain,
+      id,
+      name,
+      context,
+      roadmapId,
+      focusSpecPath: focus.spec_path,
+    });
+    return buildAlignmentGateResponse({
+      gate: 'needs_breakdown',
+      grain,
+      id,
+      name,
+      status: fm.status,
+      roadmapId,
+      focusSpecPath: focus.spec_path,
+      focusReason: focus.reason,
+      promptMarkdown,
+      suggestedActions: [
+        {
+          action: `file_${childKindFor(grain)}`,
+          mcp_tool: 'heyspex_record_alignment',
+        },
+      ],
+    });
+  }
+
+  // Children exist — AGV2 redefined drift as temporal corpus-staleness
+  // (related/depends_on/milestone last-modified newer than alignment_reviewed_at).
+  // Never a hard block when children exist; if drift is detected, prepend a
+  // soft question loop to the task brief and the agent poses keep/update/drop
+  // to the user. Silent passthrough when there's no baseline or no drift.
+  const loadFileMtime = (ref) => {
+    try {
+      const p = findSpecFile(vaultRoot, ref);
+      if (!p) return null;
+      const st = statSync(join(vaultRoot, p));
+      return st.mtimeMs;
+    } catch {
+      return null;
+    }
+  };
+  const drift = detectCorpusDrift({
+    epic: { frontmatter: fm },
+    reviewedAt: fm.alignment_reviewed_at,
+    loadRef,
+    lastModified: loadFileMtime,
+  });
+  if (!drift.hasDrift) return result; // no corpus changes since baseline — silent passthrough
+
+  const driftSection = buildDriftResolutionPrompt({
+    grain,
+    id,
+    name,
+    context,
+    existingChildren: childSpecs,
+    stale: drift.stale,
+    roadmapId,
+    focusSpecPath: focus.spec_path,
+  });
+  return {
+    ...result,
+    prompt_markdown: `${driftSection}\n\n---\n\n${result.prompt_markdown || ''}`,
+    alignment_drift: {
+      stale_corpus: drift.stale,
+      last_reviewed_at: fm.alignment_reviewed_at || null,
+    },
+  };
+}
+
+/**
+ * Lightweight alignment-state probe for summary mode. Returns the alignment
+ * state of the focus-pinned epic/milestone WITHOUT building the full
+ * decomposition or drift-resolution brief. Mirrors the disk-SSOT discipline of
+ * enrichOnDeckWithAlignment (reads children from spec file, never from a
+ * derived index) but skips the heavy prompt composition.
+ *
+ * Returns { state: 'fresh' | 'drift_detected' | 'needs_breakdown', changed_count? }
+ * or null when there is no focus pin to gate against.
+ */
+export function probeAlignmentState(vaultRoot, args = {}) {
+  if (args.ignore_focus === true || args.ignore_focus === 'true') return null;
+
+  const focus = loadFocusOverride(vaultRoot, {
+    neonPinSpecId: args.neon_pin_spec_id,
+    neonSelectionSpecPath: args.neon_selection_spec_path,
+  });
+  if (!focus || !focus.spec_path) return null;
+  const focusSpec = loadSpec(vaultRoot, focus.spec_path);
+  if (!focusSpec) return null;
+
+  const focusFm = focusSpec.frontmatter || {};
+  const status = (focusFm.status || '').toLowerCase();
+  if (ALIGNMENT_SKIP_STATUSES.has(status)) return null;
+
+  const loadRef = (ref) => {
+    try {
+      return loadTask(vaultRoot, ref);
+    } catch {
+      return null;
+    }
+  };
+  // A task pin probes its parent epic — same rule as the gate itself, so the
+  // banner and the gate can never disagree about whether drift exists.
+  const target = resolveAlignmentGateTarget(vaultRoot, focus, focusSpec, { loadRef });
+  if (!target) return null;
+  const { grain, fm } = target;
+
+  const childRefs = getChildRefs(fm, grain);
+  const childCount = childRefs.reduce((n, ref) => (loadRef(ref) ? n + 1 : n), 0);
+  if (childCount === 0) {
+    return { state: 'needs_breakdown', grain, focus_spec_id: fm.id || focus.spec_path };
+  }
+
+  const loadFileMtime = (ref) => {
+    try {
+      const p = findSpecFile(vaultRoot, ref);
+      if (!p) return null;
+      const st = statSync(join(vaultRoot, p));
+      return st.mtimeMs;
+    } catch {
+      return null;
+    }
+  };
+  const drift = detectCorpusDrift({
+    epic: { frontmatter: fm },
+    reviewedAt: fm.alignment_reviewed_at,
+    loadRef,
+    lastModified: loadFileMtime,
+  });
+  if (drift.hasDrift) {
+    return {
+      state: 'drift_detected',
+      grain,
+      focus_spec_id: fm.id || focus.spec_path,
+      changed_count: Array.isArray(drift.stale) ? drift.stale.length : 0,
+    };
+  }
+  return { state: 'fresh', grain, focus_spec_id: fm.id || focus.spec_path };
+}
+
+/**
+ * Fetch the WIP ledger from the console (`GET /api/wip`) when this machine's
+ * dev-mode reliance is CLOUD — there the hand-off landed in the Neon
+ * `wip_ledger` table ([[HS-VOCF]]: the deployed console cannot write
+ * `.heyspex/wip-state.json`, so the local file is stale by design) and the
+ * /hs-next brief must surface the Neon row, not the file. Returns the
+ * `{ [specId]: entry }` map, or null when reliance is local / dev-mode cannot
+ * be read / the console is unreachable — every failure falls back to the
+ * file-ledger path in {@link enrichOnDeckWithWip}, best-effort, never throws.
+ */
+export async function fetchCloudWipStateForBrief(vaultRoot) {
+  try {
+    // Bundler-safe loader: the two runtime paths first (stdio behaviour is
+    // unchanged), then a static specifier webpack can trace — without it the
+    // console's `POST /api/mcp` build baked the BUILD machine's checkout path,
+    // missed on Vercel, and every remote /hs-next silently lost its WIP block.
+    const mod = await importDevModeCore([
+      join(CHECKOUT_ROOT, 'scripts', 'lib', 'dev-mode.mjs'),
+      vaultRoot ? join(vaultRoot, 'scripts', 'lib', 'dev-mode.mjs') : null,
+    ]);
+    const resolved = mod.resolveDevMode();
+    if (resolved?.reliance !== 'cloud') return null;
+  } catch {
+    return null;
+  }
+  try {
+    const res = await consoleFetch('/api/wip', { timeout: 10000 });
+    // A denied caller scope is a 200 with an EMPTY ledger and an
+    // authorized:false marker (review S2) - treat it as "cloud unavailable"
+    // (null -> file fallback), never as "there is no hand-off".
+    if (res?.ok && res.body?.vaultScope?.authorized === false) return null;
+    const state = res?.ok ? res.body?.wip_state : null;
+    if (!state || typeof state !== 'object' || Array.isArray(state)) return null;
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Best-effort injection of the cloud ledger into next-on-deck args as
+ * `cloud_wip_state` (internal arg, not in the tool schema — same pattern as
+ * `neon_pin_spec_id`). No-op outside cloud reliance and in summary mode
+ * (the summary enricher chain skips the WIP block entirely). Exported for
+ * the `hs next` CLI face (`scripts/hs-next.mjs`), which builds the same brief.
+ */
+export async function injectCloudWipState(vaultRoot, args) {
+  if (args?.summary === true || args?.summary === 'true') return args;
+  if (args?.ignore_wip === true || args?.ignore_wip === 'true') return args;
+  const cloud = await fetchCloudWipStateForBrief(vaultRoot);
+  return cloud ? { ...args, cloud_wip_state: cloud } : args;
+}
+
+/** Read `.heyspex/wip-state.json` from disk. {} on missing / parse error. */
+export function loadWipState(vaultRoot) {
+  try {
+    const p = join(vaultRoot, '.heyspex', 'wip-state.json');
+    if (!existsSync(p)) return {};
+    const parsed = JSON.parse(readFileSync(p, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+export function renderWipBlock(specId, entry) {
+  const lines = [
+    `## 📋 Previous session WIP — ${specId} (read this, don't reconstruct)`,
+    '',
+    `> A prior session left work on this epic. This is the machine-readable handoff — use it instead of grepping wiring or \`git diff\` to rediscover state. Recorded ${entry.updatedAt || 'unknown'}${entry.agent ? ` by ${entry.agent}` : ''}.`,
+    '',
+  ];
+  const list = (label, arr) => {
+    if (!Array.isArray(arr) || arr.length === 0) return;
+    lines.push(`**${label}:**`);
+    for (const item of arr.slice(0, 25)) lines.push(`- ${item}`);
+    if (arr.length > 25) lines.push(`- …(${arr.length - 25} more)`);
+    lines.push('');
+  };
+  list('Untracked artifacts (built, not committed)', entry.untrackedArtifacts);
+  list('Files touched (uncommitted)', entry.filesTouched);
+  list('Specs filed', entry.specsFiled);
+  list('Verified', entry.verified);
+  list('Remaining', entry.remaining);
+  if (entry.notes) {
+    lines.push(`**Notes:** ${entry.notes}`, '');
+  }
+  return lines.join('\n');
+}
+
+export function wipEntryIsEmpty(entry) {
+  if (!entry || typeof entry !== 'object') return true;
+  const arrays = ['untrackedArtifacts', 'filesTouched', 'specsFiled', 'verified', 'remaining'];
+  const hasArray = arrays.some((k) => Array.isArray(entry[k]) && entry[k].length > 0);
+  return !hasArray && !entry.notes;
+}
+
+/**
+ * Statuses whose WIP entry the ledger keeps. Wider than plain {open, in_progress}:
+ * in_review / review_pending are build-complete but not done-with-handoff — review
+ * is a non-gating, deferrable suggestion (mvp-review-is-optional, owner correction
+ * 2026-08-15), so an epic can keep collecting WIP after submit_for_review. Mirrors
+ * the console write-side retention in `spex-console/src/lib/wip-state.ts`
+ * ([[HS-0QFI-AST6]]) — keep both in sync.
+ */
+export const WIP_RETAIN_STATUSES = new Set(['open', 'in_progress', 'in_review', 'review_pending']);
+
+/**
+ * Does this epic still have an in-flight handoff worth surfacing? Fail-safe: a
+ * missing spec or read error returns true (surface), so a transient lookup
+ * failure never hides live WIP — the console write-side sweep is the
+ * authoritative deletion path.
+ */
+export function wipEpicIsOpen(vaultRoot, epicId) {
+  try {
+    const specPath = findSpecFile(vaultRoot, epicId);
+    if (!specPath) return true;
+    const spec = loadSpec(vaultRoot, specPath);
+    const status = spec?.frontmatter?.status;
+    if (typeof status !== 'string' || !status) return true;
+    return WIP_RETAIN_STATUSES.has(status);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Surface the per-epic WIP ledger ([[HS-EPIC-FCSM]]) in the on-deck brief. When
+ * the result belongs to an epic that has a recorded WIP entry, prepend a
+ * "Previous session WIP" block so the next agent reads structured state instead
+ * of reconstructing it from specs + git diff. Display-only — never gates.
+ */
+export function enrichOnDeckWithWip(vaultRoot, result, args = {}) {
+  if (!result || result.error) return result;
+  if (args.ignore_wip === true || args.ignore_wip === 'true') return result;
+
+  // Cloud reliance: the hand-off lives in the Neon `wip_ledger` table and was
+  // pre-fetched by `injectCloudWipState` ([[HS-VOCF]]); the local file is stale
+  // by design there. Absent (local reliance, console unreachable) → the file.
+  const cloudState =
+    args.cloud_wip_state &&
+    typeof args.cloud_wip_state === 'object' &&
+    !Array.isArray(args.cloud_wip_state)
+      ? args.cloud_wip_state
+      : null;
+  const state = cloudState ?? loadWipState(vaultRoot);
+  if (!state || Object.keys(state).length === 0) return result;
+
+  // Candidate epic ids the result could belong to, most-specific first. Includes
+  // the focus-pinned epic so a freshly-claimed epic surfaces its prior WIP even
+  // before the resolver drills into a child task.
+  const focus = loadFocusOverride(vaultRoot, {
+    neonPinSpecId: args.neon_pin_spec_id,
+    neonSelectionSpecPath: args.neon_selection_spec_path,
+  });
+  const focusSpec = focus?.spec_path ? loadSpec(vaultRoot, focus.spec_path) : null;
+  const focusFm = focusSpec?.frontmatter || {};
+  const focusIsEpic = focusFm.type === 'epic' || focus?.kind === 'epic';
+
+  const candidates = [
+    result.pinned_epic?.id,
+    result.seed_epic?.id,
+    focusIsEpic ? (focusFm.id || focus.spec_path) : null,
+    // result.spec_id itself when the on-deck pick IS an epic (focus_override).
+    typeof result.spec_id === 'string' && parseSpecId(result.spec_id)?.typeLabel === 'EPIC'
+      ? result.spec_id
+      : null,
+  ].filter(Boolean);
+
+  for (const epicId of candidates) {
+    const entry = state[epicId];
+    if (entry && !wipEntryIsEmpty(entry)) {
+      // Retention guard ([[HS-0QFI-AST6]]): the ledger holds open/in_progress/
+      // in_review/review_pending epics. If this epic has since gone terminal or
+      // paused, don't surface its WIP — the work isn't in flight. The console
+      // write-side sweep deletes the stale entry on the next record; this
+      // read-side skip covers the window until then.
+      if (!wipEpicIsOpen(vaultRoot, epicId)) continue;
+      const block = renderWipBlock(epicId, entry);
+      return {
+        ...result,
+        prompt_markdown: `${block}\n\n---\n\n${result.prompt_markdown || ''}`,
+        wip_state: { epic_id: epicId, ...entry },
+      };
+    }
+  }
+  return result;
+}
+
+/**
+ * The claim target's id in long display form — `HS-<fileKey>-<familyKey>`,
+ * without the TYPE label because every surface that renders it also renders
+ * `level` in adjacent prose ([[HS-57WO-094P-RES-long-form-spec-id-display-hs-file-key]]).
+ * Reads the family key off the leaf's own path (era-3 basenames carry it
+ * positionally) and degrades to the short id when the path is absent.
+ */
+export function displayClaimTargetId(claimTarget = {}) {
+  const relPath = claimTarget.relPath || null;
+  const basename = relPath ? String(relPath).split(/[\\/]/).pop().replace(/\.md$/, '') : null;
+  return formatDisplayId(claimTarget.spec_id, { basename, type: claimTarget.level });
+}
+
+/**
+ * Render the ONE `**Sprint:**` line for the claim-target banner
+ * ([[HS-2IF0-7NZ3-EPIC-token-estimation-and-auto-bundling-for-o]] criterion 9 /
+ * [[HS-ARWE-CPQD]]). `sprint` is `result.sprint` from
+ * {@link attachSprintToOnDeck} — the shape it sets on success (never called
+ * when `sprint` is null/absent, so this never has to render a "no sprint"
+ * state). `selfId` (the claim target's own `spec_id`) is excluded from the
+ * "with …" list. Tokens are rounded to the nearest k, per the epic's contract
+ * — this is a heuristic planning aid, not an exact count.
+ */
+export function formatSprintLine(sprint, selfId) {
+  const toK = (n) => `${Math.round((Number(n) || 0) / 1000)}k`;
+  const budgetK = toK(sprint.budget);
+  if (sprint.size <= 1) {
+    if (sprint.overBudget) {
+      return `**Bundle:** ⚠ ~${toK(sprint.estimatedTokens)} tokens exceeds the ${budgetK} budget - plan a solo session or split this task first`;
+    }
+    return `**Bundle:** solo · ~${toK(sprint.estimatedTokens)} of ${budgetK} tokens`;
+  }
+  const selfLower = String(selfId || '').toLowerCase();
+  const others = (Array.isArray(sprint.taskIds) ? sprint.taskIds : []).filter(
+    (id) => String(id).toLowerCase() !== selfLower,
+  );
+  const shown = others.slice(0, 6);
+  const extra = others.length - shown.length;
+  const withPart = shown.length
+    ? ` · with ${shown.join(', ')}${extra > 0 ? ` +${extra}` : ''}`
+    : '';
+  // "Bundle", not "sprint": owner ruling 2026-09-02 — a sprint is the roadmap
+  // unit above the milestone (two or more milestones); the context-window task
+  // group is a bundle ([[HS-3C9M-A4TX-CAP]], supersedes the 2026-05-29 term).
+  return `**Bundle:** task ${sprint.position} of ${sprint.size} in bundle ${sprint.index + 1} · ~${toK(sprint.totalTokens)} of ${budgetK} tokens${withPart}`;
+}
+
+export function formatClaimBanner(claimTarget, alignmentResult = {}, sprint = null) {
+  if (!claimTarget) return '';
+  // Long display form ([[HS-57WO-094P-RES-long-form-spec-id-display-hs-file-key]]):
+  // the family key names the milestone lineage, so the owner can reference the
+  // parent from the banner alone. `includeType` stays off — the banner already
+  // renders `(${level})` and the claim question already bolds the level, so
+  // suffixing `-TASK` would state the kind twice. Display only: every claim,
+  // tool call, and API write still uses the short `claimTarget.spec_id`.
+  const displayedId = displayClaimTargetId(claimTarget);
+  const breadcrumb =
+    Array.isArray(claimTarget.hierarchy_breadcrumb) && claimTarget.hierarchy_breadcrumb.length
+      ? claimTarget.hierarchy_breadcrumb.join(' › ')
+      : displayedId;
+  const lines = [
+    `### 🎯 Claim target — \`${displayedId}\` (${claimTarget.level})`,
+    '',
+    `**Breadcrumb:** ${breadcrumb}`,
+    `**Title:** ${claimTarget.title || displayedId}`,
+  ];
+  // Surface the leaf's authored plain-language summary so the user recognizes the
+  // work before authorizing the claim. The value is a YAML block scalar on disk
+  // (contract-capped ~400 chars); collapse its newlines for the one-line banner.
+  // When absent, omit the line — composeAgentOrchestration handles the
+  // missing-summary case in the claim question (author-then-claim fallback).
+  if (claimTarget.summary && String(claimTarget.summary).trim()) {
+    const summaryOneLine = String(claimTarget.summary).replace(/\s+/g, ' ').trim();
+    lines.push(`**Summary:** ${summaryOneLine}`);
+  }
+  lines.push(
+    `**Intent:** ${claimTarget.intent_verb}`,
+    `**Alignment:** \`${claimTarget.alignment_state || alignmentResult.state || 'unknown'}\``,
+  );
+  // Sprint (token-budgeted work-group), computed at the planning gate and
+  // surfaced here BEFORE execution begins — never decided by the implementing
+  // agent, never silently re-derived mid-implementation
+  // ([[HS-2IF0-7NZ3-EPIC-token-estimation-and-auto-bundling-for-o]] criteria
+  // 7-9 / [[HS-ARWE-CPQD]]). `sprint` arrives only via a second
+  // `formatClaimBanner` call from `attachSprintToOnDeck` once the async
+  // console fetch resolves — the FIRST (synchronous) call in
+  // `enrichOnDeckWithClaimTarget` always passes `null` here.
+  if (sprint) {
+    lines.push(formatSprintLine(sprint, claimTarget.spec_id));
+  }
+  if ((claimTarget.alignment_state || alignmentResult.state) === 'drift_detected') {
+    lines.push(
+      '',
+      '> ⚠️ Drift detected. Review the brief sections above before authorizing — pick option [1] proceed only after you have answered keep/update/drop on each stale corpus doc.',
+    );
+  }
+  if (claimTarget.rollup_state === 'reviewer_blocked') {
+    const n = claimTarget.rollup_detail?.in_review ?? 'some';
+    lines.push(
+      '',
+      `⏳ **Reviewer-blocked** — ${n} child task(s) in review awaiting human review. The right next actor is the reviewer (walk each child's HS-REV companion, accept/reject memory candidates, commit to close).`,
+    );
+  } else if (claimTarget.rollup_state === 'ready_for_close') {
+    lines.push(
+      '',
+      '📋 **Ready for close-out** — every child is build-complete (closed or awaiting batched review below the active review grain). Flip this unit to `in_review`, add the Review back-link, and file an HS-REV companion. See [[session-close-protocol]].',
+    );
+  } else if (claimTarget.rollup_state === 'terminal_leaf') {
+    if (claimTarget.next_action_hint === 'wait_for_reviewer') {
+      lines.push(
+        '',
+        '⏳ **Awaiting review** — this task is done from the agent\'s perspective. Walk its HS-REV companion (or run `/hs-next review <task-id>`); the human reviewer commits to close.',
+      );
+    } else {
+      const st = claimTarget.terminal_status || 'closed';
+      lines.push(
+        '',
+        `✅ **Already terminal** — status is \`${st}\`. There is no implementation work to claim.`,
+      );
+    }
+  }
+  return lines.join('\n');
+}
+
+// Parent-contract tethering ([[HS-FRGG-IU2S-TASK-parent-contract-tethering-in-the-hs]]):
+// a contract-shaped link is a `related:` ref that resolves under specs/adr/,
+// specs/protocols/, or to the entity model — the docs a task could drift against.
+export const CONTRACT_PATH_RE = /(^|[\\/])(adr|protocols)[\\/]|(^|[\\/])entity-model(\.md)?$/i;
+
+/**
+ * Filter a list of refs (wikilinks or bare basenames) down to contract-shaped
+ * docs. Pure: link resolution is injected as `resolveRelPath(ref) → relPath|null`.
+ * Dedupes by ref; a ref that fails to resolve is silently dropped (it is a
+ * dangling link, the linkage gate's problem — not this brief's).
+ */
+export function classifyContractRefs(refs, resolveRelPath) {
+  const out = [];
+  const seen = new Set();
+  for (const raw of Array.isArray(refs) ? refs : []) {
+    const ref = String(raw ?? '')
+      .replace(/^\[\[/, '')
+      .replace(/\]\]$/, '')
+      .split('|')[0]
+      .split('#')[0]
+      .trim();
+    if (!ref || seen.has(ref)) continue;
+    seen.add(ref);
+    let relPath = null;
+    try {
+      relPath = resolveRelPath ? resolveRelPath(ref) : null;
+    } catch {
+      relPath = null;
+    }
+    if (relPath && CONTRACT_PATH_RE.test(String(relPath))) {
+      out.push({ ref, relPath: String(relPath).replace(/\\/g, '/') });
+    }
+  }
+  return out;
+}
+
+/**
+ * Render the task-grain "Parent contract" brief section: the parent epic's goal
+ * plus the contract docs the task must load — or, when no contract-shaped link
+ * resolves, an EXPLICIT hard-surface line (never a silent omission — the epic's
+ * "warning at file time, hard surface at claim time" rule).
+ */
+export function composeParentContractSection(claimTarget = {}) {
+  if (!claimTarget || claimTarget.level !== 'task') return '';
+  const parent = claimTarget.parent || null;
+  const contracts = Array.isArray(claimTarget.parent_contracts)
+    ? claimTarget.parent_contracts
+    : [];
+  const lines = ['#### 📜 Parent contract'];
+  if (parent && (parent.goal || parent.title)) {
+    const goal = String(parent.goal || '').replace(/\s+/g, ' ').trim();
+    lines.push(
+      '',
+      `**Parent${parent.kind ? ` ${parent.kind}` : ''}${parent.title ? ` — ${parent.title}` : ''}:** ${
+        goal || 'no goal recorded — read the parent spec before starting'
+      }`,
+    );
+  }
+  if (contracts.length) {
+    lines.push('', '**Contracts to honor (load before editing the interfaces they own):**');
+    for (const c of contracts) {
+      lines.push(`- [[${c.ref}]] — \`${c.relPath}\``);
+    }
+  } else {
+    lines.push(
+      '',
+      '⚠ **No contract link — parent contract not tethered.** Neither this task nor its parent links an ADR, protocol, or the entity model. Ground against the parent spec before touching shared interfaces, and add the missing contract link to the task.',
+    );
+  }
+  return lines.join('\n');
+}
+
+export function deriveAlignmentState(result) {
+  if (!result) return 'unknown';
+  if (result.alignment_drift) return 'drift_detected';
+  if (typeof result.source_kind === 'string') {
+    if (result.source_kind.endsWith('_gate')) return 'drift_detected';
+    if (result.source_kind === 'milestone_needs_breakdown') return 'drift_detected';
+  }
+  if (typeof result.status === 'string') {
+    if (result.status === 'needs_breakdown' || result.status === 'alignment_review') {
+      return 'drift_detected';
+    }
+  }
+  return 'fresh';
+}
+
+/**
+ * Bookend the response with a claim-target banner so the user reads hierarchy
+ * + intent before reaching the claim line. Reads spec via loadTask — disk,
+ * or (cloud tier) `args.__cloud_task_graph`'s pre-fetch — never from a
+ * derived index (SSOT). Best-effort: on failure the banner is skipped and
+ * the original prompt_markdown stays intact.
+ */
+export function enrichOnDeckWithClaimTarget(vaultRoot, result, args = {}) {
+  if (!result || result.error) return result;
+  if (!result.spec_id) return result;
+  if (args.ignore_claim_target === true || args.ignore_claim_target === 'true') return result;
+
+  // [[HS-H227-MCPC-TASK]]: `__cloud_task_graph` (pre-fetched over HTTP by
+  // `handleNextOnDeck` when cloud-reliant) routes both this load and the
+  // `loadRef` hierarchy/parent-contract walk below through
+  // `loadTaskViaGraph` instead of straight-to-disk `loadTask`. Undefined
+  // (every disk-reliant call site) falls through to the original disk read.
+  let spec = null;
+  try {
+    spec = loadTaskViaGraph(vaultRoot, result.spec_id, args.__cloud_task_graph);
+  } catch {
+    spec = null;
+  }
+  if (!spec) return result;
+
+  const loadRef = (ref) => {
+    try {
+      return loadTaskViaGraph(vaultRoot, ref, args.__cloud_task_graph);
+    } catch {
+      return null;
+    }
+  };
+  const alignmentState = deriveAlignmentState(result);
+  // Converge the claim target onto scheduler output ([[HS-EPIC-CNVG]]): order
+  // the milestone/epic descent by the same global scheduler order every display
+  // surface reads. Priority: the global cache → else the already-scheduler-sorted
+  // `candidate_epics` (milestone drill, warm even on cold cache) → else declared
+  // order. Without this the walk picks the first *written* child (the
+  // seed_epic-vs-claim_target divergence this fixes).
+  const cacheOrderIds = readSchedulerCacheOrderIds(vaultRoot);
+  const schedulerOrderIds =
+    cacheOrderIds.length > 0
+      ? cacheOrderIds
+      : Array.isArray(result.candidate_epics)
+        ? result.candidate_epics.map((e) => e?.id).filter(Boolean)
+        : [];
+  // Tasks other agents actively hold ([[HS-3C9M-A4TX-CAP]]) — set by
+  // resolveNextOnDeckAroundActiveClaims so the walk offers the next task
+  // nobody holds instead of the one already being worked.
+  const excludeIds = Array.isArray(args.exclude_spec_ids)
+    ? new Set(args.exclude_spec_ids.map((id) => String(id).toLowerCase()))
+    : null;
+  const claimTarget = computeClaimTarget(
+    spec,
+    vaultRoot,
+    alignmentState,
+    loadRef,
+    schedulerOrderIds,
+    undefined,
+    excludeIds && excludeIds.size > 0 ? excludeIds : null,
+  );
+  if (!claimTarget) return result;
+
+  // [[HS-68XO-DIAG]] residual — make the claim target addressable by a UNIQUELY-
+  // resolvable handle (see disambiguateClaimSpecId).
+  claimTarget.spec_id = disambiguateClaimSpecId(
+    vaultRoot,
+    claimTarget.spec_id,
+    claimTarget.relPath,
+  );
+
+  // Resolve the immediate parent's goal so the missing-summary authoring prompt
+  // (composeAgentOrchestration, below) can lead with it — a task's epic, an
+  // epic's milestone. Best-effort and read-from-disk (SSOT): a top-level
+  // milestone has no parent and keeps the standalone summary contract.
+  let parentSpecLoaded = null;
+  try {
+    const crumb = Array.isArray(claimTarget.hierarchy_breadcrumb)
+      ? claimTarget.hierarchy_breadcrumb
+      : [];
+    const parentId = crumb.length >= 2 ? crumb[crumb.length - 2] : null;
+    if (parentId && parentId !== claimTarget.spec_id) {
+      const parentSpec = loadRef(parentId);
+      parentSpecLoaded = parentSpec || null;
+      claimTarget.parent = parentSpec
+        ? {
+            id: parentSpec.id || parentId,
+            kind: parentSpec.type || parentSpec.frontmatter?.type || null,
+            title: parentSpec.name || parentSpec.frontmatter?.name || null,
+            goal: parentSpec.frontmatter?.summary || null,
+            relPath: parentSpec.specPath || null,
+          }
+        : { id: parentId, kind: null, title: null, goal: null, relPath: null };
+    }
+  } catch {
+    /* parent context is a nicety, not a gate — skip on any failure */
+  }
+
+  // Parent-contract tethering ([[HS-FRGG-IU2S-TASK-parent-contract-tethering-in-the-hs]]):
+  // at task grain, collect contract-shaped `related:` links from the task AND its
+  // parent so the brief carries the interfaces the work could drift against —
+  // enforced-at-execution, not just recorded in the graph. Best-effort resolve;
+  // an empty result still hard-surfaces via composeParentContractSection.
+  if (claimTarget.level === 'task') {
+    try {
+      const leafSpec = loadRef(claimTarget.spec_id) || spec;
+      const refs = [
+        ...(Array.isArray(leafSpec?.frontmatter?.related) ? leafSpec.frontmatter.related : []),
+        ...(Array.isArray(parentSpecLoaded?.frontmatter?.related)
+          ? parentSpecLoaded.frontmatter.related
+          : []),
+      ];
+      claimTarget.parent_contracts = classifyContractRefs(refs, (ref) => {
+        // findSpecFile returns a VAULT-RELATIVE path (resolveSpecFileRaw contract).
+        // It does not search specs/protocols/ — check that bucket explicitly so
+        // protocol wikilinks (the most common contract shape) classify.
+        const hit = findSpecFile(vaultRoot, ref);
+        if (hit) return hit;
+        const protoRel = join('specs', 'protocols', `${ref}.md`);
+        return existsSync(join(vaultRoot, protoRel)) ? protoRel : null;
+      });
+      claimTarget.contract_tethered = claimTarget.parent_contracts.length > 0;
+    } catch {
+      claimTarget.parent_contracts = [];
+      claimTarget.contract_tethered = false;
+    }
+  }
+
+  const banner = formatClaimBanner(claimTarget, { state: alignmentState });
+  if (!banner) return result;
+
+  const contractSection = composeParentContractSection(claimTarget);
+  const body = (result.prompt_markdown || '').trim();
+  // Summary-mode path: no body to bookend — emit the banner once so the
+  // claim-target line stands alone instead of wrapping an empty middle.
+  const prompt = body.length === 0
+    ? (contractSection ? `${banner}\n\n${contractSection}` : banner)
+    : `${banner}\n\n${contractSection ? `${contractSection}\n\n` : ''}---\n\n${result.prompt_markdown}\n\n---\n\n${banner}`;
+  const enriched = {
+    ...result,
+    // user_prompt_markdown is the canonical user-facing field after HS-TASK-HSNX
+    // split it from agent_dispatch. prompt_markdown stays as the @deprecated
+    // mirror so unmigrated consumers print the same user-facing content.
+    user_prompt_markdown: prompt,
+    prompt_markdown: prompt,
+    claim_target: claimTarget,
+    alignment_result: { state: alignmentState },
+  };
+  if (claimTarget.next_action_hint) {
+    enriched.next_action_hint = claimTarget.next_action_hint;
+  }
+  return enriched;
+}
+
+/** @returns {'handheld' | 'assisted' | 'autonomous'} */
+export function resolveOnDeckFront(args = {}) {
+  return normalizeRunFrontToken(args.front) ?? 'handheld';
+}
+
+/** @param {Record<string, unknown>} args @param {Record<string, unknown>} [overrides] */
+export function packNextOnDeckToolArgs(args = {}, overrides = {}) {
+  const packed = { ...overrides };
+  const front = resolveOnDeckFront(args);
+  if (front !== 'handheld') packed.front = front;
+  if (args.spec_id && packed.spec_id === undefined) packed.spec_id = args.spec_id;
+  if (shouldAutoClaimOnDeck(args) && packed.auto_claim === undefined) packed.auto_claim = true;
+  return packed;
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.specId
+ * @param {string} p.level
+ * @param {string} p.launchTool
+ * @param {string} p.shortSession
+ * @param {Record<string, unknown>} p.args
+ * @param {Record<string, unknown>} p.failureModes
+ */
+export function buildAutoClaimOrchestration({
+  specId,
+  level,
+  launchTool,
+  shortSession,
+  args,
+  failureModes,
+}) {
+  return {
+    user_prompt: [
+      '',
+      '---',
+      '',
+      `🔓 **Auto-claim** — claiming **${level}** \`${specId}\` as **${launchTool} · \`${shortSession}\`** and beginning execution.`,
+    ].join('\n'),
+    agent_dispatch: {
+      phase: 'auto_claim_execute',
+      execute_instruction:
+        'Output user_prompt_markdown verbatim, then immediately run every on_complete action in the SAME turn — claim via heyspex_claim_spec, re-fetch the full brief with summary:false, and begin executing. Do NOT ask the human to confirm.',
+      on_complete: [
+        {
+          tool: 'mcp__heyspex__heyspex_claim_spec',
+          args: { spec_id: specId },
+        },
+        {
+          tool: 'mcp__heyspex__heyspex_next_on_deck',
+          args: packNextOnDeckToolArgs(args, { summary: false }),
+        },
+      ],
+      on_handoff: [
+        {
+          tool: 'mcp__heyspex__heyspex_release_spec',
+          args: { spec_id: specId },
+          comment: 'On session hand-off or when moving the spec to in_review.',
+        },
+      ],
+      failure_modes: failureModes,
+    },
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} claimTarget
+ * @param {Record<string, unknown>} result
+ */
+export function isOnDeckTaskGrain(claimTarget = {}, result = {}) {
+  const level = String(claimTarget.level || '').toLowerCase();
+  if (level === 'task') return true;
+  const id = String(claimTarget.spec_id || result.spec_id || '');
+  return /-TASK-/i.test(id);
+}
+
+/**
+ * Run-front banner for non-handheld `/hs-next` invocations.
+ * @param {'handheld' | 'assisted' | 'autonomous'} front
+ * @param {Record<string, unknown>} claimTarget
+ * @param {Record<string, unknown>} result
+ * @returns {string}
+ */
+/**
+ * Under a run front (assisted / autonomous) the unit the dispatcher takes is a
+ * MILESTONE. When the id the caller gave is a milestone or an epic, the brief's
+ * job is to arm that milestone's run — not to claim the task the walk landed
+ * on ([[HS-3C9M-A4TX-CAP]]). A task named directly keeps the task-grain rules.
+ * Mirrors `resolveArmTarget` in scripts/hs-next.mjs.
+ * @returns {{ milestoneId: string, from: 'milestone' | 'epic', specId: string } | null}
+ */
+export function resolveArmGrainTarget(result, front) {
+  if (!result || (front !== 'assisted' && front !== 'autonomous')) return null;
+  const specPath = String(result.spec_path || '').replace(/\\/g, '/');
+  const specId = result.spec_id ? String(result.spec_id) : '';
+  if (!specId) return null;
+  if (/(^|\/)milestones\//.test(specPath)) return { milestoneId: specId, from: 'milestone', specId };
+  if (/(^|\/)epics\//.test(specPath)) {
+    const crumb = result.claim_target?.hierarchy_breadcrumb;
+    const top = Array.isArray(crumb) && crumb.length > 1 ? String(crumb[0]) : '';
+    return top ? { milestoneId: top, from: 'epic', specId } : null;
+  }
+  return null;
+}
+
+function buildArmRunOrchestration({ arm, front, failureModes }) {
+  const word = front === 'autonomous' ? 'auto' : 'assist';
+  const command = `hs next ${word} ${arm.milestoneId} --launch`;
+  const label = front === 'autonomous' ? 'Autonomous' : 'Assisted';
+  const loop =
+    front === 'autonomous'
+      ? 'unattended — the dispatcher applies the recommended option at each gate and you review the retrospective after'
+      : 'you on the loop — the dispatcher pauses at each decision gate for your answer';
+  const lines = ['', '---', '', `🏭 **${label} run front** — ${loop}.`, ''];
+  if (arm.from !== 'milestone') {
+    lines.push(
+      `Runs arm at milestone grain: \`${arm.specId}\` sits under milestone \`${arm.milestoneId}\`, so that whole milestone is what gets queued.`,
+      '',
+    );
+  }
+  lines.push(
+    `No task is claimed here. Arm the run: \`${command}\` — it writes the same queue + front files the What's Next console writes for the running dispatcher, and prints the \`--ensure\` command when the dispatcher is not live.`,
+  );
+  return {
+    user_prompt: lines.join('\n'),
+    agent_dispatch: {
+      phase: 'arm_run',
+      execute_instruction:
+        'Output user_prompt_markdown verbatim. Do NOT claim the task shown above. Give the human the arm command (it is a terminal step) and stop — the dispatcher owns execution from there.',
+      arm_target: {
+        milestone_id: arm.milestoneId,
+        from: arm.from,
+        spec_id: arm.specId,
+        front,
+        command,
+      },
+      failure_modes: failureModes,
+    },
+  };
+}
+
+export function renderRunFrontSection(front, claimTarget = {}, result = {}) {
+  if (!front || front === 'handheld') return '';
+  // At milestone/epic grain the orchestration section carries the arm command;
+  // a second banner (or the "task launches handheld-only" warning) would only
+  // contradict it.
+  if (resolveArmGrainTarget(result, front)) return '';
+  const specId = claimTarget.spec_id || result.spec_id || 'this spec';
+  const atTask = isOnDeckTaskGrain(claimTarget, result);
+
+  if (atTask) {
+    return [
+      '',
+      '---',
+      '',
+      `⚠️ **Run front \`${front}\` on a task** — single tasks launch in **handheld** mode only.`,
+      '',
+      `- To **implement** \`${specId}\`: \`/hs-next ${specId}\` (handheld is default).`,
+      `- To **batch-run** its parent milestone (the dispatcher runs at milestone grain): \`hs next ${front === 'autonomous' ? 'auto' : 'assist'} <HS-MIL…> --launch\` at a terminal, or \`/hs-next ${front === 'autonomous' ? 'auto' : 'assist'} HS-MIL…\` here.`,
+      `- Working **outside** the console: \`/hs-auto\` orchestrates dev-factory end-to-end.`,
+    ].join('\n');
+  }
+
+  const frontLabel = front === 'autonomous' ? 'Autonomous' : 'Assisted';
+  const loop =
+    front === 'autonomous'
+      ? 'you are *over* the loop — the dispatcher auto-applies Recommended options; review the Retrospective when you return'
+      : 'you are *on* the loop — the dispatcher pauses at decision gates for live answers';
+
+  return [
+    '',
+    '---',
+    '',
+    `🏭 **${frontLabel} run front** — ${loop}.`,
+    '',
+    `- From a terminal: \`hs next ${front === 'autonomous' ? 'auto' : 'assist'} <HS-MIL…> --launch\` arms the run — it writes the same queue + front files the What's Next console writes, and several milestone ids queue in order.`,
+    "- Or launch / steer from the What's Next console, or run `/hs-auto` when working outside HeySpex.",
+    '- Ensure the dispatcher is live: `node dev-factory/coo-dispatcher.mjs --ensure`.',
+    `- Scope resolved for \`${specId}\`; factory launch floor is epic/milestone grain.`,
+  ].join('\n');
+}
+
+/**
+ * @param {Record<string, unknown>} result
+ * @param {Record<string, unknown>} args
+ */
+export function enrichOnDeckWithRunFront(result, args = {}) {
+  if (!result || result.error) return result;
+  const front = resolveOnDeckFront(args);
+  const section = renderRunFrontSection(front, result.claim_target || {}, result);
+  const updated = { ...result, run_front: front };
+  if (section) {
+    const existing = updated.user_prompt_markdown ?? updated.prompt_markdown ?? '';
+    updated.user_prompt_markdown = `${existing}${section}`;
+    updated.prompt_markdown = updated.user_prompt_markdown;
+  }
+  return updated;
+}
+
+/**
+ * Does the missing-`summary:` authoring phase have to write through the
+ * console instead of a vault file? True when ([[HS-T41O-NZ8S-DIAG]]):
+ *   - the session's vault write mode is `cloud` (`__vault_write_mode`,
+ *     injected at the async handler boundary by `handleNextOnDeck` from
+ *     `resolveVaultWriteMode()`), or
+ *   - the target was read from the console (`__cloud_direct_spec` /
+ *     `__cloud_task_graph` — the neon read tier), or
+ *   - the target is Neon-only: its `relPath` does not exist under the
+ *     resolved vault root, so there is no file an Edit could land in.
+ * Absent every signal (every disk-reliant call site, every caller that
+ * predates this) the file-edit brief is kept unchanged. Pure.
+ */
+export function summaryWriteTargetsConsole(result, claimTarget = {}, args = {}) {
+  if (args.__vault_write_mode === 'cloud') return true;
+  if (args.__vault_write_mode === 'local') return false;
+  if (args.__cloud_direct_spec !== undefined || args.__cloud_task_graph || args.__cloud_scheduler_rows) return true;
+  const relPath = claimTarget?.relPath ? String(claimTarget.relPath) : '';
+  const vaultRoot = result?.vault_root ? String(result.vault_root) : '';
+  if (relPath && vaultRoot) {
+    try {
+      return !existsSync(isAbsolute(relPath) ? relPath : join(vaultRoot, relPath));
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+export function composeAgentOrchestration(result, args = {}) {
+  if (!result || result.error) return null;
+  const isSummary = args.summary === true || args.summary === 'true';
+  const claimTarget = result.claim_target || {};
+  const alignmentState =
+    claimTarget.alignment_state ||
+    result.alignment_result?.state ||
+    deriveAlignmentState(result);
+  const specId = claimTarget.spec_id || result.spec_id || 'unknown';
+  // Long form for the human-facing prompt text ONLY — `specId` stays short and
+  // remains what every tool call, claim, and on_complete arg below is built
+  // from ([[HS-57WO-094P-RES-long-form-spec-id-display-hs-file-key]]).
+  const displaySpecId = claimTarget.spec_id ? displayClaimTargetId(claimTarget) : specId;
+  const level = (claimTarget.level || 'spec').toUpperCase();
+  const intent = claimTarget.intent_verb || 'work this spec';
+  const focusSpecId =
+    result.alignment_summary?.focus_spec_id ||
+    result.claim_target?.spec_id ||
+    specId;
+  const changedCount = result.alignment_summary?.changed_count;
+
+  const failureModes = {
+    CONSOLE_URL_MISMATCH: {
+      handling: 'retry_tool_call',
+      note: 'IF an MCP tool returns CONSOLE_URL_MISMATCH: the console dev server is UP on another port; retry the same tool — never hand-write task/epic files.',
+    },
+    CONSOLE_TIMEOUT: {
+      handling: 'retry_tool_call',
+      note: 'IF an MCP tool returns CONSOLE_TIMEOUT: the console is up but slow (cold compile). Retry shortly — do NOT tell the user the server is down.',
+    },
+    CONSOLE_UNREACHABLE: {
+      handling: 'verify_with_dev_server_status',
+      note: 'IF heyspex_claim_spec returns CONSOLE_UNREACHABLE: call heyspex_dev_server_status before telling the user the console is down. Claim-badge-only proceed (status flip on disk) — NEVER hand-write files for heyspex_file_spec failures.',
+    },
+    claim_blocked_by_descendants: {
+      handling: 'rerun_with_descendant_id',
+      note: '409 from heyspex_claim_spec ([[HS-TASK-0RVD]]); use claim_target.spec_id from the error and re-run /hs-next <that-id>',
+    },
+    NO_ACTIONABLE_TASK: {
+      handling: 'suggest_include_horizon',
+      note: 'roadmap is empty/closed; suggest /hs-next --include-horizon',
+    },
+    ROADMAP_NOT_FOUND: { handling: 'surface_and_stop' },
+    VAULT_NOT_FOUND: { handling: 'surface_and_stop' },
+  };
+
+  if (!isSummary) {
+    // Full mode — the user has already authorized at the prior summary step.
+    // No new user-facing prose is added — the body + banner is already on
+    // user_prompt_markdown. Only the structured dispatch is emitted, so the
+    // agent can execute + handle a drift menu without printing any of it.
+    return {
+      user_prompt: null,
+      agent_dispatch: {
+        phase: 'post_claim_execute',
+        execute_instruction:
+          'Output user_prompt_markdown verbatim, then begin executing the work in the SAME turn. The user already authorized the claim — do not ask again.',
+        on_handoff: [
+          {
+            tool: 'mcp__heyspex__heyspex_release_spec',
+            args: { spec_id: specId },
+            comment: 'On session hand-off or when moving the spec to in_review.',
+          },
+        ],
+        drift_resolution_menu: {
+          proceed: {
+            tokens: ['1', 'proceed', 'implement'],
+            actions: [
+              {
+                tool: 'mcp__heyspex__heyspex_record_alignment',
+                args: {
+                  spec_id: focusSpecId,
+                  override_reason:
+                    "<one-line user reason or 'drift accepted at /hs-next'>",
+                },
+              },
+              {
+                tool: 'mcp__heyspex__heyspex_claim_spec',
+                args: { spec_id: specId },
+              },
+              { tool: 'mcp__heyspex__heyspex_next_on_deck', args: packNextOnDeckToolArgs(args) },
+            ],
+            execute_after: true,
+          },
+          refresh_task: {
+            tokens: ['2', 'refresh task'],
+            reply:
+              'Option 2 (`heyspex_regen_task`) is implemented under [[HS-EPIC-HSN1]] / [[HS-TASK-0CKW]]. Until it ships, pick `1` to proceed past the drift or `4` to defer.',
+          },
+          refresh_epic: {
+            tokens: ['3', 'refresh epic'],
+            reply:
+              'Option 3 (`heyspex_regen_tasks_for_epic`) is implemented under [[HS-EPIC-HSN1]] / [[HS-TASK-0CKW]]. Until it ships, pick `1` to proceed past the drift or `4` to defer.',
+          },
+          defer: {
+            tokens: ['4', 'defer', 'skip'],
+            reply:
+              'Deferred. Re-run `/hs-next` when ready, or re-pin `.heyspex/focus.yaml` first.',
+          },
+        },
+        failure_modes: failureModes,
+      },
+    };
+  }
+
+  // Summary mode — render the claim question / drift summary as user-facing
+  // prose, and the dispatch as a structured object.
+  if (alignmentState === 'drift_detected' || alignmentState === 'needs_breakdown') {
+    const summary =
+      alignmentState === 'needs_breakdown'
+        ? `**${alignmentState}** on \`${focusSpecId}\` — the focus epic has no children on disk. The breakdown brief loads on demand.`
+        : `**drift_detected** on \`${focusSpecId}\`${typeof changedCount === 'number' ? ` — ${changedCount} spec${changedCount === 1 ? '' : 's'} changed since the last alignment review` : ''}. Full review brief loads on demand.`;
+    return {
+      user_prompt: [
+        '',
+        '---',
+        '',
+        `⚠️ ${summary}`,
+        '',
+        'Reply `review` to load the full alignment-review brief and decide, or `defer` / `4` to skip.',
+      ].join('\n'),
+      agent_dispatch: {
+        phase: alignmentState === 'needs_breakdown' ? 'needs_breakdown_review' : 'drift_review',
+        on_user_reply: {
+          review: {
+            tokens: ['review', 'show review'],
+            actions: [
+              {
+                tool: 'mcp__heyspex__heyspex_next_on_deck',
+                args: packNextOnDeckToolArgs(args, { summary: false }),
+              },
+            ],
+            comment:
+              'Re-call without summary; output the returned user_prompt_markdown verbatim and follow the drift_resolution_menu in the new agent_dispatch.',
+          },
+          defer: {
+            tokens: ['defer', 'skip', '4'],
+            reply: 'Deferred. Re-run `/hs-next` when ready, or re-pin `.heyspex/focus.yaml` first.',
+          },
+        },
+        failure_modes: failureModes,
+      },
+    };
+  }
+
+  // Fresh alignment — straight claim question, unless rollup blocked the work.
+  // Resolve the session label MCP-side via the same env auto-detect the claim/
+  // file-spec handlers use (the next_on_deck schema accepts no agent/session_id,
+  // so detectAgentIdentity falls back to CLAUDE_CODE_SESSION_ID / 'local'). This
+  // replaces the old literal `{short-session}` placeholder + footnote that leaked
+  // unsubstituted into the user's terminal.
+  const launchIdentity = detectAgentIdentity(args.agent, args.session_id);
+  const shortSession = (launchIdentity.sessionId || 'local').slice(0, 8) || 'local';
+  // Real harness name ("Cursor" / "Claude Code" / "External agent") so the claim
+  // brief names the tool that actually launched, not a hard-coded one. Sourced
+  // from the harness's own session env vars, or HEYSPEX_AGENT set by the spex
+  // console spawner ([[HS-EPIC-NWUE]] / [[HS-EPIC-JLTL]]).
+  const launchTool = launchIdentity.agent || 'your agent';
+
+  if (claimTarget.rollup_state === 'reviewer_blocked') {
+    const n = claimTarget.rollup_detail?.in_review ?? 'Some';
+    return {
+      user_prompt: [
+        '',
+        '---',
+        '',
+        `⏳ **Reviewer-blocked** — ${n} child task(s) under \`${specId}\` are in review. Breakdown is already done — do not claim this epic to break it into tasks.`,
+        '',
+        "Walk each in-review child's HS-REV companion (or run `/hs-next review <task-id>`). Re-run `/hs-next` after children close to surface epic close-out.",
+      ].join('\n'),
+      agent_dispatch: {
+        phase: 'rollup_reviewer_blocked',
+        next_action_hint: 'wait_for_reviewer',
+        failure_modes: failureModes,
+      },
+    };
+  }
+
+  if (claimTarget.rollup_state === 'terminal_leaf') {
+    if (claimTarget.next_action_hint === 'wait_for_reviewer') {
+      return {
+        user_prompt: [
+          '',
+          '---',
+          '',
+          `⏳ **Awaiting review** — \`${specId}\` is \`in_review\`. Implementation is done; walk its HS-REV companion and let the human reviewer commit to close.`,
+          '',
+          'Do not claim this task to implement it. Re-run `/hs-next` without a spec id for the next open task.',
+        ].join('\n'),
+        agent_dispatch: {
+          phase: 'terminal_leaf_awaiting_review',
+          next_action_hint: 'wait_for_reviewer',
+          failure_modes: failureModes,
+        },
+      };
+    }
+    const st = claimTarget.terminal_status || 'closed';
+    return {
+      user_prompt: [
+        '',
+        '---',
+        '',
+        `✅ **Already terminal** — \`${specId}\` has status \`${st}\`. There is nothing to implement or claim.`,
+        '',
+        'Re-run `/hs-next` without a spec id for the next open task, or pick a different spec.',
+      ].join('\n'),
+      agent_dispatch: {
+        phase: 'terminal_leaf_not_claimable',
+        next_action_hint: 'not_claimable',
+        failure_modes: failureModes,
+      },
+    };
+  }
+
+  if (claimTarget.rollup_state === 'ready_for_close') {
+    if (shouldAutoClaimOnDeck(args)) {
+      return buildAutoClaimOrchestration({
+        specId,
+        level,
+        launchTool,
+        shortSession,
+        args,
+        failureModes,
+      });
+    }
+    return {
+      user_prompt: [
+        '',
+        '---',
+        '',
+        `📋 **Ready for close-out** — every child of \`${specId}\` is closed. Next: \`heyspex_submit_for_review({ spec_id: "<review-unit>" })\` per session-close-protocol (never hand-edit frontmatter status), then append change-log + HS-REV when the active grain requires it.`,
+        '',
+        `Type \`proceed\` (or \`yes\` / \`confirm\`) if you want to claim **${level}** \`${specId}\` and perform close-out now.`,
+      ].join('\n'),
+      agent_dispatch: {
+        phase: 'rollup_ready_for_close',
+        next_action_hint: 'flip_to_in_review',
+        on_user_reply: {
+          confirm: {
+            tokens: ['yes', 'proceed', 'confirm'],
+            actions: [
+              {
+                tool: 'mcp__heyspex__heyspex_claim_spec',
+                args: { spec_id: specId },
+              },
+              {
+                tool: 'mcp__heyspex__heyspex_next_on_deck',
+                args: packNextOnDeckToolArgs(args, { summary: false }),
+              },
+            ],
+            execute_after: true,
+          },
+          default: 'respond_to_user_question',
+        },
+        failure_modes: failureModes,
+      },
+    };
+  }
+
+  // Missing-summary fallback: when the leaf has no authored summary, don't jump to
+  // the claim. Hand the agent the shared authoring contract so it writes a real
+  // plain-language summary to the spec file first, then re-shows the brief.
+  // A run front asked at milestone/epic grain arms the milestone's dispatcher
+  // run — it never claims the task the walk landed on ([[HS-3C9M-A4TX-CAP]]).
+  const armGrain = resolveArmGrainTarget(result, resolveOnDeckFront(args));
+  if (armGrain) {
+    return buildArmRunOrchestration({
+      arm: armGrain,
+      front: resolveOnDeckFront(args),
+      failureModes,
+    });
+  }
+
+  if (!claimTarget.summary || !String(claimTarget.summary).trim()) {
+    const relPath = claimTarget.relPath || null;
+    // [[HS-T41O-NZ8S-DIAG]]: when the console row is the source of record the
+    // brief names the console write, never a file edit. Local reliance with
+    // the file on disk keeps the file-edit brief below byte-for-byte.
+    if (summaryWriteTargetsConsole(result, claimTarget, args)) {
+      const consoleUrl = (() => {
+        try {
+          return effectiveConsoleUrl();
+        } catch {
+          return null;
+        }
+      })();
+      const authoringPrompt = buildSummaryConsoleWritePrompt({
+        specId,
+        name: claimTarget.title || specId,
+        type: claimTarget.level || 'task',
+        parent: claimTarget.parent || null,
+        consoleUrl,
+      });
+      return {
+        user_prompt: [
+          '',
+          '---',
+          '',
+          `📝 \`${displaySpecId}\` has no \`summary:\` yet. Author it first (this session is cloud-reliant — the console row is the source of record, so write it with \`heyspex_author_summary\`, not a file edit), then I'll show the summary and ask to claim.`,
+          '',
+          authoringPrompt,
+        ].join('\n'),
+        agent_dispatch: {
+          phase: 'author_summary_then_claim',
+          execute_instruction:
+            `Output user_prompt_markdown verbatim, author the summary, then write it through the console with heyspex_author_summary { spec_id: "${specId}", summary: "<your summary>" } (load it first via heyspex_load_tools { names: ["heyspex_author_summary"] }; it PUTs /api/specs/:id — the console row is the source of record in cloud reliance, so do NOT Edit a vault file for this), then re-run heyspex_next_on_deck { summary: true } to re-show the brief with the summary and ask to claim. Do not claim before the summary is written.`,
+          on_complete: [
+            {
+              tool: 'mcp__heyspex__heyspex_load_tools',
+              args: { names: ['heyspex_author_summary'] },
+              comment: 'heyspex_author_summary is a deferred tool — make it visible before calling it.',
+            },
+            {
+              tool: 'mcp__heyspex__heyspex_author_summary',
+              args: { spec_id: specId, summary: '<the summary you authored — prose only, no YAML>' },
+              comment: 'Console write: PUT /api/specs/:id with only `summary` changed. Nothing is written to disk.',
+            },
+            {
+              tool: 'mcp__heyspex__heyspex_next_on_deck',
+              args: packNextOnDeckToolArgs(args, { summary: true }),
+              comment: 'Re-show the claim brief once the console holds the summary.',
+            },
+          ],
+          failure_modes: failureModes,
+        },
+      };
+    }
+    const authoringPrompt = relPath
+      ? buildSummaryFillInPrompt({
+          specId,
+          name: claimTarget.title || specId,
+          type: claimTarget.level || 'task',
+          relPath,
+          parent: claimTarget.parent || null,
+        })
+      : null;
+    const notice = authoringPrompt
+      ? [
+          '',
+          '---',
+          '',
+          `📝 \`${displaySpecId}\` has no \`summary:\` yet. Author it first, then I'll show the summary and ask to claim.`,
+          '',
+          authoringPrompt,
+        ].join('\n')
+      : [
+          '',
+          '---',
+          '',
+          `📝 \`${displaySpecId}\` has no \`summary:\` yet — author one with \`heyspex_author_summary\` (cloud reliance) or in the file's frontmatter (local reliance) before claiming.`,
+        ].join('\n');
+    return {
+      user_prompt: notice,
+      agent_dispatch: {
+        phase: 'author_summary_then_claim',
+        execute_instruction:
+          'Output user_prompt_markdown verbatim, author the summary into the spec frontmatter via Edit (the vault file on disk is the source of record), then re-run heyspex_next_on_deck { summary: true } to re-show the brief with the summary and ask to claim. Do not claim before the summary is written.',
+        on_complete: [
+          {
+            tool: 'mcp__heyspex__heyspex_next_on_deck',
+            args: packNextOnDeckToolArgs(args, { summary: true }),
+            comment: 'Re-show the claim brief once the summary is written to the spec file.',
+          },
+        ],
+        failure_modes: failureModes,
+      },
+    };
+  }
+
+  if (shouldAutoClaimOnDeck(args)) {
+    return buildAutoClaimOrchestration({
+      specId,
+      level,
+      launchTool,
+      shortSession,
+      args,
+      failureModes,
+    });
+  }
+
+  return {
+    user_prompt: [
+      '',
+      '---',
+      '',
+      `Ready to claim **${level}** \`${displaySpecId}\` to **${intent}**, as **${launchTool} · \`${shortSession}\`**. Type \`proceed\` (or \`yes\` / \`confirm\`) to claim it and begin — or name another spec to redirect.`,
+    ].join('\n'),
+    agent_dispatch: {
+      phase: 'claim_authorization',
+      on_user_reply: {
+        confirm: {
+          tokens: ['yes', 'proceed', 'confirm'],
+          actions: [
+            {
+              tool: 'mcp__heyspex__heyspex_claim_spec',
+              args: { spec_id: specId },
+            },
+            {
+              tool: 'mcp__heyspex__heyspex_next_on_deck',
+              args: packNextOnDeckToolArgs(args, { summary: false }),
+            },
+          ],
+          execute_after: true,
+          comment:
+            'Tools are pre-allowlisted in .claude/settings.local.json — no second permission ask.',
+        },
+        default: 'respond_to_user_question',
+      },
+      failure_modes: failureModes,
+    },
+  };
+}
+
+/**
+ * Apply the composer output to the response shape:
+ *   • appends `user_prompt` (if any) to `user_prompt_markdown`
+ *   • sets the structured `agent_dispatch` field
+ *   • mirrors `user_prompt_markdown` into `prompt_markdown` (the @deprecated
+ *     alias) — `prompt_markdown` now never carries agent-routing prose, so
+ *     legacy consumers that print it can no longer leak dispatch tables.
+ *
+ * Phase-aware via `args.summary`. See [[HS-TASK-HSNX]],
+ * [[HS-RES-J6CD-migrate-slash-command-orchestration-from]].
+ */
+export function enrichOnDeckWithAgentOrchestration(result, args = {}) {
+  if (!result || result.error) return result;
+  const composed = composeAgentOrchestration(result, args);
+  if (!composed) return result;
+  const { user_prompt, agent_dispatch } = composed;
+  const updated = { ...result };
+  if (user_prompt) {
+    const existing = updated.user_prompt_markdown ?? updated.prompt_markdown ?? '';
+    updated.user_prompt_markdown = `${existing}${user_prompt}`;
+    updated.prompt_markdown = updated.user_prompt_markdown;
+  }
+  if (agent_dispatch) {
+    updated.agent_dispatch = agent_dispatch;
+  }
+  return updated;
+}
+
+/** Wrap a gate prompt into the structured /hs-next response shape. */
+export function buildAlignmentGateResponse({
+  gate,
+  grain,
+  id,
+  name,
+  status,
+  roadmapId,
+  focusSpecPath,
+  focusReason,
+  promptMarkdown,
+  suggestedActions = [],
+  checkpointReason,
+  drift,
+}) {
+  const response = {
+    status: gate, // 'needs_breakdown' | 'alignment_review'
+    kind: grain,
+    spec_id: id,
+    spec_title: name,
+    title: name,
+    source_kind: `${gate}_gate`,
+    roadmap_id: roadmapId,
+    spec_path: focusSpecPath,
+    prompt_markdown: promptMarkdown,
+    next_eligible_spec: null,
+    next_action_hint: mapStateToHint(
+      gate === 'needs_breakdown'
+        ? grain === 'milestone'
+          ? 'milestone_needs_breakdown'
+          : 'epic_empty'
+        : 'epic_empty',
+    ),
+    suggested_actions: suggestedActions,
+  };
+  if (typeof status === 'string') response.spec_status = status;
+  if (focusReason) response.focus_reason = focusReason;
+  if (checkpointReason) response.alignment_reason = checkpointReason;
+  if (drift) {
+    response.alignment_analysis = {
+      has_drift: drift.hasDrift,
+      finding_count: drift.findings.length,
+      findings: drift.findings,
+    };
+  }
+  return response;
+}
+
+/**
+ * Summary-mode response diet ([[HS-TASK-CBPK]] / [[mcp-tool-response-size-budget]]).
+ * Keeps the agent-routing surface under ~600 structured tokens so /hs-next does
+ * not burn context before work starts. Full mode is unchanged.
+ */
+export function slimOnDeckSummaryResponse(result) {
+  if (!result || result.error) return result;
+
+  const slimFailureModes = (failureModes) => {
+    if (!failureModes || typeof failureModes !== 'object') return undefined;
+    const out = {};
+    for (const [code, entry] of Object.entries(failureModes)) {
+      out[code] = typeof entry === 'string' ? entry : entry?.handling;
+    }
+    return out;
+  };
+
+  const slimDispatch = (dispatch) => {
+    if (!dispatch || typeof dispatch !== 'object') return undefined;
+    const out = { phase: dispatch.phase };
+    if (dispatch.next_action_hint) out.next_action_hint = dispatch.next_action_hint;
+    if (dispatch.on_user_reply) out.on_user_reply = dispatch.on_user_reply;
+    if (dispatch.execute_instruction) out.execute_instruction = dispatch.execute_instruction;
+    if (dispatch.on_complete) out.on_complete = dispatch.on_complete;
+    if (dispatch.on_handoff) out.on_handoff = dispatch.on_handoff;
+    if (dispatch.arm_target) out.arm_target = dispatch.arm_target;
+    if (dispatch.drift_resolution_menu) out.drift_resolution_menu = dispatch.drift_resolution_menu;
+    const fm = slimFailureModes(dispatch.failure_modes);
+    if (fm) out.failure_modes = fm;
+    return out;
+  };
+
+  const slimClaimTarget = (ct) => {
+    if (!ct || typeof ct !== 'object') return undefined;
+    const out = {
+      level: ct.level,
+      spec_id: ct.spec_id,
+      title: ct.title,
+      intent_verb: ct.intent_verb,
+      tone_token: ct.tone_token,
+      alignment_state: ct.alignment_state,
+      summary: ct.summary,
+      hierarchy_breadcrumb: ct.hierarchy_breadcrumb,
+      relPath: ct.relPath,
+    };
+    if (ct.rollup_state) out.rollup_state = ct.rollup_state;
+    if (ct.next_action_hint) out.next_action_hint = ct.next_action_hint;
+    if (ct.rollup_detail) out.rollup_detail = ct.rollup_detail;
+    if (ct.parent && typeof ct.parent === 'object') {
+      out.parent = {
+        id: ct.parent.id,
+        kind: ct.parent.kind,
+        title: ct.parent.title,
+        relPath: ct.parent.relPath,
+      };
+    }
+    return out;
+  };
+
+  const slim = {
+    spec_id: result.spec_id,
+    title: result.title,
+    status: result.status,
+    source_kind: result.source_kind,
+    roadmap_id: result.roadmap_id,
+    spec_path: result.spec_path,
+    user_prompt_markdown: result.user_prompt_markdown,
+    run_front: result.run_front || 'handheld',
+  };
+  if (result.alignment_summary) slim.alignment_summary = result.alignment_summary;
+  const claimTarget = slimClaimTarget(result.claim_target);
+  if (claimTarget) slim.claim_target = claimTarget;
+  if (result.console_status) slim.console_status = result.console_status;
+  const dispatch = slimDispatch(result.agent_dispatch);
+  if (dispatch) slim.agent_dispatch = dispatch;
+
+  for (const key of [
+    'pinned_epic',
+    'pinned_milestone',
+    'pinned_task',
+    'seed_epic',
+    'candidate_epics',
+    'child_state',
+    'next_action_hint',
+    'unmet_blockers',
+    'blocker_severity',
+    'gating_blockers',
+    'stale_focus_pin',
+    'review_candidates',
+    'milestone_next_epics',
+    // [[HS-2IF0-7NZ3-EPIC-token-estimation-and-auto-bundling-for-o]] criteria
+    // 7-9 / HS-ARWE: the sprint attached by `attachSprintToOnDeck` must
+    // survive summary-mode slimming the same as `gating_blockers` does.
+    'sprint',
+  ]) {
+    if (result[key] !== undefined) slim[key] = result[key];
+  }
+  return slim;
+}
+
+export function finalizeOnDeckPayload(result, isSummary, runEnricherChain) {
+  const enriched = runEnricherChain(result);
+  return isSummary ? slimOnDeckSummaryResponse(enriched) : enriched;
+}
+
+export function resolveNextOnDeckPayload(vaultRoot, config, args = {}) {
+  args = { ...args, front: resolveOnDeckFront(args) };
+  const isSummary = args.summary === true || args.summary === 'true';
+
+  // Summary mode skips plan hydration, conflict scan, WIP block, full
+  // alignment-gate brief, and design context. Keeps the claim-target banner
+  // (cheap, needed to render the question) and replaces the heavy alignment
+  // enricher with a lightweight state probe — see [[hs-next-summary-first-flow]].
+  const runEnricherChain = (result) => {
+    if (isSummary) {
+      const stripped = { ...result, prompt_markdown: '' };
+      const probe = probeAlignmentState(vaultRoot, args);
+      const tagged = probe
+        ? {
+            ...stripped,
+            alignment_summary: probe,
+            // Signal drift_detected to deriveAlignmentState so the claim-target
+            // banner reflects the gate state. The full drift body stays unbuilt;
+            // the slash command re-calls without summary to load it on demand.
+            ...(probe.state === 'drift_detected' || probe.state === 'needs_breakdown'
+              ? { alignment_drift: { stale_corpus: [], last_reviewed_at: null } }
+              : {}),
+          }
+        : stripped;
+      return enrichOnDeckWithRunFront(
+        enrichOnDeckWithAgentOrchestration(
+          enrichOnDeckWithClaimTarget(vaultRoot, tagged, args),
+          args,
+        ),
+        args,
+      );
+    }
+    return enrichOnDeckWithRunFront(
+      enrichOnDeckWithAgentOrchestration(
+        enrichOnDeckWithClaimTarget(
+          vaultRoot,
+          enrichOnDeckWithRecalledMemories(
+            vaultRoot,
+            enrichOnDeckWithWip(
+              vaultRoot,
+              enrichOnDeckWithAlignment(
+                vaultRoot,
+                // Amendments wrap conflicts so the "read the amending doc first"
+                // warning prepends ABOVE the conflict section (most-important-first).
+                enrichOnDeckWithAmendments(
+                  vaultRoot,
+                  enrichOnDeckWithConflicts(
+                    vaultRoot,
+                    enrichOnDeckWithExpectedBreakage(
+                      vaultRoot,
+                      enrichOnDeckWithPlans(vaultRoot, result, args),
+                    ),
+                  ),
+                ),
+              ),
+              args,
+            ),
+            args,
+          ),
+          args,
+        ),
+        args,
+      ),
+      args,
+    );
+  };
+
+  // If spec_id is provided, fetch that specific spec directly.
+  //
+  // [[HS-DJWP-MCPC-TASK]] round 2, AC1: `args.__cloud_direct_spec` — pre-fetched
+  // over HTTP by `handleNextOnDeck` via `loadSpecByIdViaTier` when this session
+  // is cloud-reliant — replaces the `findSpecFile` + `loadSpec` disk pair below
+  // with the SAME shape, so this function stays synchronous (14+ call sites in
+  // cli.test.mjs call it directly and destructure `{ result, error }` with no
+  // `await` — converting it to async would break all of them). `undefined`
+  // (every disk-reliant call site, and every caller that predates this task)
+  // falls through to the original disk pair, unchanged.
+  if (args.spec_id) {
+    let specPath;
+    let spec;
+    if (args.__cloud_direct_spec !== undefined) {
+      if (args.__cloud_direct_spec === null) {
+        return { error: { error: 'SPEC_NOT_FOUND', message: `Spec ${args.spec_id} not found in vault` } };
+      }
+      specPath = args.__cloud_direct_spec.specPath;
+      spec = { frontmatter: args.__cloud_direct_spec.frontmatter, body: args.__cloud_direct_spec.body };
+    } else {
+      specPath = findSpecFile(vaultRoot, args.spec_id);
+      if (!specPath) {
+        return { error: { error: 'SPEC_NOT_FOUND', message: `Spec ${args.spec_id} not found in vault` } };
+      }
+
+      spec = loadSpec(vaultRoot, specPath);
+      if (!spec) {
+        return { error: { error: 'SPEC_LOAD_FAILED', message: `Could not load spec at ${specPath}` } };
+      }
+    }
+
+    let promptMarkdown = '';
+    let designContext = null;
+
+    if (!isSummary) {
+      // [[HS-TASK-G0HF]] the derived brief is the only path — a missing
+      // `## NEXT STEP` no longer hard-errors (NO_NEXT_STEP retired); the block,
+      // if present, is the Tier-0 override prepended by buildExecutionBrief.
+      promptMarkdown = deriveTaskBrief(vaultRoot, {
+        id: spec.frontmatter.id || args.spec_id,
+        name: spec.frontmatter.name || args.spec_id,
+        status: spec.frontmatter.status || 'unknown',
+        roadmapId: args.roadmap_id || config.defaultRoadmapId,
+        frontmatter: spec.frontmatter,
+        body: spec.body,
+        specPath,
+        // [[HS-H227-MCPC-TASK]]: pre-fetched over HTTP by `handleNextOnDeck`
+        // (`prefetchCloudTaskGraph`) when cloud-reliant; undefined everywhere
+        // else, which keeps `deriveTaskBrief`'s `loadRef` on disk.
+        cloudTaskGraph: args.__cloud_task_graph,
+      });
+
+      // Detect UI tags and load design context if applicable
+      const uiTags = detectUITags(spec.frontmatter);
+      if (uiTags.length > 0) {
+        // [[HS-DJWP-MCPC-TASK]] round 2: `__cloud_design_decisions` — pre-fetched
+        // over HTTP by `handleNextOnDeck` (only once it already knows uiTags is
+        // non-empty, from the SAME pre-fetched spec) — falls through to the
+        // disk scan when absent, same additive pattern as `__cloud_direct_spec`.
+        const designDecisions =
+          args.__cloud_design_decisions !== undefined
+            ? args.__cloud_design_decisions
+            : loadDesignMemories(vaultRoot, uiTags);
+        if (designDecisions.length > 0) {
+          designContext = {
+            triggered_by_tags: uiTags,
+            decisions: designDecisions,
+          };
+          const designSection = buildDesignContextSection(designDecisions, uiTags);
+          promptMarkdown = designSection + promptMarkdown;
+        }
+      }
+    }
+
+    const result = {
+      spec_id: spec.frontmatter.id || args.spec_id,
+      title: spec.frontmatter.name || args.spec_id,
+      status: spec.frontmatter.status || 'unknown',
+      source_kind: 'direct_lookup',
+      roadmap_id: args.roadmap_id || config.defaultRoadmapId,
+      prompt_markdown: promptMarkdown,
+      spec_path: specPath,
+      vault_root: vaultRoot,
+      resolved_at: new Date().toISOString(),
+    };
+
+    if (designContext) {
+      result.design_context = designContext;
+    }
+
+    const directExplanation = buildOnDeckExplanation(result.spec_id, [
+      { id: result.spec_id, frontmatter: spec.frontmatter || {} },
+    ], vaultRoot);
+    attachWhyNowFields(result, directExplanation, args.neon_pin_spec_id ?? null);
+
+    return { result: finalizeOnDeckPayload(result, isSummary, runEnricherChain) };
+  }
+
+  const roadmapId = args.roadmap_id || config.defaultRoadmapId;
+  const result = resolveNextOnDeck(vaultRoot, roadmapId, {
+    ignoreFocus: args.ignore_focus === true || args.ignore_focus === 'true',
+    includeHorizon: args.include_horizon === true || args.include_horizon === 'true',
+    // The Neon focus ids, injected by `injectNeonFocusPin` at the async handler
+    // boundary (the file is dormant on a Neon-up machine): layer-1 pin +
+    // layer-2 selection spec_path.
+    neonPinSpecId: args.neon_pin_spec_id,
+    neonSelectionSpecPath: args.neon_selection_spec_path,
+    // [[HS-TASK-JHIA]] frozen milestone snapshot epic order, fetched over HTTP by
+    // `injectFrozenMilestoneOrder` at the async handler boundary (the cli has no
+    // Neon client). Undefined → live scheduler order.
+    frozenEpicOrder: args.frozen_epic_order,
+    // [[HS-DJWP-MCPC-TASK]] — pre-fetched over HTTP by `handleNextOnDeck` when
+    // cloud-reliant; undefined (falls through to disk) everywhere else,
+    // including every OTHER caller of `resolveNextOnDeckPayload`.
+    schedulerRows: args.__cloud_scheduler_rows,
+    pillarTierById: args.__cloud_pillar_tier_by_id,
+  });
+
+  if (result.error) {
+    return { error: result };
+  }
+
+  result.vault_root = vaultRoot;
+  result.resolved_at = new Date().toISOString();
+  return { result: finalizeOnDeckPayload(result, isSummary, runEnricherChain) };
+}
+
+/** Append a suffix to BOTH the canonical + deprecated prompt fields (kept in sync). */
+export function appendToOnDeckPrompts(result, suffix) {
+  if (typeof result.user_prompt_markdown === 'string') result.user_prompt_markdown += suffix;
+  if (typeof result.prompt_markdown === 'string') result.prompt_markdown += suffix;
+}
+
+/**
+ * Render the passive overlap section for the on-deck brief ([[HS-TASK-FD5O]]).
+ * Returns '' when no warnings (additive-only).
+ *
+ * @param {Array<{ other_agent: string, other_spec_id?: string, overlapping_globs: string[] }>} stompWarnings
+ */
+export function renderStompWarningsSection(stompWarnings) {
+  if (!Array.isArray(stompWarnings) || stompWarnings.length === 0) return '';
+  const lines = stompWarnings.map((w) => {
+    const agent = w.other_agent || 'Another agent';
+    const globs = Array.isArray(w.overlapping_globs) ? w.overlapping_globs : [];
+    const globText = globs.map((g) => `\`${g}\``).join(', ') || '`(unknown path)`';
+    return `- **${agent}** is also working in ${globText} — coordinate before editing overlapping files.`;
+  });
+  return `\n\n---\n\n## Parallel-agent overlap\n\n${lines.join('\n')}`;
+}
+
+/**
+ * Inject stomp warnings into `user_prompt_markdown` when overlaps exist
+ * ([[HS-TASK-FD5O]]). Sync / pure — the HTTP probe lives in
+ * `augmentOnDeckWithStompWarnings`.
+ */
+export function enrichOnDeckWithStompWarnings(result, stompWarnings) {
+  if (!result || result.error) return result;
+  const section = renderStompWarningsSection(stompWarnings);
+  if (!section) return result;
+  appendToOnDeckPrompts(result, section);
+  return { ...result, stomp_warnings: stompWarnings };
+}
+
+/**
+ * Render the passive identity guidance section for the on-deck brief
+ * ([[HS-TASK-E4OE]]). Returns '' when no nudges (additive-only).
+ *
+ * @param {Array<{ identity_name: string, trigger: string, message: string }>} identityNudges
+ */
+export function renderAgentGuidanceSection(identityNudges) {
+  if (!Array.isArray(identityNudges) || identityNudges.length === 0) return '';
+  const lines = identityNudges.map((n) => `- ${n.message}`);
+  return `\n\n---\n\n## Agent guidance\n\n${lines.join('\n')}`;
+}
+
+/**
+ * Inject identity nudges into `user_prompt_markdown` ([[HS-TASK-E4OE]]).
+ * Sync / pure — the HTTP probe lives in `augmentOnDeckWithIdentityNudges`.
+ */
+export function enrichOnDeckWithIdentityNudges(result, identityNudges) {
+  if (!result || result.error) return result;
+  const section = renderAgentGuidanceSection(identityNudges);
+  if (!section) return result;
+  appendToOnDeckPrompts(result, section);
+  return { ...result, identity_nudges: identityNudges };
+}
+
+/**
+ * Render the parallelism serialization hint section ([[HS-TASK-55VE]]).
+ * Distinct from stomp overlap ([[HS-TASK-FD5O]]) — advises run-one-at-a-time
+ * for shared depends_on or same-module affects_paths. Reused by scheduler
+ * Phase 2 §3 ([[HS-MIL-SCHD-scheduler-and-priority-algorithm]]).
+ *
+ * @param {Array<{ kind: 'depends_on' | 'same_module', other_agent: string, other_spec_id: string, shared_dep?: string, overlapping_globs?: string[] }>} hints
+ */
+export function renderParallelismHintsSection(hints) {
+  if (!Array.isArray(hints) || hints.length === 0) return '';
+  const lines = hints.map((h) => {
+    const agent = h.other_agent || 'Another agent';
+    const spec = h.other_spec_id || 'another spec';
+    if (h.kind === 'depends_on') {
+      const dep = h.shared_dep ? `\`${h.shared_dep}\`` : 'a shared dependency';
+      return `- **${agent}** holds \`${spec}\`, which shares ${dep} with this task — **run one at a time**, not in parallel.`;
+    }
+    const globs = Array.isArray(h.overlapping_globs)
+      ? h.overlapping_globs.map((g) => `\`${g}\``).join(', ')
+      : '';
+    const globText = globs || '`(unknown module)`';
+    return `- **${agent}** holds \`${spec}\` in the same module (${globText}) — **serialize execution** rather than running both tasks in parallel.`;
+  });
+  return `\n\n---\n\n## Parallelism hint\n\n${lines.join('\n')}`;
+}
+
+/**
+ * Inject parallelism hints into `user_prompt_markdown` ([[HS-TASK-55VE]]).
+ * Sync / pure — the HTTP probe lives in `augmentOnDeckWithParallelismHints`.
+ */
+export function enrichOnDeckWithParallelismHints(result, hints) {
+  if (!result || result.error) return result;
+  const section = renderParallelismHintsSection(hints);
+  if (!section) return result;
+  appendToOnDeckPrompts(result, section);
+  return { ...result, parallelism_hints: hints };
+}
+
+/**
+ * Extend "one detection path" to the agent's on-deck brief ([[HS-EPIC-RSSO]] §5).
+ * The milestone/epic drill builds the brief WITHOUT a gating-prerequisite scan,
+ * so the agent saw no blocker while the console overlay showed one. Here we read
+ * the SAME converged endpoint the overlay reads — `GET /api/specs/:id/blockers`
+ * (now aggregator-backed) — for the drilled seed / claim-target spec, and
+ * surface its gating subset. Agent and console therefore read the same bytes.
+ *
+ * Console-unreachable is a dev-only condition ([[console-unreachable-is-dev-only]]):
+ * users never run a local console. On unreachable we emit an honest "start the
+ * dev server" notice — never a second, drift-prone detector ([[no-fallbacks-by-default]]).
+ * Skipped in summary mode (the fast pre-claim first response).
+ */
+export async function augmentOnDeckWithGatingBlockers(result, args = {}) {
+  if (!result || result.error) return;
+  if (args.summary === true || args.summary === 'true') return;
+  const targetId =
+    result.claim_target?.spec_id || result.seed_epic?.id || result.spec_id || null;
+  if (!targetId) return;
+
+  let res;
+  try {
+    res = await consoleFetch(`/api/specs/${encodeURIComponent(targetId)}/blockers?unresolved=true`);
+  } catch {
+    return; // never let the blocker probe break the on-deck brief
+  }
+  if (!res.ok) {
+    if (res.status === 0) {
+      appendToOnDeckPrompts(
+        result,
+        `\n\n---\n\n> ℹ️ Blocker check skipped — start the spex-console dev server to see gating prerequisites for \`${targetId}\`.`,
+      );
+    }
+    return;
+  }
+  const gating = Array.isArray(res.body?.blockers)
+    ? res.body.blockers.filter((b) => b.gating)
+    : [];
+  result.gating_blockers = gating;
+  if (gating.length > 0) {
+    const lines = gating.map(
+      (b) => `- \`${b.id}\` — ${b.name} (status: \`${b.status}\`, ${b.category})`,
+    );
+    const first = gating[0];
+    const doFirst =
+      first && first.status !== 'missing'
+        ? ` **Do this first:** on your confirmation, \`heyspex_pin_set { spec_id: "${first.id}" }\` — a freeze-safe scoped pin change (overlays the snapshot, never rewrites it).`
+        : '';
+    appendToOnDeckPrompts(
+      result,
+      `\n\n---\n\n## ⚠️ Unmet gating prerequisites (${gating.length})\n\n${lines.join('\n')}\n\nThese hard-gate \`${targetId}\` — the same set the console On-Deck overlay shows. Run \`/hs-resolve\` for the full fix brief (Do-this-first / Switch / Defer / Resolve), or clear them before claiming.${doFirst}`,
+    );
+  }
+}
+
+/**
+ * Surface passive stomp-detection warnings on the on-deck brief ([[HS-TASK-FD5O]]).
+ * Reads the same preview endpoint the console would use for a would-be claim.
+ * Best-effort — never blocks the brief when console is unreachable.
+ */
+export async function augmentOnDeckWithStompWarnings(result, args = {}) {
+  if (!result || result.error) return;
+  const targetId =
+    result.claim_target?.spec_id || result.seed_epic?.id || result.spec_id || null;
+  if (!targetId) return;
+
+  const agentProfile =
+    typeof args.agent_profile === 'string' && args.agent_profile.trim()
+      ? args.agent_profile.trim()
+      : undefined;
+  const qs = agentProfile ? `?agent_profile=${encodeURIComponent(agentProfile)}` : '';
+
+  let res;
+  try {
+    res = await consoleFetch(
+      `/api/specs/${encodeURIComponent(targetId)}/stomp-preview${qs}`,
+    );
+  } catch {
+    return;
+  }
+  if (!res.ok) return;
+
+  const warnings = Array.isArray(res.body?.stomp_warnings) ? res.body.stomp_warnings : [];
+  enrichOnDeckWithStompWarnings(result, warnings);
+}
+
+/**
+ * Surface passive identity nudges on the on-deck brief ([[HS-TASK-E4OE]]).
+ * Reads the nudge-preview endpoint. Best-effort — never blocks the brief.
+ */
+export async function augmentOnDeckWithIdentityNudges(result, args = {}) {
+  if (!result || result.error) return;
+  const targetId =
+    result.claim_target?.spec_id || result.seed_epic?.id || result.spec_id || null;
+  if (!targetId) return;
+
+  const agentProfile =
+    typeof args.agent_profile === 'string' && args.agent_profile.trim()
+      ? args.agent_profile.trim()
+      : undefined;
+  const params = new URLSearchParams();
+  if (agentProfile) params.set('agent_profile', agentProfile);
+  const qs = params.toString() ? `?${params.toString()}` : '';
+
+  let res;
+  try {
+    res = await consoleFetch(
+      `/api/specs/${encodeURIComponent(targetId)}/nudge-preview${qs}`,
+    );
+  } catch {
+    return;
+  }
+  if (!res.ok) return;
+
+  const nudges = Array.isArray(res.body?.identity_nudges) ? res.body.identity_nudges : [];
+  enrichOnDeckWithIdentityNudges(result, nudges);
+}
+
+/**
+ * Surface depends_on / same-module serialization hints on the on-deck brief
+ * ([[HS-TASK-55VE]]). Best-effort — never blocks the brief when console is
+ * unreachable.
+ */
+export async function augmentOnDeckWithParallelismHints(result, args = {}) {
+  if (!result || result.error) return;
+  if (args.summary === true || args.summary === 'true') return;
+  const targetId =
+    result.claim_target?.spec_id || result.seed_epic?.id || result.spec_id || null;
+  if (!targetId) return;
+
+  let res;
+  try {
+    res = await consoleFetch(
+      `/api/specs/${encodeURIComponent(targetId)}/parallelism-preview`,
+    );
+  } catch {
+    return;
+  }
+  if (!res.ok) return;
+
+  const hints = Array.isArray(res.body?.parallelism_hints) ? res.body.parallelism_hints : [];
+  enrichOnDeckWithParallelismHints(result, hints);
+}
+
+/**
+ * Attach the pre-computed sprint (token-budgeted work-group) the claim target
+ * lands in, from the SAME `sprintPlan` the console computes once at the
+ * planning/alignment gate (`GET /api/specs/:id/children` →
+ * `spex-console/src/lib/spec-children.ts`'s `buildSpecChildren` /
+ * `computeSprintPlan`) — HS-ARWE (console half) /
+ * [[HS-2IF0-7NZ3-EPIC-token-estimation-and-auto-bundling-for-o]] criteria
+ * 7-9 (MCP half): the sprint decision is surfaced to the agent BEFORE
+ * execution begins, never decided by the implementing agent, and re-derives
+ * only when this brief is re-fetched (the gate re-firing) — never silently
+ * mid-implementation.
+ *
+ * Same best-effort HTTP-augment shape as `augmentOnDeckWithGatingBlockers`:
+ * only runs for a task-grain claim target with a resolvable parent epic id;
+ * console-unreachable, a non-ok response, or no matching sprint sets
+ * `result.sprint = null` and appends no line — never throws, never blocks
+ * the brief. A non-task claim target (or a task with no `parent.id`) is left
+ * completely untouched — no `sprint` key at all.
+ *
+ * `fetchImpl` defaults to the module's real `consoleFetch` (unchanged for
+ * every production call site); tests inject a stub, same DI seam as
+ * `resolveNextResolutionPayload(args, { consoleFetch })` in `next-resolution.mjs`.
+ */
+export async function attachSprintToOnDeck(result, fetchImpl = consoleFetch) {
+  if (!result || result.error) return;
+  const claimTarget = result.claim_target;
+  if (!claimTarget || claimTarget.level !== 'task') return;
+  const parentId = claimTarget.parent?.id;
+  if (!parentId) return;
+
+  let res;
+  try {
+    res = await fetchImpl(`/api/specs/${encodeURIComponent(parentId)}/children`);
+  } catch {
+    result.sprint = null;
+    return;
+  }
+  if (!res.ok) {
+    result.sprint = null;
+    return;
+  }
+
+  const sprintPlan = res.body?.sprintPlan;
+  if (!sprintPlan || !Array.isArray(sprintPlan.sprints)) {
+    result.sprint = null;
+    return;
+  }
+
+  // Same case-insensitive id comparison used throughout this file (e.g. the
+  // `.toLowerCase()` level/status checks above) — the console's task ids and
+  // this brief's claim-target id can differ in case.
+  const targetIdLower = String(claimTarget.spec_id || '').toLowerCase();
+  const matchedSprint = sprintPlan.sprints.find(
+    (s) =>
+      Array.isArray(s.taskIds) &&
+      s.taskIds.some((id) => String(id).toLowerCase() === targetIdLower),
+  );
+  if (!matchedSprint) {
+    result.sprint = null;
+    return;
+  }
+
+  const children = Array.isArray(res.body?.children) ? res.body.children : [];
+  const ownRow = children.find((c) => String(c?.id || '').toLowerCase() === targetIdLower);
+  const estimatedTokens =
+    typeof ownRow?.estimatedTokens === 'number' ? ownRow.estimatedTokens : 0;
+  const position =
+    matchedSprint.taskIds.findIndex((id) => String(id).toLowerCase() === targetIdLower) + 1;
+
+  result.sprint = {
+    index: matchedSprint.index,
+    position,
+    size: matchedSprint.taskIds.length,
+    totalTokens: matchedSprint.totalTokens,
+    budget: sprintPlan.budget,
+    overBudget: matchedSprint.overBudget,
+    taskIds: matchedSprint.taskIds,
+    estimatedTokens,
+  };
+
+  // Re-render the SAME markdown builder (`formatClaimBanner`) with the sprint
+  // now known, and splice it into both prompt fields in place of the
+  // sprint-less banner `enrichOnDeckWithClaimTarget` already embedded
+  // (bookended banner in full mode → two occurrences; summary mode → one).
+  // `.split(...).join(...)` replaces every occurrence, unlike `.replace`.
+  const oldBanner = formatClaimBanner(claimTarget, result.alignment_result || {});
+  const newBanner = formatClaimBanner(claimTarget, result.alignment_result || {}, result.sprint);
+  if (oldBanner && newBanner !== oldBanner) {
+    if (typeof result.user_prompt_markdown === 'string') {
+      result.user_prompt_markdown = result.user_prompt_markdown.split(oldBanner).join(newBanner);
+    }
+    if (typeof result.prompt_markdown === 'string') {
+      result.prompt_markdown = result.prompt_markdown.split(oldBanner).join(newBanner);
+    }
+  }
+}
+
+/** HTTP-backed on-deck augments (gating + stomp + identity nudges + parallelism + sprint). Shared by MCP tool + hs next CLI. */
+/**
+ * The active claims another agent holds right now — the ones that would make
+ * a launch come back `live_claim` ([[HS-3C9M-A4TX-CAP]]). Stale or expired
+ * claims are relaunchable and drop out; the caller's own session's claims drop
+ * out too (re-fetching a brief after claiming must not skip its own task).
+ * @param {Array<Record<string, any>>} claims  GET /api/control/active-claims → claims
+ * @param {string | null | undefined} ownSessionId
+ * @param {number} [nowMs]
+ */
+export function selectClaimsHeldByOthers(claims, ownSessionId, nowMs = Date.now()) {
+  const own = ownSessionId ? String(ownSessionId) : '';
+  const out = [];
+  for (const c of Array.isArray(claims) ? claims : []) {
+    if (!c || typeof c.specId !== 'string' || !c.specId) continue;
+    if (c.effectiveStatus === 'stale') continue;
+    if (c.expiresAt) {
+      const t = Date.parse(c.expiresAt);
+      if (Number.isFinite(t) && nowMs >= t) continue;
+    }
+    const sid = c.sessionId ? String(c.sessionId) : '';
+    const short = c.sessionShort ? String(c.sessionShort) : '';
+    if (own && own !== 'local' && (sid === own || (short && own.startsWith(short)))) continue;
+    out.push(c);
+  }
+  return out;
+}
+
+function claimAgoLabel(iso, nowMs) {
+  const t = Date.parse(String(iso || ''));
+  if (!Number.isFinite(t)) return '';
+  const mins = Math.max(0, Math.round((nowMs - t) / 60000));
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins} min ago`;
+  return `${Math.round(mins / 60)} h ago`;
+}
+
+/**
+ * Markdown appended to the brief: who holds what, which held task(s) this
+ * brief stepped past, and how to put a parallel agent on another task.
+ * Empty when nothing is held.
+ */
+export function renderActiveClaimsSection(held, skipped = [], nowMs = Date.now()) {
+  if (!Array.isArray(held) || held.length === 0) return '';
+  const lines = [
+    '',
+    '---',
+    '',
+    `## 👥 Active claims — ${held.length} spec${held.length === 1 ? '' : 's'} held by other agents`,
+    '',
+  ];
+  for (const c of held) {
+    const who = `${c.agent || 'agent'} · \`${c.sessionShort || String(c.sessionId || '').slice(0, 8) || '?'}\``;
+    const state = c.effectiveStatus || c.status || 'working';
+    const since = c.claimedAt ? ` · claimed ${claimAgoLabel(c.claimedAt, nowMs)}` : '';
+    const active = c.lastActivityAt ? ` · active ${claimAgoLabel(c.lastActivityAt, nowMs)}` : '';
+    lines.push(`- \`${c.specId}\` — ${who} · ${state}${since}${active}`);
+  }
+  lines.push('');
+  if (Array.isArray(skipped) && skipped.length > 0) {
+    lines.push(
+      `Skipped ${skipped.map((c) => `\`${c.specId}\``).join(', ')} (held above) — this brief presents the next task nobody holds, so a parallel agent can start on it.`,
+    );
+  }
+  lines.push(
+    'Put more agents on other unheld tasks any time (`hs next <id> --launch`) — the claim ledger and the dispatcher coordinate between them, and a task already held is refused at launch.',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * `resolveNextOnDeckPayload`, then step past any task another agent actively
+ * holds ([[HS-3C9M-A4TX-CAP]] — owner ruling 2026-09-02: the live-claim refusal
+ * at launch is right, but the brief should offer the next task that CAN be
+ * launched in parallel and list who holds what). Same `{ error, result }`
+ * shape as the sync resolver. Best-effort: a dead console means no claims are
+ * known and the plain result comes back untouched.
+ *
+ * A spec id the operator named directly is never skipped — they asked for
+ * that one — it just carries the held-by note. When every other launchable
+ * task under the walk is held too, the held task is kept with the note.
+ */
+export async function resolveNextOnDeckAroundActiveClaims(
+  vaultRoot,
+  config,
+  args = {},
+  { fetchImpl = consoleFetch, nowMs = Date.now() } = {},
+) {
+  const first = resolveNextOnDeckPayload(vaultRoot, config, args);
+  if (!first || first.error || !first.result) return first;
+
+  let claims = [];
+  try {
+    const res = await fetchImpl('/api/control/active-claims', { timeout: 5000 });
+    if (res?.ok && Array.isArray(res.body?.claims)) claims = res.body.claims;
+  } catch {
+    claims = [];
+  }
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const held = selectClaimsHeldByOthers(claims, identity?.sessionId, nowMs);
+  if (held.length === 0) return first;
+
+  const heldById = new Map(held.map((c) => [String(c.specId).toLowerCase(), c]));
+  const requested = args.spec_id ? String(args.spec_id).toLowerCase() : '';
+  let current = first;
+  const skipped = [];
+  const exclude = [];
+  for (let i = 0; i < 25; i += 1) {
+    const ct = current.result?.claim_target;
+    if (!ct || ct.level !== 'task' || !ct.spec_id) break;
+    const id = String(ct.spec_id).toLowerCase();
+    if (id === requested) break;
+    const holder = heldById.get(id);
+    if (!holder) break;
+    const next = resolveNextOnDeckPayload(vaultRoot, config, {
+      ...args,
+      exclude_spec_ids: [...exclude, id],
+    });
+    const nct = next?.result?.claim_target;
+    if (!next || next.error || !nct || nct.level !== 'task' || !nct.spec_id) break;
+    skipped.push(holder);
+    exclude.push(id);
+    current = next;
+  }
+
+  current.result.active_claims = held;
+  current.result.skipped_held = skipped;
+  appendToOnDeckPrompts(current.result, renderActiveClaimsSection(held, skipped, nowMs));
+  return current;
+}
+
+export async function applyOnDeckHttpAugments(result, args = {}) {
+  await augmentOnDeckWithGatingBlockers(result, args);
+  await augmentOnDeckWithStompWarnings(result, args);
+  await augmentOnDeckWithIdentityNudges(result, args);
+  await augmentOnDeckWithParallelismHints(result, args);
+  await attachSprintToOnDeck(result);
+}
+
+/**
+ * [[HS-T41O-NZ8S-DIAG]]: resolve the session's vault WRITE mode once at the
+ * async handler boundary and thread it in as `__vault_write_mode` so the
+ * synchronous brief composer can route the missing-`summary:` authoring
+ * phase to the console (cloud) or the file (local). Never throws — an
+ * unresolvable mode leaves the arg unset and the composer falls back to the
+ * read-tier / file-on-disk signals.
+ */
+export async function injectVaultWriteMode(args = {}, resolveWriteMode = resolveVaultWriteMode) {
+  if (args.__vault_write_mode === 'cloud' || args.__vault_write_mode === 'local') return args;
+  try {
+    const mode = await resolveWriteMode();
+    if (mode === 'cloud' || mode === 'local') return { ...args, __vault_write_mode: mode };
+  } catch {
+    /* fall through — the composer has its own signals */
+  }
+  return args;
+}
+
+/**
+ * Degrade-don't-die wrapper: when any cloud loader inside the brief fell back
+ * to the local clone ({@link readViaSelector}), the response JSON carries
+ * `degraded: true, source: 'disk', cloud_error, warning` at its top level.
+ */
+export async function handleNextOnDeck(vaultRoot, config, args) {
+  const { value, degraded } = await withDegradationScope(() => handleNextOnDeckInner(vaultRoot, config, args));
+  if (!degraded || !value || value.isError) return value;
+  try {
+    const first = value.content?.[0];
+    const parsed = JSON.parse(first.text);
+    return { ...value, content: [{ ...first, text: JSON.stringify({ ...parsed, ...degraded }, null, 2) }] };
+  } catch {
+    return value;
+  }
+}
+
+async function handleNextOnDeckInner(vaultRoot, config, args) {
+  // Resolve the Neon layer-1 pin first (async), then the frozen milestone
+  // snapshot order (async, [[HS-TASK-JHIA]]), then run the sync resolver with
+  // both threaded in via `neon_pin_spec_id` / `frozen_epic_order`. See
+  // `injectNeonFocusPin` + `injectFrozenMilestoneOrder`.
+  const resolvedArgs = await injectVaultWriteMode(
+    await injectCloudWipState(
+      vaultRoot,
+      await injectFrozenMilestoneOrder(await injectNeonFocusPin(args)),
+    ),
+  );
+
+  // [[HS-DJWP-MCPC-TASK]] "Scheduler cohort + pillar tier map" family: in
+  // cloud reliance, pre-fetch both over HTTP before the synchronous resolver
+  // runs, so it never falls back to `readdirSync`ing `specs/{tasks,epics,
+  // milestones,diagnoses}` / `specs/pillars` (which a no-vault-checkout
+  // session cannot do). Skipped for the direct spec_id lookup path (it never
+  // calls computeGlobalSchedulerOrder). A dead console here is the ONE
+  // decision point (readViaSelector, inside the *ViaTier loaders) surfacing
+  // CONSOLE_UNREACHABLE_CLOUD_MODE — never a silent disk fallback.
+  let cloudArgs = resolvedArgs;
+  if (!resolvedArgs.spec_id) {
+    const tier = await resolveReadTier();
+    if (tier === 'neon') {
+      const consoleUrl = effectiveConsoleUrl();
+      try {
+        const [schedulerRows, pillarTierById] = await Promise.all([
+          loadVaultSpecsForSchedulerViaTier(vaultRoot, { tier, consoleUrl }),
+          loadPillarTierMapViaTier(vaultRoot, { tier, consoleUrl }),
+        ]);
+        cloudArgs = {
+          ...resolvedArgs,
+          __cloud_scheduler_rows: schedulerRows,
+          __cloud_pillar_tier_by_id: pillarTierById,
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              error: err instanceof ConsoleUnreachableCloudModeError ? err.name : 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+              message: String(err?.message ?? err),
+            }),
+          }],
+        };
+      }
+    }
+  } else {
+    // [[HS-DJWP-MCPC-TASK]] round 2, AC1 "general spec load": the direct
+    // `spec_id` lookup branch of `resolveNextOnDeckPayload` takes the SAME
+    // pre-fetch-and-inject treatment as the scheduler cohort above — see
+    // `__cloud_direct_spec` there for why that branch can't be made async
+    // directly. Once the spec is known, also pre-fetch design-memory
+    // decisions when its tags trigger them (`__cloud_design_decisions`,
+    // best-effort per `loadDesignMemoriesViaTier`).
+    //
+    // [[HS-H227-MCPC-TASK]]: `deriveTaskBrief`'s decomposition context
+    // (`extractDecompositionContext`'s `loadRef` — related links, the
+    // parent-epic/milestone climb + milestone siblings) and
+    // `enrichOnDeckWithClaimTarget`'s parent-contract lookup (same `loadTask`
+    // shape) ALSO get the pre-fetch-and-inject treatment here —
+    // `prefetchCloudTaskGraph` walks that bounded closure over HTTP and the
+    // result rides in as `__cloud_task_graph`, consulted by
+    // `loadTaskViaGraph` instead of `loadTask` at those two sites. The
+    // readiness-floor settings file stays disk-only (machine-local per the
+    // epic rule) — not part of this pre-fetch.
+    const tier = await resolveReadTier();
+    if (tier === 'neon') {
+      const consoleUrl = effectiveConsoleUrl();
+      try {
+        const directSpec = await loadSpecByIdViaTier(vaultRoot, resolvedArgs.spec_id, { tier, consoleUrl });
+        cloudArgs = { ...resolvedArgs, __cloud_direct_spec: directSpec };
+        if (directSpec) {
+          const uiTags = detectUITags(directSpec.frontmatter || {});
+          if (uiTags.length > 0) {
+            cloudArgs.__cloud_design_decisions = await loadDesignMemoriesViaTier(vaultRoot, uiTags, { tier, consoleUrl });
+          }
+          cloudArgs.__cloud_task_graph = await prefetchCloudTaskGraph(vaultRoot, resolvedArgs.spec_id, directSpec, {
+            tier,
+            consoleUrl,
+          });
+        }
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              error: err instanceof ConsoleUnreachableCloudModeError ? err.name : 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+              message: String(err?.message ?? err),
+            }),
+          }],
+        };
+      }
+    }
+  }
+
+  const { error, result } = await resolveNextOnDeckAroundActiveClaims(vaultRoot, config, cloudArgs);
+
+  if (error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(error) }],
+    };
+  }
+
+  // One detection path (RSSO §5): surface the same gating prereqs as the console
+  // overlay. Best-effort — never breaks the brief if console is unreachable.
+  await applyOnDeckHttpAugments(result, resolvedArgs);
+  await attachConsoleStatusToOnDeck(result);
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export function nextReviewDeps() {
+  return { findSpecFile, loadSpec, loadRoadmap, loadTask };
+}
+
+export function handleNextReview(vaultRoot, config, args) {
+  const { error, result } = resolveNextReviewPayload(
+    vaultRoot,
+    config,
+    args,
+    nextReviewDeps(),
+  );
+
+  if (error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(error) }],
+    };
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/**
+ * heyspex_next_resolution — the agent face of the Resolution lane. HTTP-only:
+ * the resolver reads the console aggregator (the one detection path) via
+ * consoleFetch; we never re-detect here. Async because consoleFetch is async —
+ * the dispatch switch is sync but its caller awaits returned Promises.
+ */
+export async function handleNextResolution(args = {}) {
+  const { error, result } = await resolveNextResolutionPayload(args, { consoleFetch });
+  if (error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(error, null, 2) }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/**
+ * Live console liveness stamped on every /hs-next response so agents cannot
+ * infer "server down" from conditional failure_modes alone. Uses the same
+ * transport as claim/file_spec (fetch → /api/version).
+ */
+export async function attachConsoleStatusToOnDeck(result) {
+  if (!result || result.error) return;
+  try {
+    const probe = await consoleFetch('/api/version', { timeout: 4000 });
+    let url = effectiveConsoleUrl();
+    if (probe.url) {
+      try {
+        url = new URL(probe.url).origin;
+      } catch {
+        // keep effectiveConsoleUrl() fallback
+      }
+    }
+    const consoleStatus = {
+      reachable: probe.ok,
+      url,
+      checked_at: new Date().toISOString(),
+      ...(probe.ok
+        ? {}
+        : {
+            error_code: consoleErrorCode(probe, 'CONSOLE_PROBE_FAILED'),
+            error: probe.error || null,
+          }),
+    };
+    result.console_status = consoleStatus;
+    if (result.agent_dispatch && typeof result.agent_dispatch === 'object') {
+      result.agent_dispatch.console_status = consoleStatus;
+      result.agent_dispatch.console_connectivity_note = probe.ok
+        ? 'Console was reachable when this brief was built — do NOT tell the user the dev server is down unless a tool call returns CONSOLE_UNREACHABLE after this timestamp.'
+        : 'Console probe failed when this brief was built — call heyspex_dev_server_status before claiming the server is down.';
+    }
+  } catch {
+    result.console_status = {
+      reachable: false,
+      checked_at: new Date().toISOString(),
+      error: 'probe_exception',
+    };
+  }
+}
+
+/**
+ * [[HS-TASK-JHIA]] — pre-fetch the FROZEN milestone snapshot from the console
+ * (Neon-sourced) at the async handler boundary, mirroring `injectNeonFocusPin`.
+ *
+ * The vendor cli has no Neon client, so the frozen epic order can only arrive
+ * over HTTP. We resolve the active milestone server-side via the `active`
+ * sentinel and thread the frozen epic order into args as `frozen_epic_order`, so
+ * the sync resolver reorders the milestone-drill candidate epics by it — making
+ * `/hs-next`'s seed epic agree with the console What's Next / On Deck surfaces.
+ *
+ * Best-effort: a disabled flag (`{ enabled: false }`), missing snapshot, or an
+ * unreachable console leaves the order unset and `/hs-next` keeps live scheduler
+ * order — the honest `CONSOLE_UNREACHABLE` degradation ([[HS-TASK-JHIA]] AC #2).
+ * No `.heyspex/*` file fallback is ever consulted ([[no-fallbacks-by-default]]).
+ */
+export async function injectFrozenMilestoneOrder(args = {}) {
+  if (args.ignore_focus === true || args.ignore_focus === 'true') return args;
+  if (args.spec_id) return args;
+  let res;
+  try {
+    res = await consoleFetch('/api/scheduler/milestone-snapshot/active');
+  } catch {
+    return args; // unreachable → live order
+  }
+  if (!res || !res.ok || !res.body || res.body.enabled !== true) return args;
+  const snapshot = res.body.snapshot;
+  if (!snapshot || !Array.isArray(snapshot.epicOrder)) return args;
+  const frozen = snapshot.epicOrder
+    .slice()
+    .sort((a, b) => (a.position ?? 0) - (b.position ?? 0))
+    .map((e) => e.epic_id)
+    .filter((id) => typeof id === 'string' && id.length > 0);
+  const appended = snapshot.appendedAfterSnapshot?.epics;
+  if (Array.isArray(appended)) {
+    for (const id of appended) {
+      if (typeof id === 'string' && id.length > 0) frozen.push(id);
+    }
+  }
+  if (frozen.length === 0) return args;
+  return { ...args, frozen_epic_order: frozen };
+}
+
+/**
+ * heyspex_suggest_pillar — rank the pillar taxonomy against a draft spec.
+ *
+ * Thin relay over POST /api/pillars/suggest (the console owns the charter corpus and the
+ * scorer). Read-only by construction: there is no code path from here to creating a
+ * pillar, because a pillar is a permanent taxonomy change that only the owner approves
+ * ([[pillar-assignment-protocol]] §"Proposing a new pillar").
+ */
+export async function handleSuggestPillar(args = {}) {
+  const subject = [args.subject, args.name, args.summary, Array.isArray(args.tags) ? args.tags.join(' ') : '']
+    .filter((v) => typeof v === 'string' && v.trim())
+    .join(' ')
+    .trim();
+  if (!subject) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'INVALID_ARGS',
+          message: 'Pass the draft spec\'s `name` (ideally with `summary` and `tags`), or a freeform `subject`. Scoring needs the spec\'s own words.',
+        }, null, 2),
+      }],
+    };
+  }
+
+  const result = await consoleFetch('/api/pillars/suggest', {
+    method: 'POST',
+    body: {
+      name: typeof args.name === 'string' ? args.name : undefined,
+      summary: typeof args.summary === 'string' ? args.summary : undefined,
+      tags: Array.isArray(args.tags) ? args.tags : undefined,
+      subject: typeof args.subject === 'string' ? args.subject : undefined,
+      shortlist: typeof args.shortlist === 'number' ? args.shortlist : undefined,
+    },
+  });
+  if (!result.ok) {
+    const payload = await enrichConsoleFailurePayloadAsync(result, {
+      error: consoleErrorCode(result, 'SUGGEST_PILLAR_FAILED'),
+      message: consoleErrorMessage(result, `POST /api/pillars/suggest returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+    });
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(result.body, null, 2) }] };
+}
+
+/**
+ * Execute one cross-milestone prerequisite resolution path — [[HS-EPIC-QQBD]].
+ * POST /api/focus/prereq with the chosen `path` (do_first | switch_milestone |
+ * move_in | dispatch | defer). The console owns the deterministic execution; this
+ * tool is the agent-facing face. Success → { ok: true, result }; failures
+ * (including the 409 confirmation_required case for an unconfirmed move_in) pass
+ * the console error body straight through via controlError.
+ */
+export async function handleResolvePrerequisite(args = {}) {
+  const body = {
+    blocked_id: args.blocked_id,
+    prereq_id: args.prereq_id,
+    path: args.path,
+    actor: 'agent',
+    ...(args.auto_return !== undefined ? { auto_return: args.auto_return } : {}),
+    ...(args.confirm !== undefined ? { confirm: args.confirm } : {}),
+    ...(args.prereq_milestone_id !== undefined
+      ? { prereq_milestone_id: args.prereq_milestone_id }
+      : {}),
+    ...(args.blocked_milestone_id !== undefined
+      ? { blocked_milestone_id: args.blocked_milestone_id }
+      : {}),
+    ...(args.return_to !== undefined ? { return_to: args.return_to } : {}),
+  };
+  const result = await consoleFetch('/api/focus/prereq', { method: 'POST', body });
+  if (!result.ok) {
+    return controlError(result, 'PREREQ_RESOLVE_FAILED', {
+      blocked_id: args.blocked_id,
+      prereq_id: args.prereq_id,
+      path: args.path,
+    });
+  }
+  return controlOk(result.body);
+}
+
+export const MEMORY_BASELINE_TAGS = ['feedback', 'decision', 'architecture', 'saas'];
+
+export const MEMORY_INJECTION_LIMIT = 5;
+
+export const MEMORY_DESCRIPTION_TRUNCATE = 300;
+
+/**
+ * Detect that a memory's body carries an amendment/deprecation BELOW the part
+ * recall shows, so the surfaced summary can be flagged as possibly-stale.
+ *
+ * Returns a short label naming what was found (e.g. "Amendment 2026-07-02 —
+ * deprecated as a general architecture principle"), or '' when the memory reads
+ * the same all the way down.
+ *
+ * Only content *after* the shown summary counts: a memory whose opening
+ * paragraph already says it was superseded is not misleading, and flagging it
+ * would be noise.
+ */
+export function detectMemoryAmendment(body, shownDescription) {
+  try {
+    const shownEnd = shownDescription
+      ? body.indexOf(shownDescription.slice(0, 60))
+      : -1;
+    const tail = shownEnd >= 0 ? body.slice(shownEnd + 1) : body;
+    // Headings first — they carry the most precise label. A memory can have
+    // several (an amendment that narrows it, then a later one that retires it);
+    // surface the most severe, since "deprecated" changes whether the memory
+    // applies at all while "extended" only changes its edges.
+    const headings = [...tail.matchAll(/^#{1,6}\s*((?:Amendment|Addendum|Superseded|Deprecat)[^\n]*)$/gim)].map(
+      (m) => m[1].trim().replace(/\s+/g, ' ').slice(0, 120),
+    );
+    if (headings.length > 0) {
+      const retiring = headings.find((h) => /deprecat|supersed|retire|no longer/i.test(h));
+      return retiring ?? headings[headings.length - 1];
+    }
+    // Otherwise look for retirement language in prose.
+    if (/\b(?:no longer governs|is deprecated|now deprecated|superseded by|has been superseded|retired as)\b/i.test(tail)) {
+      return 'amended/superseded later in body';
+    }
+    return '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Score vault memories by tag-overlap with a primary tag set + baseline pool.
+ * Returns the top-K memories as `{ source, name, link, description, score }`
+ * entries. Source is always "vault" for now (specs/memory/); agent-local
+ * memory injection is Phase 2.
+ *
+ * Deterministic: same inputs → same output ordering (sort is stable by
+ * score-desc then name-asc), so the prompt cache stays warm on identical calls.
+ */
+export function scoreRelevantMemories(vaultRoot, options = {}) {
+  const primaryTags = Array.isArray(options.primaryTags) ? options.primaryTags : [];
+  const baselineTags = Array.isArray(options.baselineTags)
+    ? options.baselineTags
+    : MEMORY_BASELINE_TAGS;
+  const limit = Number.isInteger(options.limit) && options.limit > 0
+    ? options.limit
+    : MEMORY_INJECTION_LIMIT;
+
+  const memoryDir = join(vaultRoot, 'specs', 'memory');
+  if (!existsSync(memoryDir)) return { header: null, items: [] };
+
+  // Lower-case query set for case-insensitive overlap.
+  const querySet = new Set(
+    [...primaryTags, ...baselineTags].map((t) => String(t).toLowerCase()),
+  );
+  if (querySet.size === 0) return { header: null, items: [] };
+
+  const subdirs = ['lessons', 'decisions', 'references', 'ui-patterns'];
+  const candidates = [];
+
+  for (const sub of subdirs) {
+    const catDir = join(memoryDir, sub);
+    if (!existsSync(catDir)) continue;
+    const files = readdirSync(catDir).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+      try {
+        const content = readFileSync(join(catDir, file), 'utf8');
+        const { frontmatter, body } = parseFrontmatter(content);
+        const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+        if (tags.length === 0) continue;
+        const tagSet = new Set(tags.map((t) => String(t).toLowerCase()));
+        let score = 0;
+        for (const q of querySet) if (tagSet.has(q)) score += 1;
+        if (score === 0) continue;
+        const slug = file.replace(/\.md$/, '');
+        const name = frontmatter.name || frontmatter.id || slug;
+        let description = extractSummary(body);
+        if (description.length > MEMORY_DESCRIPTION_TRUNCATE) {
+          description = description.slice(0, MEMORY_DESCRIPTION_TRUNCATE - 1) + '…';
+        }
+        // Amendment awareness. Recall shows only the opening paragraph, so a
+        // memory later amended or deprecated is surfaced by its ORIGINAL claim
+        // — the reverse of what is in force. That is not hypothetical:
+        // [[local-first-applies-beyond-storage]] opens with "we always choose
+        // local first" and, 30 lines below the truncation point, carries
+        // "Amendment 2026-07-02 — deprecated as a general architecture
+        // principle". An agent applying the recalled summary would apply a rule
+        // the owner retired ([[HS-GIXC-CAP-KPZT-heyspex-should-actively-detect-and-preve]]).
+        const amended = detectMemoryAmendment(body, description);
+        if (amended) {
+          description = `${description} ⚠ ${amended} — this summary may not reflect the current ruling; READ THE FULL BODY before applying.`;
+        }
+        candidates.push({
+          source: 'vault',
+          name,
+          link: `[[${slug}]]`,
+          description,
+          amended: amended || undefined,
+          score,
+        });
+      } catch {
+        // Skip unparseable files.
+      }
+    }
+  }
+
+  candidates.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.name.localeCompare(b.name);
+  });
+
+  return {
+    header: 'Retrieved from prior sessions. Apply at decision points; do not echo verbatim.',
+    items: candidates.slice(0, limit),
+  };
+}
+
+/**
+ * Surface a `recalled_memories` block on the /hs-next response so the agent
+ * reads the relevant prior-session lessons without having to remember to call
+ * heyspex_recall_memories itself ([[HS-TASK-IMMF]] Part A). Scoring uses the
+ * claimed spec's tags as the primary signal + the baseline pool — so memories
+ * about rule placement, SaaS template cost, etc. always rank as candidates
+ * regardless of which spec is on deck.
+ *
+ * Display-only — never gates. Skipped in summary mode (the full call refetches).
+ */
+export function enrichOnDeckWithRecalledMemories(vaultRoot, result, args = {}) {
+  if (!result || result.error) return result;
+  if (args.ignore_memories === true || args.ignore_memories === 'true') return result;
+
+  // Derive the claimed spec's tags. The full response carries the spec frontmatter
+  // through under different keys depending on the path (direct lookup vs scheduler);
+  // fall back to the breadcrumb's leaf id and load the spec on disk if needed.
+  let primaryTags = [];
+  const candidatePaths = [result.spec_path, result.spec_id ? findSpecFile(vaultRoot, result.spec_id) : null].filter(Boolean);
+  for (const p of candidatePaths) {
+    try {
+      const spec = typeof p === 'string' ? loadSpec(vaultRoot, p) : null;
+      if (spec?.frontmatter?.tags && Array.isArray(spec.frontmatter.tags)) {
+        primaryTags = spec.frontmatter.tags;
+        break;
+      }
+    } catch {
+      // Continue to next candidate.
+    }
+  }
+
+  const recalled = scoreRelevantMemories(vaultRoot, { primaryTags });
+  if (!recalled.items.length) return result;
+
+  return { ...result, recalled_memories: recalled };
+}