heyspex 0.2.0 → 0.2.2

package/vendor/heyspex-mcp/vault-io.mjs

@@ -1,724 +1,720 @@
-// Vault file IO shared by every tool: frontmatter/YAML parsing, spec-file
-// resolution by id / file key / crosswalk, and the tier-aware spec loaders.
-// Extracted from cli.mjs under
-// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
-//
-// Read-path selector ([[HS-DJWP-MCPC-TASK-wire-the-mcp-server-s-vault-reads]] of
-// [[HS-T6GS-MCPC-EPIC-mcp-server-reads-the-vault-through-the]]): the ONE tier
-// decision point every wired vault read below goes through. Tier is resolved
-// fresh per tool invocation (never cached at module scope) so a dev-mode file
-// edited between calls takes effect on the very next call.
-
-import { join } from 'node:path';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { alternateOrderingBasename, fileKeyFromBasename, parseSpecId } from './spec-id-lib.mjs';
-import { readViaSelector } from './read-path.mjs';
-import { consoleFetch } from './console-transport.mjs';
-
-export function parseFrontmatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return { frontmatter: {}, body: content };
-
-  const yamlBlock = match[1];
-  const body = content.slice(match[0].length).trim();
-  const frontmatter = parseSimpleYaml(yamlBlock);
-
-  return { frontmatter, body };
-}
-
-export function parseSimpleYaml(yaml) {
-  const result = {};
-  const lines = yaml.split(/\r?\n/);
-  let currentKey = null;
-  let currentArray = null;
-  let inNestedObject = false;
-  let nestedKey = null;
-  let nestedArray = null;
-  // Block-scalar collection state (`key: |` / `key: >`). The vast majority of
-  // authored `summary:` values in this vault are literal block scalars, so the
-  // claim brief must read them as strings — not silently drop them to `[]`,
-  // which made the /hs-next card fall into the "author a summary" path for any
-  // spec whose summary was a block scalar. [[HS-TASK-ECOI]]
-  let blockKey = null;
-  let blockLines = null;
-  let blockFold = false;
-
-  const flushBlock = () => {
-    if (blockKey === null) return;
-    const contentful = blockLines.filter((l) => l.trim() !== '');
-    const minIndent = contentful.length
-      ? Math.min(...contentful.map((l) => l.match(/^(\s*)/)[1].length))
-      : 0;
-    const stripped = blockLines.map((l) => l.slice(minIndent));
-    result[blockKey] = blockFold
-      ? stripped.map((l) => l.trim()).filter(Boolean).join(' ')
-      : stripped.join('\n').replace(/\n+$/, '');
-    blockKey = null;
-    blockLines = null;
-    blockFold = false;
-  };
-
-  for (const line of lines) {
-    // Collect an active block scalar: blank or indented lines belong to it; a
-    // line at the key column ends it and is parsed normally below.
-    if (blockKey !== null) {
-      if (line.trim() === '' || /^\s/.test(line)) {
-        blockLines.push(line);
-        continue;
-      }
-      flushBlock();
-    }
-
-    // Skip empty lines and comments
-    if (!line.trim() || line.trim().startsWith('#')) continue;
-
-    // Detect array item under a key
-    const arrayItemMatch = line.match(/^(\s+)-\s*(.*)$/);
-    if (arrayItemMatch && currentArray !== null) {
-      const indent = arrayItemMatch[1].length;
-      const value = arrayItemMatch[2].trim().replace(/^["']|["']$/g, '');
-      if (indent <= 2 && currentArray) {
-        currentArray.push(value);
-      } else if (nestedArray) {
-        nestedArray.push(value);
-      }
-      continue;
-    }
-
-    // Detect nested object key (e.g., roadmap_manifest:)
-    const nestedKeyMatch = line.match(/^(\s{2,})(\w+):\s*(.*)$/);
-    if (nestedKeyMatch && inNestedObject) {
-      const key = nestedKeyMatch[2];
-      const value = nestedKeyMatch[3].trim();
-      if (value) {
-        if (!result[nestedKey]) result[nestedKey] = {};
-        result[nestedKey][key] = parseYamlValue(value);
-      }
-      continue;
-    }
-
-    // Detect top-level key
-    const keyMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/);
-    if (keyMatch) {
-      const key = keyMatch[1];
-      const value = keyMatch[2].trim();
-
-      currentArray = null;
-      inNestedObject = false;
-      nestedKey = null;
-      nestedArray = null;
-
-      if (/^[|>][-+\d]*$/.test(value)) {
-        // Block scalar (`|`, `>`, or a header variant like `|-`/`>+`/`|2`):
-        // collect the indented continuation lines into a string value.
-        currentKey = key;
-        blockKey = key;
-        blockLines = [];
-        blockFold = value.startsWith('>');
-        result[key] = '';
-      } else if (value === '') {
-        // Could be array, nested object, or multiline
-        currentKey = key;
-        result[key] = [];
-        currentArray = result[key];
-      } else if (value.startsWith('[') && value.endsWith(']')) {
-        // Inline array
-        result[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
-      } else {
-        result[key] = parseYamlValue(value);
-      }
-
-      // Check if this is roadmap_manifest (needs special handling)
-      if (key === 'roadmap_manifest') {
-        inNestedObject = true;
-        nestedKey = key;
-        result[key] = {};
-      }
-
-      // `pin:` is a nested object ({ spec_id, pinned_at, expires_at, pinned_by })
-      // written by the console pin writer (`POST /api/pin`). Without
-      // this, parseSimpleYaml only descends into roadmap_manifest, so an empty
-      // `pin:` value parses to an array and the modern pin block is invisible to
-      // /hs-next — every focus reader downstream (getPinnedSpecIdFromFocus, the
-      // milestone/epic drill) sees no pin and falls through to scheduler_default.
-      // Guarded on empty value so a scalar `pin:` elsewhere is unaffected.
-      if (key === 'pin' && value === '') {
-        inNestedObject = true;
-        nestedKey = key;
-        result[key] = {};
-        currentArray = null;
-      }
-    }
-  }
-
-  // Flush a block scalar that ran to the end of the frontmatter.
-  flushBlock();
-
-  // Handle roadmap_manifest specially - re-parse with full YAML support
-  if (result.roadmap_manifest !== undefined) {
-    result.roadmap_manifest = parseRoadmapManifest(yaml);
-  }
-
-  return result;
-}
-
-export function parseRoadmapManifest(yaml) {
-  // Find roadmap_manifest block and parse it more carefully
-  const manifestMatch = yaml.match(/roadmap_manifest:\s*\r?\n([\s\S]*?)(?=\r?\n\w|\r?\n$|$)/);
-  if (!manifestMatch) return {};
-
-  const manifestBlock = manifestMatch[1];
-  const manifest = { phases: [], initiatives: [], horizon: [] };
-
-  // Parse version and default
-  const versionMatch = manifestBlock.match(/version:\s*(\d+)/);
-  if (versionMatch) manifest.version = parseInt(versionMatch[1], 10);
-
-  const defaultMatch = manifestBlock.match(/default:\s*(true|false)/);
-  if (defaultMatch) manifest.default = defaultMatch[1] === 'true';
-
-  // Parse phases
-  const phasesMatch = manifestBlock.match(/phases:\s*\r?\n([\s\S]*?)(?=\r?\n\s{2}\w|\r?\n\s{2}-\s*id:.*initiatives|\r?\n\s{2}initiatives:|\r?\n\s{2}horizon:|$)/);
-  if (phasesMatch) {
-    const phasesBlock = phasesMatch[1];
-    const phaseBlocks = phasesBlock.split(/\r?\n\s{4}- id:/);
-
-    for (let i = 0; i < phaseBlocks.length; i++) {
-      const block = (i === 0 ? phaseBlocks[i].replace(/^\s*- id:/, '') : phaseBlocks[i]).trim();
-      if (!block) continue;
-
-      const phase = { tasks: [] };
-
-      const idMatch = block.match(/^(\S+)/);
-      if (idMatch) phase.id = idMatch[1];
-
-      const nameMatch = block.match(/name:\s*(.+)/);
-      if (nameMatch) phase.name = nameMatch[1].trim();
-
-      const summaryMatch = block.match(/summary:\s*(.+)/);
-      if (summaryMatch) phase.summary = summaryMatch[1].trim();
-
-      // Parse tasks array
-      const tasksMatch = block.match(/tasks:\s*\r?\n([\s\S]*?)(?=\r?\n\s{4}- id:|$)/);
-      if (tasksMatch) {
-        const taskLines = tasksMatch[1].match(/^\s*- (\S+)/gm);
-        if (taskLines) {
-          phase.tasks = taskLines.map(t => t.replace(/^\s*- /, '').trim());
-        }
-      }
-
-      if (phase.id) manifest.phases.push(phase);
-    }
-  }
-
-  // Parse initiatives
-  const initiativesMatch = manifestBlock.match(/initiatives:\s*\r?\n([\s\S]*?)(?=\r?\n\s{2}\w|$)/);
-  if (initiativesMatch) {
-    const initLines = initiativesMatch[1].match(/^\s*- (\S+)/gm);
-    if (initLines) {
-      manifest.initiatives = initLines.map(t => t.replace(/^\s*- /, '').trim());
-    }
-  }
-
-  // Parse horizon
-  const horizonMatch = manifestBlock.match(/horizon:\s*\r?\n([\s\S]*?)(?=\r?\n\w|$)/);
-  if (horizonMatch) {
-    const horizonLines = horizonMatch[1].match(/^\s*- (\S+)/gm);
-    if (horizonLines) {
-      manifest.horizon = horizonLines.map(t => t.replace(/^\s*- /, '').trim());
-    }
-  }
-
-  return manifest;
-}
-
-export function parseYamlValue(value) {
-  if (value === 'true') return true;
-  if (value === 'false') return false;
-  if (value === 'null' || value === '~') return null;
-  if (/^-?\d+$/.test(value)) return parseInt(value, 10);
-  if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
-  return value.replace(/^["']|["']$/g, '');
-}
-
-export function loadSpec(vaultRoot, specPath) {
-  const fullPath = join(vaultRoot, specPath);
-  if (!existsSync(fullPath)) return null;
-
-  const content = readFileSync(fullPath, 'utf-8');
-  return parseFrontmatter(content);
-}
-
-// Raw, single-ordering resolver: locate a spec file whose basename (or
-// frontmatter id) matches `specId` exactly as given. The dual-read wrapper
-// `findSpecFile` calls this once per candidate ordering.
-export function resolveSpecFileRaw(vaultRoot, specId) {
-  // Check exact filename matches first
-  const locations = [
-    `specs/tasks/${specId}.md`,
-    `specs/epics/${specId}.md`,
-    `specs/milestones/${specId}.md`,
-    `specs/roadmaps/${specId}.md`,
-    `specs/research/${specId}.md`,
-    `specs/reviews/${specId}.md`,
-    `specs/adr/${specId}.md`,
-    `specs/${specId}.md`,
-  ];
-  // CAP is family-keyed (dual-read via parseSpecId); IDEA is not reordered, so it
-  // stays a type-first prefix check ([[HS-EPIC-DLE3]]).
-  if (parseSpecId(specId)?.typeLabel === 'CAP' || /^HS-IDEA-/i.test(specId)) {
-    for (const bucket of ['captures', 'ideas']) {
-      const bucketDir = join(vaultRoot, 'specs', bucket);
-      if (!existsSync(bucketDir)) continue;
-      try {
-        for (const file of readdirSync(bucketDir)) {
-          if (file.startsWith(specId) && file.endsWith('.md')) {
-            return join('specs', bucket, file);
-          }
-        }
-      } catch {
-        /* ignore */
-      }
-    }
-  }
-
-  for (const loc of locations) {
-    const fullPath = join(vaultRoot, loc);
-    if (existsSync(fullPath)) return loc;
-  }
-
-  // Search in specs directories by filename prefix. Vault root (`specs/`) is
-  // scanned via a sentinel that the helpers treat as a flat .md walk (no
-  // subdir recursion) so foundational specs (heyspex-north-star, etc.) and
-  // adr/ entries resolve from [[wikilinks]]. [[HS-TASK-NWLR]]
-  //
-  // Ambiguity guard ([[HS-68XO-DIAG]] / vault-id-assignment-protocol §Shared-suffix
-  // families, same contract as [[HS-QEBP-TASK]]): a bare shared-family token
-  // (e.g. `HS-W6AD-TASK` when six sibling tasks all carry that id) matches MORE
-  // THAN ONE basename at a token boundary. Picking the first in readdir order
-  // silently targets the wrong sibling (the diagnosed claim/scheduler bug), so we
-  // collect ALL matches and resolve only when exactly one exists — >1 returns null
-  // (ambiguous → surfaces upstream rather than guessing). A full basename already
-  // returned via the exact-path check above, so it never reaches this scan.
-  const specDirs = ['specs/tasks', 'specs/epics', 'specs/milestones', 'specs/diagnoses', 'specs/roadmaps', 'specs/research', 'specs/reviews', 'specs/captures', 'specs/ideas', 'specs/adr', 'specs'];
-  const matchesAtBoundary = (file) =>
-    file.endsWith('.md') && (file === `${specId}.md` || file.startsWith(`${specId}-`));
-
-  const prefixMatches = new Set();
-  for (const dir of specDirs) {
-    const dirPath = join(vaultRoot, dir);
-    if (!existsSync(dirPath)) continue;
-    try {
-      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
-        if (entry.isFile() && matchesAtBoundary(entry.name)) {
-          prefixMatches.add(join(dir, entry.name));
-        }
-      }
-    } catch {
-      // Directory doesn't exist or isn't readable
-    }
-  }
-  if (prefixMatches.size === 1) return [...prefixMatches][0];
-  if (prefixMatches.size > 1) return null; // ambiguous bare family token — do not guess
-
-  // Search by frontmatter id field (handles filename != id cases). Same
-  // exactly-one rule: a shared id carried by >1 sibling is ambiguous → null.
-  const idMatches = new Set();
-  for (const dir of specDirs) {
-    const dirPath = join(vaultRoot, dir);
-    if (!existsSync(dirPath)) continue;
-    try {
-      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
-        if (!entry.isFile()) continue;
-        const file = entry.name;
-        if (!file.endsWith('.md')) continue;
-        const filePath = join(dir, file);
-        const content = readFileSync(join(vaultRoot, filePath), 'utf-8');
-        const { frontmatter } = parseFrontmatter(content);
-        if (frontmatter.id === specId) idMatches.add(filePath);
-      }
-    } catch {
-      // Skip files that can't be read
-    }
-  }
-  if (idMatches.size === 1) return [...idMatches][0];
-  return null; // 0 → not found; >1 → ambiguous shared-family id
-}
-
-// Dual-read spec resolver ([[HS-EPIC-6SNQ-dual-read-resolver-grace-period-for-pipe]],
-// Phase 1 of [[HS-MIL-KY1F-pipeline-first-spec-identifier-format-mi]]).
-//
-// During the format migration grace window the on-disk basenames are in ONE
-// ordering at a time (type-first today, family-first after the bulk rename), but
-// callers may pass either. Resolve the input as-given first; on a miss, flip the
-// ordering once and retry, logging the legacy/cross-ordering hit to stderr so the
-// sunset gate can count residual legacy references. Family-first input that hits
-// directly never touches the fallback (no log).
-export function findSpecFile(vaultRoot, specId) {
-  const direct = resolveSpecFileRaw(vaultRoot, specId);
-  if (direct) return direct;
-
-  const alt = alternateOrderingBasename(specId);
-  if (alt) {
-    const hit = resolveSpecFileRaw(vaultRoot, alt);
-    if (hit) {
-      process.stderr.write?.(
-        `[heyspex-mcp dual-read] resolved "${specId}" via alternate ordering "${alt}" → ${hit}\n`,
-      );
-      return hit;
-    }
-  }
-
-  // File-key tier ([[HS-ANWD-RHIB-TASK]], parity with the console resolver's
-  // buildSpecLookup priority: file key above basename fallbacks). Extract a
-  // candidate key from the query — a bare `HS-<key>` citation or the era-aware
-  // key of a full basename — and match it against every spec's frontmatter
-  // `file_id:` / basename-derived key, in ANY of the three era orderings
-  // (era-1/2 keys sit mid-basename, so the prefix scan above never finds them).
-  const byKey = resolveSpecFileByFileKey(vaultRoot, specId);
-  if (byKey) return byKey;
-
-  // Crosswalk tier: after the step-4 vault-wide rename, retired basenames/ids
-  // live in .heyspex/id-crosswalk.json → re-resolve to the surviving name.
-  const viaCrosswalk = resolveSpecFileViaCrosswalk(vaultRoot, specId);
-  if (viaCrosswalk) return viaCrosswalk;
-
-  return null;
-}
-
-// Directories the file-key tier scans — superset mirror of the specDirs list in
-// resolveSpecFileRaw (kept separate so that function stays untouched).
-export const FILE_KEY_SCAN_DIRS = ['specs/tasks', 'specs/epics', 'specs/milestones', 'specs/diagnoses', 'specs/roadmaps', 'specs/research', 'specs/reviews', 'specs/captures', 'specs/ideas', 'specs/adr', 'specs'];
-
-/** Bare `HS-<fileKey>` citation → the key; else the era-aware key of a full basename; else null. */
-export function fileKeyCandidateFromQuery(specId) {
-  const trimmed = String(specId ?? '').trim().replace(/\.md$/i, '');
-  const bare = /^HS-((?=[0-9]*[A-Z])[A-Z0-9]{4,})$/.exec(trimmed);
-  if (bare) return bare[1];
-  return fileKeyFromBasename(trimmed);
-}
-
-/**
- * Resolve a spec by its per-file FILE KEY across all three era orderings.
- * Frontmatter `file_id:` is the SSOT (a lazily-minted key may exist only
- * there), with the basename-derived key as the cheap first check. Fail-closed
- * on ambiguity: >1 match returns null and names the colliding candidates on
- * stderr — never guess ([[vault-id-assignment-protocol]] ambiguity contract).
- */
-export function resolveSpecFileByFileKey(vaultRoot, specId) {
-  const candidate = fileKeyCandidateFromQuery(specId);
-  if (!candidate) return null;
-
-  const matches = new Set();
-  for (const dir of FILE_KEY_SCAN_DIRS) {
-    const dirPath = join(vaultRoot, dir);
-    if (!existsSync(dirPath)) continue;
-    try {
-      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
-        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-        const base = entry.name.replace(/\.md$/i, '');
-        if (fileKeyFromBasename(base) === candidate) {
-          matches.add(join(dir, entry.name));
-          continue;
-        }
-        try {
-          const { frontmatter } = parseFrontmatter(readFileSync(join(dirPath, entry.name), 'utf-8'));
-          if (frontmatter.file_id === candidate) matches.add(join(dir, entry.name));
-        } catch {
-          // Unreadable file — skip.
-        }
-      }
-    } catch {
-      // Directory unreadable — skip.
-    }
-  }
-
-  if (matches.size === 1) {
-    const hit = [...matches][0];
-    process.stderr.write?.(
-      `[heyspex-mcp dual-read] resolved "${specId}" via file key "${candidate}" → ${hit}\n`,
-    );
-    return hit;
-  }
-  if (matches.size > 1) {
-    process.stderr.write?.(
-      `[heyspex-mcp dual-read] AMBIGUOUS file key "${candidate}" for "${specId}" — candidates: ${[...matches].join(', ')} (fail-closed, not guessing)\n`,
-    );
-  }
-  return null;
-}
-
-/**
- * Crosswalk fallback ([[HS-ANWD-RHIB-TASK]]): read the retired-id redirect
- * table the step-4 rename writes (`.heyspex/id-crosswalk.json`, rows
- * `{oldBasename, oldId, newBasename, newId}`) and re-resolve a retired
- * basename/id to the surviving spec. Tolerates an absent or malformed file
- * silently (pre-rename vaults have none) — mirror of the indexer's
- * loadIdCrosswalk contract.
- */
-export function resolveSpecFileViaCrosswalk(vaultRoot, specId) {
-  let rows;
-  try {
-    rows = JSON.parse(readFileSync(join(vaultRoot, '.heyspex', 'id-crosswalk.json'), 'utf-8'));
-  } catch {
-    return null;
-  }
-  if (!Array.isArray(rows)) return null;
-
-  const q = String(specId ?? '').trim().replace(/\.md$/i, '');
-  const hit = rows.find((r) => r && (r.oldBasename === q || r.oldId === q));
-  if (!hit) return null;
-  const target = hit.newBasename ?? hit.newId;
-  if (!target) return null;
-  const resolved = resolveSpecFileRaw(vaultRoot, target);
-  if (resolved) {
-    process.stderr.write?.(
-      `[heyspex-mcp dual-read] resolved retired "${specId}" via crosswalk → ${resolved}\n`,
-    );
-  }
-  return resolved;
-}
-
-/**
- * Cloud-reliant sibling of `findSpecFile` ([[HS-DJWP-MCPC-TASK]] "spec-id
- * resolution" family). `findSpecFile` itself (and the multi-tier
- * `resolveSpecFileRaw` / `resolveSpecFileByFileKey` / `resolveSpecFileViaCrosswalk`
- * chain it drives) stays disk-only and UNTOUCHED — it is the `diskRead` branch
- * here, verbatim. In `neon` tier this never walks `specs/` directories; it asks
- * `GET /api/specs/resolve?q=` for the `{basename, id, relPath}` triple. A 404
- * (not_found OR ambiguous_id) is a real, reachable-console answer — "no such
- * spec" — and returns `null` exactly like `findSpecFile` does today; only a
- * genuine transport/5xx failure throws (wrapped by `readViaSelector` into
- * `CONSOLE_UNREACHABLE_CLOUD_MODE`).
- */
-export async function resolveSpecIdViaTier(vaultRoot, specId, { tier, consoleUrl }) {
-  return readViaSelector({
-    tier,
-    // Same contract as findSpecFile: a bare relPath string, or null.
-    diskRead: () => findSpecFile(vaultRoot, specId),
-    neonRead: async () => {
-      const res = await consoleFetch(`/api/specs/resolve?q=${encodeURIComponent(specId)}`);
-      if (res.ok) {
-        return res.body?.resolved?.relPath ?? null;
-      }
-      if (res.status === 404) return null; // not_found / ambiguous_id — a real answer, not a failure.
-      throw new Error(
-        `GET /api/specs/resolve returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`,
-      );
-    },
-    routeLabel: 'GET /api/specs/resolve',
-    consoleUrl,
-  });
-}
-
-/**
- * Cloud-reliant "load this spec by id" primitive ([[HS-DJWP-MCPC-TASK]] round
- * 2, AC1 "general spec load"). Disk tier calls `findSpecFile` + `loadSpec`
- * (both untouched, verbatim) and returns `{ specPath, frontmatter, body }` —
- * `null` when not found. Neon tier makes ONE `GET /api/specs/[id]` call (the
- * route resolves AND loads together, per its own docstring: "`:id` accepts
- * the spec `id` or a wikilink basename").
- *
- * Used by `handleNextOnDeck` to pre-fetch the direct `spec_id` lookup branch
- * of `resolveNextOnDeckPayload` — see the `__cloud_direct_spec` injection
- * there for why that branch itself could not be made async directly (14+
- * synchronous call sites in `cli.test.mjs`).
- */
-export async function loadSpecByIdViaTier(vaultRoot, specId, { tier, consoleUrl }) {
-  return readViaSelector({
-    tier,
-    diskRead: () => {
-      const specPath = findSpecFile(vaultRoot, specId);
-      if (!specPath) return null;
-      const spec = loadSpec(vaultRoot, specPath);
-      if (!spec) return null;
-      return { specPath, frontmatter: spec.frontmatter, body: spec.body };
-    },
-    neonRead: async () => {
-      const res = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
-      if (res.ok) {
-        const spec = res.body?.spec;
-        if (!spec) return null;
-        return { specPath: spec.relPath ?? null, frontmatter: spec.frontmatter || {}, body: spec.body || '' };
-      }
-      if (res.status === 404) return null; // not_found / ambiguous_id — a real answer, not a failure.
-      throw new Error(
-        `GET /api/specs/${specId} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`,
-      );
-    },
-    routeLabel: 'GET /api/specs/[id]',
-    consoleUrl,
-  });
-}
-
-/**
- * [[HS-H227-MCPC-TASK]] Pre-fetch, over HTTP, the bounded closure of specs
- * that on-deck brief composition's `loadRef` calls can reach for a given
- * root spec's frontmatter — `extractDecompositionContext`'s `related:` links
- * and its milestone-chain climb (walked by `enrichOnDeckWithClaimTarget` too,
- * via `resolveHierarchy`/`computeClaimTarget` in blocker-resolver.mjs), plus
- * each hop's OWN `related:` links (parent-contract tethering checks the
- * task's related AND its parent's related) and a milestone's sibling `epics:`
- * (decomposition context's milestone-siblings list). Real chains are shallow
- * (task -> epic -> milestone), but the climb is bounded (8 hops) as a
- * belt-and-braces guard against a malformed cycle.
- *
- * Returns a `Map` keyed by every spelling a `loadRef(ref)` call might use for
- * an entry (the ref token it was fetched by, its resolved frontmatter `id`,
- * and its specPath basename) — `loadTaskViaGraph` below does the lookup. The
- * root spec itself (already fetched by the caller as `__cloud_direct_spec`,
- * no second HTTP call here) is seeded under `rootRef` so
- * `enrichOnDeckWithClaimTarget`'s OWN `loadTask(vaultRoot, result.spec_id)`
- * re-load of the on-deck spec also answers from this same cache.
- * `loadSpecByIdViaTier`'s own no-silent-disk-fallback holds here too: a
- * genuine console failure mid-walk throws (propagated to the caller's
- * existing CONSOLE_UNREACHABLE_CLOUD_MODE handling); a 404/not-found ref is
- * just absent from the map — every consumer already treats a missing
- * `loadRef` result as "skip this piece of context", never a hard error.
- */
-export async function prefetchCloudTaskGraph(vaultRoot, rootRef, rootSpec, { tier, consoleUrl }) {
-  const cache = new Map();
-
-  const register = (key, loaded) => {
-    if (!loaded) return null;
-    const fm = loaded.frontmatter || {};
-    const shaped = {
-      frontmatter: fm,
-      body: loaded.body || '',
-      specPath: loaded.specPath ?? null,
-      id: fm.id || key,
-      status: fm.status,
-      name: fm.name,
-      type: fm.type,
-      tags: fm.tags || [],
-    };
-    if (key) cache.set(String(key), shaped);
-    if (fm.id) cache.set(String(fm.id), shaped);
-    if (loaded.specPath) {
-      const base = String(loaded.specPath).split(/[\\/]/).pop().replace(/\.md$/i, '');
-      cache.set(base, shaped);
-    }
-    return shaped;
-  };
-
-  const fetchRef = async (ref) => {
-    const key = wikilinkTarget(ref);
-    if (!key) return null;
-    if (cache.has(key)) return cache.get(key);
-    const loaded = await loadSpecByIdViaTier(vaultRoot, key, { tier, consoleUrl });
-    return register(key, loaded);
-  };
-
-  const relatedOf = (fm) => (Array.isArray(fm?.related) ? fm.related : []);
-
-  const rootShaped = register(rootRef, rootSpec);
-  await Promise.all(relatedOf(rootShaped?.frontmatter).map(fetchRef));
-
-  let currentFm = rootShaped?.frontmatter || {};
-  for (let hops = 0; hops < 8; hops++) {
-    const parentRef = currentFm.parent || currentFm.parent_epic || currentFm.milestone;
-    if (!parentRef) break;
-    const parentShaped = await fetchRef(parentRef);
-    if (!parentShaped) break;
-    const parentFm = parentShaped.frontmatter || {};
-    await Promise.all(relatedOf(parentFm).map(fetchRef));
-    if (Array.isArray(parentFm.epics)) {
-      await Promise.all(parentFm.epics.map(fetchRef));
-    }
-    currentFm = parentFm;
-  }
-
-  return cache;
-}
-
-// [[HS-68XO-DIAG]] residual — pick a UNIQUELY-resolvable handle for a claim target.
-//
-// computeClaimTarget reports a leaf's bare frontmatter `id` as `spec_id`, but a
-// shared-suffix family (>1 sibling carrying the same id, e.g. the six
-// `HS-W6AD-TASK` children of HS-W6AD-EPIC) makes that bare token AMBIGUOUS. The
-// hardened resolver ([[vault-id-assignment-protocol]] §Shared-suffix families)
-// correctly REFUSES a bare ambiguous token — which would 409 the very
-// `heyspex_claim_spec` the on-deck brief tees up (the claim/release/alignment
-// actions are all built off `claim_target.spec_id`). When the bare id no longer
-// resolves to exactly one spec, return the leaf's unique basename instead (it
-// resolves via the resolver's exact-path check), so the claim/status/progress
-// handshake targets exactly this sibling. Unique families still resolve from the
-// bare token → it is returned unchanged (the convention + every blocker-resolver
-// test asserting bare ids is preserved).
-export function disambiguateClaimSpecId(vaultRoot, specId, relPath) {
-  if (!specId || !relPath) return specId;
-  let resolvesUniquely = false;
-  try {
-    resolvesUniquely = !!findSpecFile(vaultRoot, specId);
-  } catch {
-    resolvesUniquely = false;
-  }
-  if (resolvesUniquely) return specId;
-  const base = String(relPath)
-    .split(/[\\/]/)
-    .pop()
-    .replace(/\.md$/i, '');
-  return base && base !== specId ? base : specId;
-}
-
-export function loadRoadmap(vaultRoot, roadmapId) {
-  const specPath = findSpecFile(vaultRoot, roadmapId);
-  if (!specPath) return null;
-
-  const spec = loadSpec(vaultRoot, specPath);
-  if (!spec) return null;
-
-  return {
-    ...spec,
-    specPath,
-    id: spec.frontmatter.id || roadmapId,
-  };
-}
-
-export function loadTask(vaultRoot, taskId) {
-  const specPath = findSpecFile(vaultRoot, taskId);
-  if (!specPath) return null;
-
-  const spec = loadSpec(vaultRoot, specPath);
-  if (!spec) return null;
-
-  return {
-    ...spec,
-    specPath,
-    id: spec.frontmatter.id || taskId,
-    status: spec.frontmatter.status,
-    name: spec.frontmatter.name,
-    type: spec.frontmatter.type,
-    tags: spec.frontmatter.tags || [],
-  };
-}
-
-/**
- * [[HS-H227-MCPC-TASK]] Cloud-aware `loadTask` for on-deck brief composition.
- * `cloudTaskGraph`, when supplied, is the `Map` `prefetchCloudTaskGraph` built
- * over HTTP in neon tier — a miss there returns null, never a disk fallback
- * (no-silent-disk-fallback rule; a genuine console failure already surfaced
- * during the pre-fetch, before this synchronous lookup ever runs). Every
- * OTHER `loadTask` call site (disk-only on-deck flows this task does not
- * touch — blocker/prerequisite resolution, the scheduler cohort path, etc.)
- * never passes a graph and this falls through to the original disk read,
- * unchanged.
- */
-export function loadTaskViaGraph(vaultRoot, ref, cloudTaskGraph) {
-  if (cloudTaskGraph) {
-    const key = wikilinkTarget(ref);
-    return (key && cloudTaskGraph.get(key)) || null;
-  }
-  try {
-    return loadTask(vaultRoot, ref);
-  } catch {
-    return null;
-  }
-}
-
-// Extract a basename or id from a `[[wikilink]]` (with or without surrounding quotes).
-export function wikilinkTarget(raw) {
-  if (typeof raw !== 'string') return null;
-  const m = raw.match(/\[\[([^\]]+)\]\]/);
-  return m ? m[1].trim() : raw.trim();
-}
+// Vault file IO shared by every tool: frontmatter/YAML parsing, spec-file
+// resolution by id / file key / crosswalk, and the tier-aware spec loaders.
+// Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// Read-path selector ([[HS-DJWP-MCPC-TASK-wire-the-mcp-server-s-vault-reads]] of
+// [[HS-T6GS-MCPC-EPIC-mcp-server-reads-the-vault-through-the]]): the ONE tier
+// decision point every wired vault read below goes through. Tier is resolved
+// fresh per tool invocation (never cached at module scope) so a dev-mode file
+// edited between calls takes effect on the very next call.
+
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { alternateOrderingBasename, fileKeyFromBasename, parseSpecId } from './spec-id-lib.mjs';
+import { consoleReadErrorFrom, readViaSelector } from './read-path.mjs';
+import { consoleFetch } from './console-transport.mjs';
+
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const yamlBlock = match[1];
+  const body = content.slice(match[0].length).trim();
+  const frontmatter = parseSimpleYaml(yamlBlock);
+
+  return { frontmatter, body };
+}
+
+export function parseSimpleYaml(yaml) {
+  const result = {};
+  const lines = yaml.split(/\r?\n/);
+  let currentKey = null;
+  let currentArray = null;
+  let inNestedObject = false;
+  let nestedKey = null;
+  let nestedArray = null;
+  // Block-scalar collection state (`key: |` / `key: >`). The vast majority of
+  // authored `summary:` values in this vault are literal block scalars, so the
+  // claim brief must read them as strings — not silently drop them to `[]`,
+  // which made the /hs-next card fall into the "author a summary" path for any
+  // spec whose summary was a block scalar. [[HS-TASK-ECOI]]
+  let blockKey = null;
+  let blockLines = null;
+  let blockFold = false;
+
+  const flushBlock = () => {
+    if (blockKey === null) return;
+    const contentful = blockLines.filter((l) => l.trim() !== '');
+    const minIndent = contentful.length
+      ? Math.min(...contentful.map((l) => l.match(/^(\s*)/)[1].length))
+      : 0;
+    const stripped = blockLines.map((l) => l.slice(minIndent));
+    result[blockKey] = blockFold
+      ? stripped.map((l) => l.trim()).filter(Boolean).join(' ')
+      : stripped.join('\n').replace(/\n+$/, '');
+    blockKey = null;
+    blockLines = null;
+    blockFold = false;
+  };
+
+  for (const line of lines) {
+    // Collect an active block scalar: blank or indented lines belong to it; a
+    // line at the key column ends it and is parsed normally below.
+    if (blockKey !== null) {
+      if (line.trim() === '' || /^\s/.test(line)) {
+        blockLines.push(line);
+        continue;
+      }
+      flushBlock();
+    }
+
+    // Skip empty lines and comments
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    // Detect array item under a key
+    const arrayItemMatch = line.match(/^(\s+)-\s*(.*)$/);
+    if (arrayItemMatch && currentArray !== null) {
+      const indent = arrayItemMatch[1].length;
+      const value = arrayItemMatch[2].trim().replace(/^["']|["']$/g, '');
+      if (indent <= 2 && currentArray) {
+        currentArray.push(value);
+      } else if (nestedArray) {
+        nestedArray.push(value);
+      }
+      continue;
+    }
+
+    // Detect nested object key (e.g., roadmap_manifest:)
+    const nestedKeyMatch = line.match(/^(\s{2,})(\w+):\s*(.*)$/);
+    if (nestedKeyMatch && inNestedObject) {
+      const key = nestedKeyMatch[2];
+      const value = nestedKeyMatch[3].trim();
+      if (value) {
+        if (!result[nestedKey]) result[nestedKey] = {};
+        result[nestedKey][key] = parseYamlValue(value);
+      }
+      continue;
+    }
+
+    // Detect top-level key
+    const keyMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/);
+    if (keyMatch) {
+      const key = keyMatch[1];
+      const value = keyMatch[2].trim();
+
+      currentArray = null;
+      inNestedObject = false;
+      nestedKey = null;
+      nestedArray = null;
+
+      if (/^[|>][-+\d]*$/.test(value)) {
+        // Block scalar (`|`, `>`, or a header variant like `|-`/`>+`/`|2`):
+        // collect the indented continuation lines into a string value.
+        currentKey = key;
+        blockKey = key;
+        blockLines = [];
+        blockFold = value.startsWith('>');
+        result[key] = '';
+      } else if (value === '') {
+        // Could be array, nested object, or multiline
+        currentKey = key;
+        result[key] = [];
+        currentArray = result[key];
+      } else if (value.startsWith('[') && value.endsWith(']')) {
+        // Inline array
+        result[key] = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
+      } else {
+        result[key] = parseYamlValue(value);
+      }
+
+      // Check if this is roadmap_manifest (needs special handling)
+      if (key === 'roadmap_manifest') {
+        inNestedObject = true;
+        nestedKey = key;
+        result[key] = {};
+      }
+
+      // `pin:` is a nested object ({ spec_id, pinned_at, expires_at, pinned_by })
+      // written by the console pin writer (`POST /api/pin`). Without
+      // this, parseSimpleYaml only descends into roadmap_manifest, so an empty
+      // `pin:` value parses to an array and the modern pin block is invisible to
+      // /hs-next — every focus reader downstream (getPinnedSpecIdFromFocus, the
+      // milestone/epic drill) sees no pin and falls through to scheduler_default.
+      // Guarded on empty value so a scalar `pin:` elsewhere is unaffected.
+      if (key === 'pin' && value === '') {
+        inNestedObject = true;
+        nestedKey = key;
+        result[key] = {};
+        currentArray = null;
+      }
+    }
+  }
+
+  // Flush a block scalar that ran to the end of the frontmatter.
+  flushBlock();
+
+  // Handle roadmap_manifest specially - re-parse with full YAML support
+  if (result.roadmap_manifest !== undefined) {
+    result.roadmap_manifest = parseRoadmapManifest(yaml);
+  }
+
+  return result;
+}
+
+export function parseRoadmapManifest(yaml) {
+  // Find roadmap_manifest block and parse it more carefully
+  const manifestMatch = yaml.match(/roadmap_manifest:\s*\r?\n([\s\S]*?)(?=\r?\n\w|\r?\n$|$)/);
+  if (!manifestMatch) return {};
+
+  const manifestBlock = manifestMatch[1];
+  const manifest = { phases: [], initiatives: [], horizon: [] };
+
+  // Parse version and default
+  const versionMatch = manifestBlock.match(/version:\s*(\d+)/);
+  if (versionMatch) manifest.version = parseInt(versionMatch[1], 10);
+
+  const defaultMatch = manifestBlock.match(/default:\s*(true|false)/);
+  if (defaultMatch) manifest.default = defaultMatch[1] === 'true';
+
+  // Parse phases
+  const phasesMatch = manifestBlock.match(/phases:\s*\r?\n([\s\S]*?)(?=\r?\n\s{2}\w|\r?\n\s{2}-\s*id:.*initiatives|\r?\n\s{2}initiatives:|\r?\n\s{2}horizon:|$)/);
+  if (phasesMatch) {
+    const phasesBlock = phasesMatch[1];
+    const phaseBlocks = phasesBlock.split(/\r?\n\s{4}- id:/);
+
+    for (let i = 0; i < phaseBlocks.length; i++) {
+      const block = (i === 0 ? phaseBlocks[i].replace(/^\s*- id:/, '') : phaseBlocks[i]).trim();
+      if (!block) continue;
+
+      const phase = { tasks: [] };
+
+      const idMatch = block.match(/^(\S+)/);
+      if (idMatch) phase.id = idMatch[1];
+
+      const nameMatch = block.match(/name:\s*(.+)/);
+      if (nameMatch) phase.name = nameMatch[1].trim();
+
+      const summaryMatch = block.match(/summary:\s*(.+)/);
+      if (summaryMatch) phase.summary = summaryMatch[1].trim();
+
+      // Parse tasks array
+      const tasksMatch = block.match(/tasks:\s*\r?\n([\s\S]*?)(?=\r?\n\s{4}- id:|$)/);
+      if (tasksMatch) {
+        const taskLines = tasksMatch[1].match(/^\s*- (\S+)/gm);
+        if (taskLines) {
+          phase.tasks = taskLines.map(t => t.replace(/^\s*- /, '').trim());
+        }
+      }
+
+      if (phase.id) manifest.phases.push(phase);
+    }
+  }
+
+  // Parse initiatives
+  const initiativesMatch = manifestBlock.match(/initiatives:\s*\r?\n([\s\S]*?)(?=\r?\n\s{2}\w|$)/);
+  if (initiativesMatch) {
+    const initLines = initiativesMatch[1].match(/^\s*- (\S+)/gm);
+    if (initLines) {
+      manifest.initiatives = initLines.map(t => t.replace(/^\s*- /, '').trim());
+    }
+  }
+
+  // Parse horizon
+  const horizonMatch = manifestBlock.match(/horizon:\s*\r?\n([\s\S]*?)(?=\r?\n\w|$)/);
+  if (horizonMatch) {
+    const horizonLines = horizonMatch[1].match(/^\s*- (\S+)/gm);
+    if (horizonLines) {
+      manifest.horizon = horizonLines.map(t => t.replace(/^\s*- /, '').trim());
+    }
+  }
+
+  return manifest;
+}
+
+export function parseYamlValue(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null' || value === '~') return null;
+  if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+  if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+  return value.replace(/^["']|["']$/g, '');
+}
+
+export function loadSpec(vaultRoot, specPath) {
+  const fullPath = join(vaultRoot, specPath);
+  if (!existsSync(fullPath)) return null;
+
+  const content = readFileSync(fullPath, 'utf-8');
+  return parseFrontmatter(content);
+}
+
+// Raw, single-ordering resolver: locate a spec file whose basename (or
+// frontmatter id) matches `specId` exactly as given. The dual-read wrapper
+// `findSpecFile` calls this once per candidate ordering.
+export function resolveSpecFileRaw(vaultRoot, specId) {
+  // Check exact filename matches first
+  const locations = [
+    `specs/tasks/${specId}.md`,
+    `specs/epics/${specId}.md`,
+    `specs/milestones/${specId}.md`,
+    `specs/roadmaps/${specId}.md`,
+    `specs/research/${specId}.md`,
+    `specs/reviews/${specId}.md`,
+    `specs/adr/${specId}.md`,
+    `specs/${specId}.md`,
+  ];
+  // CAP is family-keyed (dual-read via parseSpecId); IDEA is not reordered, so it
+  // stays a type-first prefix check ([[HS-EPIC-DLE3]]).
+  if (parseSpecId(specId)?.typeLabel === 'CAP' || /^HS-IDEA-/i.test(specId)) {
+    for (const bucket of ['captures', 'ideas']) {
+      const bucketDir = join(vaultRoot, 'specs', bucket);
+      if (!existsSync(bucketDir)) continue;
+      try {
+        for (const file of readdirSync(bucketDir)) {
+          if (file.startsWith(specId) && file.endsWith('.md')) {
+            return join('specs', bucket, file);
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  for (const loc of locations) {
+    const fullPath = join(vaultRoot, loc);
+    if (existsSync(fullPath)) return loc;
+  }
+
+  // Search in specs directories by filename prefix. Vault root (`specs/`) is
+  // scanned via a sentinel that the helpers treat as a flat .md walk (no
+  // subdir recursion) so foundational specs (heyspex-north-star, etc.) and
+  // adr/ entries resolve from [[wikilinks]]. [[HS-TASK-NWLR]]
+  //
+  // Ambiguity guard ([[HS-68XO-DIAG]] / vault-id-assignment-protocol §Shared-suffix
+  // families, same contract as [[HS-QEBP-TASK]]): a bare shared-family token
+  // (e.g. `HS-W6AD-TASK` when six sibling tasks all carry that id) matches MORE
+  // THAN ONE basename at a token boundary. Picking the first in readdir order
+  // silently targets the wrong sibling (the diagnosed claim/scheduler bug), so we
+  // collect ALL matches and resolve only when exactly one exists — >1 returns null
+  // (ambiguous → surfaces upstream rather than guessing). A full basename already
+  // returned via the exact-path check above, so it never reaches this scan.
+  const specDirs = ['specs/tasks', 'specs/epics', 'specs/milestones', 'specs/diagnoses', 'specs/roadmaps', 'specs/research', 'specs/reviews', 'specs/captures', 'specs/ideas', 'specs/adr', 'specs'];
+  const matchesAtBoundary = (file) =>
+    file.endsWith('.md') && (file === `${specId}.md` || file.startsWith(`${specId}-`));
+
+  const prefixMatches = new Set();
+  for (const dir of specDirs) {
+    const dirPath = join(vaultRoot, dir);
+    if (!existsSync(dirPath)) continue;
+    try {
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        if (entry.isFile() && matchesAtBoundary(entry.name)) {
+          prefixMatches.add(join(dir, entry.name));
+        }
+      }
+    } catch {
+      // Directory doesn't exist or isn't readable
+    }
+  }
+  if (prefixMatches.size === 1) return [...prefixMatches][0];
+  if (prefixMatches.size > 1) return null; // ambiguous bare family token — do not guess
+
+  // Search by frontmatter id field (handles filename != id cases). Same
+  // exactly-one rule: a shared id carried by >1 sibling is ambiguous → null.
+  const idMatches = new Set();
+  for (const dir of specDirs) {
+    const dirPath = join(vaultRoot, dir);
+    if (!existsSync(dirPath)) continue;
+    try {
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        if (!entry.isFile()) continue;
+        const file = entry.name;
+        if (!file.endsWith('.md')) continue;
+        const filePath = join(dir, file);
+        const content = readFileSync(join(vaultRoot, filePath), 'utf-8');
+        const { frontmatter } = parseFrontmatter(content);
+        if (frontmatter.id === specId) idMatches.add(filePath);
+      }
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+  if (idMatches.size === 1) return [...idMatches][0];
+  return null; // 0 → not found; >1 → ambiguous shared-family id
+}
+
+// Dual-read spec resolver ([[HS-EPIC-6SNQ-dual-read-resolver-grace-period-for-pipe]],
+// Phase 1 of [[HS-MIL-KY1F-pipeline-first-spec-identifier-format-mi]]).
+//
+// During the format migration grace window the on-disk basenames are in ONE
+// ordering at a time (type-first today, family-first after the bulk rename), but
+// callers may pass either. Resolve the input as-given first; on a miss, flip the
+// ordering once and retry, logging the legacy/cross-ordering hit to stderr so the
+// sunset gate can count residual legacy references. Family-first input that hits
+// directly never touches the fallback (no log).
+export function findSpecFile(vaultRoot, specId) {
+  const direct = resolveSpecFileRaw(vaultRoot, specId);
+  if (direct) return direct;
+
+  const alt = alternateOrderingBasename(specId);
+  if (alt) {
+    const hit = resolveSpecFileRaw(vaultRoot, alt);
+    if (hit) {
+      process.stderr.write?.(
+        `[heyspex-mcp dual-read] resolved "${specId}" via alternate ordering "${alt}" → ${hit}\n`,
+      );
+      return hit;
+    }
+  }
+
+  // File-key tier ([[HS-ANWD-RHIB-TASK]], parity with the console resolver's
+  // buildSpecLookup priority: file key above basename fallbacks). Extract a
+  // candidate key from the query — a bare `HS-<key>` citation or the era-aware
+  // key of a full basename — and match it against every spec's frontmatter
+  // `file_id:` / basename-derived key, in ANY of the three era orderings
+  // (era-1/2 keys sit mid-basename, so the prefix scan above never finds them).
+  const byKey = resolveSpecFileByFileKey(vaultRoot, specId);
+  if (byKey) return byKey;
+
+  // Crosswalk tier: after the step-4 vault-wide rename, retired basenames/ids
+  // live in .heyspex/id-crosswalk.json → re-resolve to the surviving name.
+  const viaCrosswalk = resolveSpecFileViaCrosswalk(vaultRoot, specId);
+  if (viaCrosswalk) return viaCrosswalk;
+
+  return null;
+}
+
+// Directories the file-key tier scans — superset mirror of the specDirs list in
+// resolveSpecFileRaw (kept separate so that function stays untouched).
+export const FILE_KEY_SCAN_DIRS = ['specs/tasks', 'specs/epics', 'specs/milestones', 'specs/diagnoses', 'specs/roadmaps', 'specs/research', 'specs/reviews', 'specs/captures', 'specs/ideas', 'specs/adr', 'specs'];
+
+/** Bare `HS-<fileKey>` citation → the key; else the era-aware key of a full basename; else null. */
+export function fileKeyCandidateFromQuery(specId) {
+  const trimmed = String(specId ?? '').trim().replace(/\.md$/i, '');
+  const bare = /^HS-((?=[0-9]*[A-Z])[A-Z0-9]{4,})$/.exec(trimmed);
+  if (bare) return bare[1];
+  return fileKeyFromBasename(trimmed);
+}
+
+/**
+ * Resolve a spec by its per-file FILE KEY across all three era orderings.
+ * Frontmatter `file_id:` is the SSOT (a lazily-minted key may exist only
+ * there), with the basename-derived key as the cheap first check. Fail-closed
+ * on ambiguity: >1 match returns null and names the colliding candidates on
+ * stderr — never guess ([[vault-id-assignment-protocol]] ambiguity contract).
+ */
+export function resolveSpecFileByFileKey(vaultRoot, specId) {
+  const candidate = fileKeyCandidateFromQuery(specId);
+  if (!candidate) return null;
+
+  const matches = new Set();
+  for (const dir of FILE_KEY_SCAN_DIRS) {
+    const dirPath = join(vaultRoot, dir);
+    if (!existsSync(dirPath)) continue;
+    try {
+      for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+        const base = entry.name.replace(/\.md$/i, '');
+        if (fileKeyFromBasename(base) === candidate) {
+          matches.add(join(dir, entry.name));
+          continue;
+        }
+        try {
+          const { frontmatter } = parseFrontmatter(readFileSync(join(dirPath, entry.name), 'utf-8'));
+          if (frontmatter.file_id === candidate) matches.add(join(dir, entry.name));
+        } catch {
+          // Unreadable file — skip.
+        }
+      }
+    } catch {
+      // Directory unreadable — skip.
+    }
+  }
+
+  if (matches.size === 1) {
+    const hit = [...matches][0];
+    process.stderr.write?.(
+      `[heyspex-mcp dual-read] resolved "${specId}" via file key "${candidate}" → ${hit}\n`,
+    );
+    return hit;
+  }
+  if (matches.size > 1) {
+    process.stderr.write?.(
+      `[heyspex-mcp dual-read] AMBIGUOUS file key "${candidate}" for "${specId}" — candidates: ${[...matches].join(', ')} (fail-closed, not guessing)\n`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Crosswalk fallback ([[HS-ANWD-RHIB-TASK]]): read the retired-id redirect
+ * table the step-4 rename writes (`.heyspex/id-crosswalk.json`, rows
+ * `{oldBasename, oldId, newBasename, newId}`) and re-resolve a retired
+ * basename/id to the surviving spec. Tolerates an absent or malformed file
+ * silently (pre-rename vaults have none) — mirror of the indexer's
+ * loadIdCrosswalk contract.
+ */
+export function resolveSpecFileViaCrosswalk(vaultRoot, specId) {
+  let rows;
+  try {
+    rows = JSON.parse(readFileSync(join(vaultRoot, '.heyspex', 'id-crosswalk.json'), 'utf-8'));
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(rows)) return null;
+
+  const q = String(specId ?? '').trim().replace(/\.md$/i, '');
+  const hit = rows.find((r) => r && (r.oldBasename === q || r.oldId === q));
+  if (!hit) return null;
+  const target = hit.newBasename ?? hit.newId;
+  if (!target) return null;
+  const resolved = resolveSpecFileRaw(vaultRoot, target);
+  if (resolved) {
+    process.stderr.write?.(
+      `[heyspex-mcp dual-read] resolved retired "${specId}" via crosswalk → ${resolved}\n`,
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Cloud-reliant sibling of `findSpecFile` ([[HS-DJWP-MCPC-TASK]] "spec-id
+ * resolution" family). `findSpecFile` itself (and the multi-tier
+ * `resolveSpecFileRaw` / `resolveSpecFileByFileKey` / `resolveSpecFileViaCrosswalk`
+ * chain it drives) stays disk-only and UNTOUCHED — it is the `diskRead` branch
+ * here, verbatim. In `neon` tier this never walks `specs/` directories; it asks
+ * `GET /api/specs/resolve?q=` for the `{basename, id, relPath}` triple. A 404
+ * (not_found OR ambiguous_id) is a real, reachable-console answer — "no such
+ * spec" — and returns `null` exactly like `findSpecFile` does today; only a
+ * genuine transport/5xx failure throws (wrapped by `readViaSelector` into
+ * `CONSOLE_UNREACHABLE_CLOUD_MODE`).
+ */
+export async function resolveSpecIdViaTier(vaultRoot, specId, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    // Same contract as findSpecFile: a bare relPath string, or null.
+    diskRead: () => findSpecFile(vaultRoot, specId),
+    neonRead: async () => {
+      const res = await consoleFetch(`/api/specs/resolve?q=${encodeURIComponent(specId)}`);
+      if (res.ok) {
+        return res.body?.resolved?.relPath ?? null;
+      }
+      if (res.status === 404) return null; // not_found / ambiguous_id — a real answer, not a failure.
+      throw consoleReadErrorFrom(res, `GET /api/specs/resolve returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+    },
+    routeLabel: 'GET /api/specs/resolve',
+    consoleUrl,
+  });
+}
+
+/**
+ * Cloud-reliant "load this spec by id" primitive ([[HS-DJWP-MCPC-TASK]] round
+ * 2, AC1 "general spec load"). Disk tier calls `findSpecFile` + `loadSpec`
+ * (both untouched, verbatim) and returns `{ specPath, frontmatter, body }` —
+ * `null` when not found. Neon tier makes ONE `GET /api/specs/[id]` call (the
+ * route resolves AND loads together, per its own docstring: "`:id` accepts
+ * the spec `id` or a wikilink basename").
+ *
+ * Used by `handleNextOnDeck` to pre-fetch the direct `spec_id` lookup branch
+ * of `resolveNextOnDeckPayload` — see the `__cloud_direct_spec` injection
+ * there for why that branch itself could not be made async directly (14+
+ * synchronous call sites in `cli.test.mjs`).
+ */
+export async function loadSpecByIdViaTier(vaultRoot, specId, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => {
+      const specPath = findSpecFile(vaultRoot, specId);
+      if (!specPath) return null;
+      const spec = loadSpec(vaultRoot, specPath);
+      if (!spec) return null;
+      return { specPath, frontmatter: spec.frontmatter, body: spec.body };
+    },
+    neonRead: async () => {
+      const res = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
+      if (res.ok) {
+        const spec = res.body?.spec;
+        if (!spec) return null;
+        return { specPath: spec.relPath ?? null, frontmatter: spec.frontmatter || {}, body: spec.body || '' };
+      }
+      if (res.status === 404) return null; // not_found / ambiguous_id — a real answer, not a failure.
+      throw consoleReadErrorFrom(res, `GET /api/specs/${specId} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+    },
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+/**
+ * [[HS-H227-MCPC-TASK]] Pre-fetch, over HTTP, the bounded closure of specs
+ * that on-deck brief composition's `loadRef` calls can reach for a given
+ * root spec's frontmatter — `extractDecompositionContext`'s `related:` links
+ * and its milestone-chain climb (walked by `enrichOnDeckWithClaimTarget` too,
+ * via `resolveHierarchy`/`computeClaimTarget` in blocker-resolver.mjs), plus
+ * each hop's OWN `related:` links (parent-contract tethering checks the
+ * task's related AND its parent's related) and a milestone's sibling `epics:`
+ * (decomposition context's milestone-siblings list). Real chains are shallow
+ * (task -> epic -> milestone), but the climb is bounded (8 hops) as a
+ * belt-and-braces guard against a malformed cycle.
+ *
+ * Returns a `Map` keyed by every spelling a `loadRef(ref)` call might use for
+ * an entry (the ref token it was fetched by, its resolved frontmatter `id`,
+ * and its specPath basename) — `loadTaskViaGraph` below does the lookup. The
+ * root spec itself (already fetched by the caller as `__cloud_direct_spec`,
+ * no second HTTP call here) is seeded under `rootRef` so
+ * `enrichOnDeckWithClaimTarget`'s OWN `loadTask(vaultRoot, result.spec_id)`
+ * re-load of the on-deck spec also answers from this same cache.
+ * `loadSpecByIdViaTier`'s own no-silent-disk-fallback holds here too: a
+ * genuine console failure mid-walk throws (propagated to the caller's
+ * existing CONSOLE_UNREACHABLE_CLOUD_MODE handling); a 404/not-found ref is
+ * just absent from the map — every consumer already treats a missing
+ * `loadRef` result as "skip this piece of context", never a hard error.
+ */
+export async function prefetchCloudTaskGraph(vaultRoot, rootRef, rootSpec, { tier, consoleUrl }) {
+  const cache = new Map();
+
+  const register = (key, loaded) => {
+    if (!loaded) return null;
+    const fm = loaded.frontmatter || {};
+    const shaped = {
+      frontmatter: fm,
+      body: loaded.body || '',
+      specPath: loaded.specPath ?? null,
+      id: fm.id || key,
+      status: fm.status,
+      name: fm.name,
+      type: fm.type,
+      tags: fm.tags || [],
+    };
+    if (key) cache.set(String(key), shaped);
+    if (fm.id) cache.set(String(fm.id), shaped);
+    if (loaded.specPath) {
+      const base = String(loaded.specPath).split(/[\\/]/).pop().replace(/\.md$/i, '');
+      cache.set(base, shaped);
+    }
+    return shaped;
+  };
+
+  const fetchRef = async (ref) => {
+    const key = wikilinkTarget(ref);
+    if (!key) return null;
+    if (cache.has(key)) return cache.get(key);
+    const loaded = await loadSpecByIdViaTier(vaultRoot, key, { tier, consoleUrl });
+    return register(key, loaded);
+  };
+
+  const relatedOf = (fm) => (Array.isArray(fm?.related) ? fm.related : []);
+
+  const rootShaped = register(rootRef, rootSpec);
+  await Promise.all(relatedOf(rootShaped?.frontmatter).map(fetchRef));
+
+  let currentFm = rootShaped?.frontmatter || {};
+  for (let hops = 0; hops < 8; hops++) {
+    const parentRef = currentFm.parent || currentFm.parent_epic || currentFm.milestone;
+    if (!parentRef) break;
+    const parentShaped = await fetchRef(parentRef);
+    if (!parentShaped) break;
+    const parentFm = parentShaped.frontmatter || {};
+    await Promise.all(relatedOf(parentFm).map(fetchRef));
+    if (Array.isArray(parentFm.epics)) {
+      await Promise.all(parentFm.epics.map(fetchRef));
+    }
+    currentFm = parentFm;
+  }
+
+  return cache;
+}
+
+// [[HS-68XO-DIAG]] residual — pick a UNIQUELY-resolvable handle for a claim target.
+//
+// computeClaimTarget reports a leaf's bare frontmatter `id` as `spec_id`, but a
+// shared-suffix family (>1 sibling carrying the same id, e.g. the six
+// `HS-W6AD-TASK` children of HS-W6AD-EPIC) makes that bare token AMBIGUOUS. The
+// hardened resolver ([[vault-id-assignment-protocol]] §Shared-suffix families)
+// correctly REFUSES a bare ambiguous token — which would 409 the very
+// `heyspex_claim_spec` the on-deck brief tees up (the claim/release/alignment
+// actions are all built off `claim_target.spec_id`). When the bare id no longer
+// resolves to exactly one spec, return the leaf's unique basename instead (it
+// resolves via the resolver's exact-path check), so the claim/status/progress
+// handshake targets exactly this sibling. Unique families still resolve from the
+// bare token → it is returned unchanged (the convention + every blocker-resolver
+// test asserting bare ids is preserved).
+export function disambiguateClaimSpecId(vaultRoot, specId, relPath) {
+  if (!specId || !relPath) return specId;
+  let resolvesUniquely = false;
+  try {
+    resolvesUniquely = !!findSpecFile(vaultRoot, specId);
+  } catch {
+    resolvesUniquely = false;
+  }
+  if (resolvesUniquely) return specId;
+  const base = String(relPath)
+    .split(/[\\/]/)
+    .pop()
+    .replace(/\.md$/i, '');
+  return base && base !== specId ? base : specId;
+}
+
+export function loadRoadmap(vaultRoot, roadmapId) {
+  const specPath = findSpecFile(vaultRoot, roadmapId);
+  if (!specPath) return null;
+
+  const spec = loadSpec(vaultRoot, specPath);
+  if (!spec) return null;
+
+  return {
+    ...spec,
+    specPath,
+    id: spec.frontmatter.id || roadmapId,
+  };
+}
+
+export function loadTask(vaultRoot, taskId) {
+  const specPath = findSpecFile(vaultRoot, taskId);
+  if (!specPath) return null;
+
+  const spec = loadSpec(vaultRoot, specPath);
+  if (!spec) return null;
+
+  return {
+    ...spec,
+    specPath,
+    id: spec.frontmatter.id || taskId,
+    status: spec.frontmatter.status,
+    name: spec.frontmatter.name,
+    type: spec.frontmatter.type,
+    tags: spec.frontmatter.tags || [],
+  };
+}
+
+/**
+ * [[HS-H227-MCPC-TASK]] Cloud-aware `loadTask` for on-deck brief composition.
+ * `cloudTaskGraph`, when supplied, is the `Map` `prefetchCloudTaskGraph` built
+ * over HTTP in neon tier — a miss there returns null, never a disk fallback
+ * (no-silent-disk-fallback rule; a genuine console failure already surfaced
+ * during the pre-fetch, before this synchronous lookup ever runs). Every
+ * OTHER `loadTask` call site (disk-only on-deck flows this task does not
+ * touch — blocker/prerequisite resolution, the scheduler cohort path, etc.)
+ * never passes a graph and this falls through to the original disk read,
+ * unchanged.
+ */
+export function loadTaskViaGraph(vaultRoot, ref, cloudTaskGraph) {
+  if (cloudTaskGraph) {
+    const key = wikilinkTarget(ref);
+    return (key && cloudTaskGraph.get(key)) || null;
+  }
+  try {
+    return loadTask(vaultRoot, ref);
+  } catch {
+    return null;
+  }
+}
+
+// Extract a basename or id from a `[[wikilink]]` (with or without surrounding quotes).
+export function wikilinkTarget(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/\[\[([^\]]+)\]\]/);
+  return m ? m[1].trim() : raw.trim();
+}