heyspex 0.2.5 → 0.2.7

package/vendor/heyspex-mcp/procedure-tools.mjs

@@ -1,1181 +1,1209 @@
-/**
- * HeySpex procedure-discovery MCP tools.
- *
- * Pure-logic module backing the `heyspex_list_procedures`,
- * `heyspex_get_procedure`, and `heyspex_preflight` MCP tools mounted in
- * cli.mjs. Reads the committed catalog at specs/protocols/.catalog.json
- * (generated by scripts/build-procedure-catalog.mjs) and the underlying
- * markdown bodies under specs/protocols/.
- *
- * Spec: [[HS-EPIC-3QS8-agent-procedure-discovery-enforcement-la]]
- * Pattern source: vendor/heyspex-mcp/design-tools.mjs (the
- * heyspex_design_* family is the canonical template this module mirrors).
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { consoleReadErrorFrom, mergeDegradation, readViaSelector, withDegradationScope } from "./read-path.mjs";
-import { pageListToolResult } from "./list-tools.mjs";
-
-const CATALOG_FILE = ["specs", "protocols", ".catalog.json"];
-const PROTOCOLS_DIR = ["specs", "protocols"];
-
-function normalize(value) {
-  return String(value ?? "").toLowerCase();
-}
-
-export function loadCatalog(vaultRoot) {
-  const path = join(vaultRoot, ...CATALOG_FILE);
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function summarize(entry) {
-  return {
-    name: entry.name,
-    id: entry.id,
-    title: entry.title,
-    tags: Array.isArray(entry.tags) ? entry.tags : [],
-    triggers: Array.isArray(entry.triggers) ? entry.triggers : [],
-    summary: entry.summary ?? "",
-    path: entry.path,
-  };
-}
-
-/**
- * `injectedCatalog` (HS-DJWP-MCPC-TASK read-path wiring): when provided, used
- * verbatim INSTEAD of `loadCatalog(vaultRoot)` — the cloud-reliant selector
- * wrapper below fetches the catalog once over HTTP and injects it here so
- * this function never touches disk in that tier. `undefined` (the default)
- * preserves today's disk-only behavior byte-for-byte.
- */
-export function executeListProcedures(vaultRoot, args = {}, injectedCatalog) {
-  const catalog =
-    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
-  if (!catalog) {
-    return {
-      error: "CATALOG_NOT_FOUND",
-      message:
-        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
-    };
-  }
-  const procedures = Array.isArray(catalog.procedures)
-    ? catalog.procedures
-    : [];
-  const tagFilter = args.tag ? normalize(args.tag) : null;
-  const triggerFilter = args.trigger ? normalize(args.trigger) : null;
-  const queryFilter = args.query ? normalize(args.query) : null;
-
-  const matches = [];
-  for (const entry of procedures) {
-    if (tagFilter) {
-      const tags = (entry.tags ?? []).map(normalize);
-      if (!tags.includes(tagFilter)) continue;
-    }
-    if (triggerFilter) {
-      const triggers = (entry.triggers ?? []).map(normalize);
-      if (!triggers.includes(triggerFilter)) continue;
-    }
-    if (queryFilter) {
-      const haystack = [entry.name, entry.title, entry.summary]
-        .map(normalize)
-        .join(" ");
-      if (!haystack.includes(queryFilter)) continue;
-    }
-    matches.push(summarize(entry));
-  }
-
-  // One page on a (name, id) keyset cursor, fitted to the byte budget of the
-  // tool — never the whole catalog, never a total count
-  // ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).
-  const paged = pageListToolResult("heyspex_list_procedures", matches, args, {
-    keyOf: (p) => p.name,
-    idOf: (p) => p.id ?? p.name,
-    extra: {
-      filters_applied: {
-        tag: args.tag ?? null,
-        trigger: args.trigger ?? null,
-        query: args.query ?? null,
-      },
-    },
-  });
-  if (paged.error) return paged.error;
-  return paged.result;
-}
-
-function findEntry(catalog, name) {
-  const procedures = Array.isArray(catalog.procedures)
-    ? catalog.procedures
-    : [];
-  return procedures.find((p) => p.name === name) || null;
-}
-
-export function executeGetProcedure(vaultRoot, args = {}) {
-  const name = String(args.name ?? "").trim();
-  if (!name) {
-    return {
-      error: "MISSING_NAME",
-      message: 'name is required (e.g. "spec-hierarchy")',
-    };
-  }
-  const catalog = loadCatalog(vaultRoot);
-  if (!catalog) {
-    return {
-      error: "CATALOG_NOT_FOUND",
-      message:
-        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
-    };
-  }
-  const entry = findEntry(catalog, name);
-  if (!entry) {
-    return {
-      error: "PROCEDURE_NOT_FOUND",
-      message: `No procedure named "${name}" in catalog. Call heyspex_list_procedures to browse.`,
-    };
-  }
-  const bodyPath = join(vaultRoot, ...PROTOCOLS_DIR, `${name}.md`);
-  if (!existsSync(bodyPath)) {
-    return {
-      error: "BODY_FILE_MISSING",
-      message: `Catalog entry exists but ${entry.path} not found on disk. Regenerate the catalog.`,
-    };
-  }
-  const content = readFileSync(bodyPath, "utf8");
-  return {
-    procedure: {
-      name: entry.name,
-      id: entry.id,
-      title: entry.title,
-      tags: Array.isArray(entry.tags) ? entry.tags : [],
-      triggers: Array.isArray(entry.triggers) ? entry.triggers : [],
-      summary: entry.summary ?? "",
-      path: entry.path,
-      status: entry.status ?? null,
-      created: entry.created ?? null,
-      lastModified: entry.lastModified ?? null,
-      byteSize: entry.byteSize ?? null,
-    },
-    content,
-    source: entry.path,
-  };
-}
-
-/**
- * Procedures every customer vault ships (the universal template protocols; a
- * drift test pins this list to the template manifest's protocol dests). Every
- * other PREFLIGHT_INTENT_MAP procedure is platform-only: a vault whose runtime
- * catalog lacks it gets the row DEMOTED to advisory by {@link resolveRow}, never
- * deleted. Promoting more procedures to universal is a later template version.
- */
-export const UNIVERSAL_PROCEDURES = Object.freeze([
-  "canonical-frontmatter-templates",
-  "spec-hierarchy",
-  "memory-protocol",
-  "session-close-protocol",
-  "spec-summary-authoring",
-  "destructive-action-checklist",
-]);
-
-/** Audience of a preflight row, by procedure name. */
-export function procedureAudience(name) {
-  return UNIVERSAL_PROCEDURES.includes(name) ? "universal" : "platform";
-}
-
-const DEMOTED_REASON = "not in this vault's catalog (platform-only procedure)";
-
-/**
- * Resolve one preflight row against the supplied (runtime) catalog. Shared by
- * the static intent path AND the close_session thread-type path. A row whose
- * procedure is present is returned exactly as before; an absent one is demoted
- * to `advisory` (original severity kept in `demoted_from`) with
- * `missing_from_catalog: true` still set for consumers.
- */
-export function resolveRow(catalog, row) {
-  const entry = findEntry(catalog, row.procedure);
-  const base = {
-    procedure: row.procedure,
-    ...(row.why !== undefined ? { why: row.why } : {}),
-    severity: row.severity,
-    path: entry?.path ?? null,
-    title: entry?.title ?? null,
-    missing_from_catalog: entry ? undefined : true,
-  };
-  if (entry) return base;
-  return {
-    ...base,
-    severity: "advisory",
-    demoted_from: row.severity,
-    reason: DEMOTED_REASON,
-  };
-}
-
-// Bootstrap intent → procedure map (eight intents per HS-EPIC-3QS8 §Open
-// questions "Trigger taxonomy"). Each row names the procedure slug (matches
-// specs/protocols/<slug>.md), a `why` blurb the agent can quote, and a
-// severity. Extension rule: add a new intent when a third unique use case
-// appears — new intents land in their own tasks, not edits to this map.
-const PREFLIGHT_INTENT_MAP = {
-  // [[HS-K0ZP]]: "about to do research" is a governed trigger. Running this
-  // preflight writes the proof-of-use marker that unlocks WebSearch / WebFetch /
-  // heyspex_save_research for the session (spexharness/src/gates/research-protocol-gate.mjs
-  // on every PreToolUse front, preflight-gate.mjs inside the MCP server). Before
-  // it, those calls are refused -- the protocol was prose an agent could skip.
-  research: [
-    {
-      procedure: "research-capture-protocol",
-      why: "Method triage FIRST (known-target-retrieval vs the confidence ladder), ground-first (heyspex_recall_memories + /hs-ground) before any external pass, and the offer-before-save step: a web search offers to save findings, it does not auto-file a research doc.",
-      severity: "required",
-    },
-    {
-      procedure: "capture-guardrails",
-      why: "A known-target lookup never enters the research-doc pipeline; the exit for a quick retrieval is a memory-reference or a fold into the consuming spec.",
-      severity: "recommended",
-    },
-  ],
-  promote_research: [
-    {
-      procedure: "research-capture-protocol",
-      why: "Confirm the research doc is complete (prerequisites, conclusion, sources) before promotion.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-hierarchy",
-      why: "Mandatory default: target_milestone NEW. Existing-milestone attach only when status: open and thesis clearly extends; in_progress requires explicit owner override.",
-      severity: "required",
-    },
-    {
-      procedure: "pillar-assignment-protocol",
-      why: "Every spawned epic must name a pillar before execution breakdown.",
-      severity: "recommended",
-    },
-  ],
-  file_iteration: [
-    {
-      procedure: "supersession-protocol",
-      why: "§Iterates-on: choose the right tier; a re-attempt is neither supersession nor amends.",
-      severity: "required",
-    },
-    {
-      procedure: "research-capture-protocol",
-      why: 'Promote flow asks "is this a re-attempt?" and populates iterates_on: — confirm iteration lineage is recorded.',
-      severity: "required",
-    },
-    {
-      procedure: "internal-linking-protocol",
-      why: "Iteration structure and tier-based lineage tracking; see entity-model §Iteration lineage for tier semantics.",
-      severity: "recommended",
-    },
-  ],
-  file_milestone: [
-    {
-      procedure: "spec-hierarchy",
-      why: "Defines which level a new spec belongs at and the milestone frontmatter shape.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-summary-authoring",
-      why: "Every milestone needs a plain-language summary: at filing time — pass summary to heyspex_file_spec / POST /api/specs.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique HS-MIL-<suffix> id and prevents duplicates.",
-      severity: "required",
-    },
-  ],
-  file_epic: [
-    {
-      procedure: "spec-hierarchy",
-      why: "Defines epic frontmatter, required parent-milestone link, and child layout.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-summary-authoring",
-      why: "Every epic needs a plain-language summary at plan-ingest filing time — pass summary to heyspex_push_plan / heyspex_file_spec / POST /api/specs. Do not file tasks in the same pass.",
-      severity: "required",
-    },
-    {
-      procedure: "pillar-assignment-protocol",
-      why: "Every epic must name a pillar (hard-blocked at filing). Covers picking an existing HS-PILR theme or authoring a net-new one.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique HS-EPIC-<suffix> id and prevents duplicates.",
-      severity: "required",
-    },
-    {
-      procedure: "plan-ingest-agent-workflow",
-      why: "Linkage + manifest registration steps when ingesting an external plan into the epic.",
-      severity: "recommended",
-    },
-    {
-      procedure: "builder-fleet-capability-reference",
-      why: "Optional builder_profile + ## Builder fleet notes at epic filing — anticipate local builder model class and context tier.",
-      severity: "recommended",
-    },
-  ],
-  file_task: [
-    {
-      procedure: "spec-hierarchy",
-      why: "Defines task frontmatter, required parent-epic link, and child-task fan-out rules.",
-      severity: "required",
-    },
-    {
-      procedure: "builder-fleet-capability-reference",
-      why: "Required ## Builder brief + dispatch frontmatter (suggested_model, recommended_num_ctx, context_files) for fleet-calibrated tasks.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-summary-authoring",
-      why: "Every task needs a plain-language summary at the /hs-next breakdown moment — pass summary to heyspex_file_spec / POST /api/specs. Tasks are never filed during plan ingest.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique HS-TASK-<suffix> id and prevents duplicates.",
-      severity: "required",
-    },
-    {
-      procedure: "checks-manifest-authoring",
-      why: "Every task ships a FROZEN specs/checks/<task-id>.checks.json — each AC classified machine|property|human with named runnable checks, authored at breakdown before any builder sees the brief. A task without one is not ready to dispatch.",
-      severity: "required",
-    },
-    {
-      procedure: "unit-test-authoring-protocol",
-      why: "How the tests behind the manifest checks are written: pure-core/thin-shell, colocation, the five case families, and the mutation gate as the quality oracle.",
-      severity: "recommended",
-    },
-  ],
-  file_diagnose: [
-    {
-      procedure: "spec-hierarchy",
-      why: "Defines diagnose frontmatter, the standalone-default / optional epic-or-milestone parent rule, and severity.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique HS-DIAG-<suffix> id and prevents duplicates.",
-      severity: "required",
-    },
-    {
-      procedure: "resolution-diagnose-workflow",
-      why: "The end-to-end bug→diagnose procedure: intake, §Step 2 symptom-vs-core classification (if fixing exactly this leaves the same class of failure possible, you are still on the symptom), severity ranking, §Step 6 sibling sweep — which now owes a receipt in the body's ## Sweep section — and close-out.",
-      severity: "required",
-    },
-    {
-      procedure: "checks-manifest-authoring",
-      why: 'A bug is the case where a regression check is worth the most and costs the least — the reproduction is already written. Freeze one runnable check per acceptance criterion via `checks:` on heyspex_file_spec, and make at least one of them FAIL when the fix is reverted; "the test passes now" is also what a symptom-level fix produces. REQUIRED WITH AN OUT: a trivial bug may file with no manifest — filing still succeeds and returns a `no_checks_manifest` warning — but skipping is a decision to state, not a step to forget.',
-      severity: "required",
-    },
-  ],
-  file_research: [
-    {
-      procedure: "capture-guardrails",
-      why: "A brand-new idea surfacing in conversation (no existing HS-CAP-*/HS-RES-* id already in play) goes through Capture → Ground=Expand → Promote-to-research first via heyspex_active_capture — never straight to file_research/research dispatch tooling. Skip only when the research target already has an existing capture or research id.",
-      severity: "recommended",
-    },
-    {
-      procedure: "spec-hierarchy",
-      why: "Confirms research is a standalone entity (HS-RES-<id>), how it links back to consumers, and that promotion defaults to a NEW milestone.",
-      severity: "required",
-    },
-    {
-      procedure: "research-capture-protocol",
-      why: "Required template (Executive Summary + Sources) and the back-wikilink + maintenance rules for a research doc.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique HS-RES-<suffix> id and prevents duplicates.",
-      severity: "required",
-    },
-  ],
-  file_memory_lesson: [
-    {
-      procedure: "memory-protocol",
-      why: "How to file a memory-lesson and link it back to the originating spec; the four-axis capture rubric.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique memory slug/id and prevents duplicates.",
-      severity: "required",
-    },
-  ],
-  file_memory_decision: [
-    {
-      procedure: "memory-protocol",
-      why: "How to file a memory-decision and link it back to the originating spec; the four-axis capture rubric.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique memory slug/id and prevents duplicates.",
-      severity: "required",
-    },
-  ],
-  file_memory_reference: [
-    {
-      procedure: "memory-protocol",
-      why: "How to file a memory-reference and link it back to the originating spec; the four-axis capture rubric.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique memory slug/id and prevents duplicates.",
-      severity: "required",
-    },
-  ],
-  file_memory_ui_pattern: [
-    {
-      procedure: "memory-protocol",
-      why: "How to file a memory-ui-pattern and link it back to the originating spec; the four-axis capture rubric.",
-      severity: "required",
-    },
-    {
-      procedure: "vault-id-assignment-protocol",
-      why: "Allocates a unique memory slug/id and prevents duplicates.",
-      severity: "required",
-    },
-  ],
-  file_review: [
-    {
-      procedure: "session-close-protocol",
-      why: "The HS-REV companion doc shape (four required sections) and the close-out flow it belongs to.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-hierarchy",
-      why: 'Confirms the review parents the spec under review (parent: "[[<spec>]]" is required).',
-      severity: "recommended",
-    },
-  ],
-  file_capture: [
-    {
-      procedure: "capture-guardrails",
-      why: "Captures are session-based and NOT research — human words stay verbatim in `## Notes`; AI authors separate layers on an explicit pass. Drive them via heyspex_active_capture, not heyspex_file_spec.",
-      severity: "required",
-    },
-  ],
-  destructive_action: [
-    {
-      procedure: "destructive-action-checklist",
-      why: "Run before any PR that deletes, archives, or routes data-destroying actions.",
-      severity: "required",
-    },
-    {
-      procedure: "dev-server-lifecycle-and-db-safety",
-      why: "If the action is a DB migration / Neon branch reset / .next delete, stop the running dev server first — check ground-truth status via heyspex_dev_server_status.",
-      severity: "recommended",
-    },
-  ],
-  protocol_edit: [
-    {
-      procedure: "spec-hierarchy",
-      why: '§Agent autonomy row "Modify a protocol doc" — protocol edits require explicit user approval.',
-      severity: "required",
-    },
-  ],
-  memory_creation: [
-    {
-      procedure: "memory-protocol",
-      why: "How to file a lesson/decision/reference/ui-pattern memory and link it back to the originating spec.",
-      severity: "required",
-    },
-  ],
-  close_session: [
-    {
-      procedure: "session-close-protocol",
-      why: "Required agent close-out checklist (status flips, review-doc creation, hand-off). " + "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
-      severity: "required",
-    },
-    {
-      procedure: "memory-protocol",
-      why: "Self-check for learnings is step 0 of close-out — capture any non-obvious lesson/decision as a memory spec.",
-      severity: "recommended",
-    },
-  ],
-  context_rollover: [
-    {
-      procedure: "context-rollover-checkpoint",
-      why: "Lightweight mid-flight checkpoint when compaction interrupts implementation — record WIP + handoff, then resume. Do NOT flip status / write HS-REV (that is session close, not rollover).",
-      severity: "required",
-    },
-  ],
-  claim_spec: [
-    {
-      procedure: "spec-hierarchy",
-      why: "A spec is claimable iff it is its own current ClaimTarget — read §Claim eligibility before claiming an Epic/Milestone with open descendants; the console endpoint returns 409 claim_blocked_by_descendants otherwise ([[HS-TASK-0RVD]]).",
-      severity: "required",
-    },
-    {
-      procedure: "pre-execution-alignment-gate",
-      why: "The /hs-next surface routes the claim through this gate; the brief sections (world_state_new / world_state_modified / graph_delta) and the 4-option menu are documented here.",
-      severity: "recommended",
-    },
-  ],
-  execute_spec: [
-    {
-      procedure: "dev-factory-delegation-routing",
-      why: "The COO operating contract: delegation is table-driven. Before delegating build/breakdown/critic work, consult dev-factory/routing-table.json — build → free local fleet, breakdown/critic → DeepSeek V4, cloud/Opus escalation-only. NEVER spawn a Claude subagent on your own (expensive) tier for mechanical, gate-verified build.",
-      severity: "required",
-    },
-    {
-      procedure: "pre-execution-alignment-gate",
-      why: "The first pre-flight before executing an epic/milestone — break down a childless node or revisit a drifted breakdown; hard gate with override-with-reason.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-hierarchy",
-      why: "Confirms the level you are executing and the parent/child linkage the breakdown must respect.",
-      severity: "recommended",
-    },
-    {
-      procedure: "builder-fleet-capability-reference",
-      why: "Context tier ladder + task Builder brief contract when breaking down or dispatching to the local fleet.",
-      severity: "recommended",
-    },
-    {
-      procedure: "unit-test-authoring-protocol",
-      why: "Before writing any test: pure-core/thin-shell structure, colocated <module>.test.ts, the five case families every pure module covers, and the mutation gate as the test-quality oracle.",
-      severity: "recommended",
-    },
-    {
-      procedure: "checks-manifest-authoring",
-      why: "The frozen specs/checks/<task-id>.checks.json is the external completion gate — builders satisfy its named checks and never edit it; hs check run <task-id> is the per-criterion verdict.",
-      severity: "recommended",
-    },
-    {
-      procedure: "dev-server-lifecycle-and-db-safety",
-      why: "Execution often involves DB migrations / dependency installs / .next deletes that break a running dev server — check ground-truth status (heyspex_dev_server_status) and stop the server first.",
-      severity: "recommended",
-    },
-  ],
-  exit_plan_mode: [
-    {
-      procedure: "plan-quality-canonical-check",
-      why: "Run dual overlap+code audit and canonical/supersession check before exit; revise plan to V2.",
-      severity: "required",
-    },
-    {
-      procedure: "plan-ingest-agent-workflow",
-      why: "After the plan is approved, do NOT start coding. First ingest the approved plan into the vault as an epic (file it with children:[]; tasks fan out later via /hs-next) AND claim it via heyspex_claim_spec before executing. ExitPlanMode is the plan→execute seam — without this step agents skip filing+claiming and go straight to code.",
-      severity: "required",
-    },
-    {
-      procedure: "supersession-protocol",
-      why: "If the plan deprecates an existing spec, file the supersession edge per protocol.",
-      severity: "recommended",
-    },
-  ],
-  recommend_location: [
-    {
-      procedure: "rule-placement-protocol",
-      why: "Cost ranking for where a new rule belongs: procedure ≥ memory > spec > CLAUDE.md. CLAUDE.md is the most expensive surface (always-loaded, customer-inherited) — never the default.",
-      severity: "required",
-    },
-    {
-      procedure: "memory-protocol",
-      why: "When the right home is a memory (rank 2 in rule-placement-protocol), this defines the lesson/decision/reference/ui-pattern shape and tagging conventions.",
-      severity: "recommended",
-    },
-    {
-      procedure: "foundations-placement-protocol",
-      why: "When the thing to place is a high-level vision/strategy concept (a principle, a north-star idea, a business claim) rather than an agent-behavior rule: ranks the foundations homes (North Star > Operating Model > Principles > Architecture > Positioning > Research) and gates a foundational edit behind user sign-off.",
-      severity: "recommended",
-    },
-  ],
-  focus_pivot: [
-    {
-      procedure: "focus-intent-routing",
-      why: 'How to detect a roadmap focus-pivot utterance and route it through heyspex_set_focus_areas — covers negation handling ("stop working on X" must NOT add X), the closed-tag-vocabulary constraint (heyspex_list_known_tags first), and the confirmation beat before applying.',
-      severity: "required",
-    },
-  ],
-  server_impacting_action: [
-    {
-      procedure: "dev-server-lifecycle-and-db-safety",
-      why: "Before a DB migration, Neon branch reset, dependency install, .next delete, or starting a second dev server: check ground-truth status (heyspex_dev_server_status / `hs server status`) and stop a live server first — running a migration under a live server strands its in-memory schema and forces a restart.",
-      severity: "required",
-    },
-  ],
-  restructure_content: [
-    {
-      procedure: "internal-linking-protocol",
-      why: "Before re-parenting an epic, editing a milestone epics[] roster, or moving trackable work to a new canonical home — leave a summary + wikilink stub at the old home so wikilinks and lexical retrieval signal are preserved.",
-      severity: "required",
-    },
-    {
-      procedure: "section-supersede-protocol",
-      why: "Before editing or deleting a section that has gone stale: the three-way test for edit-in-place vs supersede-the-section vs retire-the-whole-document, the stub properties a reviewer checks, and the rule that the repair stays a proposal a person approves — a linked heading is never silently rewritten.",
-      severity: "required",
-    },
-    {
-      procedure: "spec-hierarchy",
-      why: "Confirms bidirectional linkage shape (epics: ⇄ milestone:, children: ⇄ parent:) that re-parent edits must maintain.",
-      severity: "recommended",
-    },
-    {
-      procedure: "supersession-protocol",
-      why: "If the move replaces dead guidance (not merely relocates live work), use supersession instead of a cross-reference stub.",
-      severity: "recommended",
-    },
-    {
-      procedure: "doc-canonicalization-protocol",
-      why: "If the restructure is an evergreen-doc split/merge rather than plan-side re-parent, use doc-canonicalization instead.",
-      severity: "recommended",
-    },
-  ],
-};
-
-const VALID_INTENTS = Object.keys(PREFLIGHT_INTENT_MAP);
-
-// Maps a file_* intent to the canonical filing tool the agent should call.
-// This is the core of [[HS-EPIC-WDP3]]: surface the deterministic tool inline
-// in the preflight response so an agent that reaches the procedure layer is
-// routed at the right answer — instead of pattern-matching a sibling spec's
-// frontmatter. Every non-capture kind files via heyspex_file_spec (the server
-// generates frontmatter from the canonical template); captures are
-// session-based and route at heyspex_active_capture. Intents not listed here
-// (destructive_action, protocol_edit, close_session, claim_spec, execute_spec,
-// recommend_location) govern actions, not spec creation — close_session carries
-// close_tool; others carry no filing_tool block.
-const CLOSE_TOOL_MAP = {
-  close_session: {
-    tool: "heyspex_submit_for_review",
-    minimal_call: { spec_id: "<completed-review-unit-or-task-id>" },
-    note: "Status SSOT is PATCH /api/specs/:id/status — not frontmatter edits. This tool applies review-grain coercion, parent rollup, and releases the claim. Still run session-close-protocol steps 2–7 (change-log, HS-REV or review seed, WIP, export).",
-  },
-};
-
-// Build the close_tool block for action intents that flip status at session end.
-function buildCloseTool(intent) {
-  return CLOSE_TOOL_MAP[intent] ?? null;
-}
-
-const FILE_SPEC_NOTE =
-  "Use this. The server generates frontmatter from the canonical template. Do not compose frontmatter from a sibling spec.";
-const FILING_TOOL_MAP = {
-  file_milestone: { type: "milestone" },
-  file_epic: {
-    type: "epic",
-    parentKey: "milestone",
-    parentExample: "[[HS-MIL-...]]",
-  },
-  file_task: {
-    type: "task",
-    parentKey: "parent",
-    parentExample: "[[HS-EPIC-...]]",
-  },
-  file_diagnose: {
-    type: "diagnose",
-    note: `${FILE_SPEC_NOTE} By default a diagnose is filed standalone — it has no parent and does not nest under any epic or milestone, so it lives on its own in the Resolution lane rather than inside a planned work item. Keep it standalone for a cross-cutting bug, or one that isn't part of any single epic's or milestone's scope (the common case). Only set parent: "[[HS-EPIC-...]]" or "[[HS-MIL-...]]" when the bug clearly belongs to that epic's or milestone's work and you want it tracked under it.`,
-  },
-  file_research: { type: "research" },
-  file_memory_lesson: { type: "memory-lesson" },
-  file_memory_decision: { type: "memory-decision" },
-  file_memory_reference: { type: "memory-reference" },
-  file_memory_ui_pattern: { type: "memory-ui-pattern" },
-  file_review: {
-    type: "review",
-    parentKey: "parent",
-    parentExample: "[[<spec-under-review>]]",
-    note: `${FILE_SPEC_NOTE} A review's parent is the spec it reviews — parent is required.`,
-  },
-  file_capture: {
-    tool: "heyspex_active_capture",
-    minimal_call: { spec_id: "<HS-CAP-...>" },
-    note: "Captures are session-based; use heyspex_active_capture, NOT heyspex_file_spec.",
-  },
-};
-
-// Build the filing_tool block for a given intent, or null when the intent does
-// not create a spec.
-function buildFilingTool(intent) {
-  const spec = FILING_TOOL_MAP[intent];
-  if (!spec) return null;
-  // Captures (and any future bespoke tool) carry an explicit shape.
-  if (spec.tool) {
-    return {
-      tool: spec.tool,
-      minimal_call: spec.minimal_call,
-      note: spec.note,
-    };
-  }
-  const minimal_call = { type: spec.type };
-  if (spec.parentKey) minimal_call[spec.parentKey] = spec.parentExample;
-  minimal_call.name = "<title>";
-  return {
-    tool: "heyspex_file_spec",
-    minimal_call,
-    note: spec.note ?? FILE_SPEC_NOTE,
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Thread-type-aware session close-out ([[HS-RES-32MJ]]). Close-out is NOT
-// one-size-fits-all: the thread type decides whether there is a close at all and
-// which steps run; the grain ladder (session-close-protocol) decides which spec
-// is the review unit on the execution paths. Thread-type is DECLARED, not
-// inferred — two of the five candidate signals (specs-filed-by-type,
-// research-saved) are not session-scoped on either tier, so a positive
-// declaration is the robust path. Mirrors the prose decision table in
-// session-close-protocol §"Thread-type close-out".
-// ─────────────────────────────────────────────────────────────────────────────
-const CLOSE_SESSION_THREAD_PATHS = {
-  capture_only: {
-    label: "Capture-only — brain-offload via /hs-capture; no claim, no code",
-    is_close: false,
-    close_tool: false,
-    procedures: ["research-capture-protocol"],
-    steps: [
-      "No session close-out is owed — a capture is not a review unit.",
-      "Exit = promote to research (heyspex_promote_capture) or leave the capture pinned.",
-      "Do NOT submit_for_review, mint an HS-REV, record a WIP ledger, or flush an audit export.",
-    ],
-  },
-  research_only: {
-    label: "Research-only — saved an HS-RES; no claimed spec",
-    is_close: false,
-    close_tool: false,
-    procedures: ["research-capture-protocol"],
-    steps: [
-      "Save findings via heyspex_save_research / heyspex_complete_research (external scope needs >=1 cited URL).",
-      "Research is evergreen: do NOT submit_for_review or flip status, and do NOT mint an HS-REV.",
-      "No execution WIP ledger is owed. Audit export (heyspex_export_events) is optional.",
-    ],
-  },
-  plan_ingest_only: {
-    label: "Plan/ingest-only — filed milestone+epics; no task execution",
-    is_close: false,
-    close_tool: false,
-    procedures: ["plan-ingest-agent-workflow", "spec-hierarchy"],
-    steps: [
-      "Confirm every new spec is registered + linked: heyspex_validate_linkage (heyspex_register_spec for any orphan).",
-      "Confirm each milestone/epic carries an authored summary and a re-derived ## Intended outcome.",
-      "No task close, no HS-REV, no execution WIP ledger — epics are filed with children: [].",
-    ],
-  },
-  one_task: {
-    label: "One-task execution — claimed and completed a single task",
-    is_close: true,
-    close_tool: true,
-    procedures: ["session-close-protocol", "memory-protocol"],
-    steps: [
-      "heyspex_submit_for_review({ spec_id }) on the completed unit (status API SSOT — never hand-edit status:). Grain-coercion, parent rollup, and claim release happen server-side.",
-      "Append a change-log roll-up / review seed to the task.",
-      "Create an HS-REV companion + parent ## Review back-link ONLY if the active review grain is task; otherwise the change-log seed is enough.",
-      "heyspex_record_wip for the worked epic (skip only if the epic closed this session).",
-      "heyspex_export_events to flush the audit log. Do NOT git commit / push.",
-      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
-    ],
-  },
-  multi_task_epic: {
-    label: "Multi-task / epic push — completed several tasks under an epic",
-    is_close: true,
-    close_tool: true,
-    procedures: ["session-close-protocol", "memory-protocol"],
-    steps: [
-      "heyspex_submit_for_review on each completed unit; parent rollup is automatic when the last child lands.",
-      "One consolidated change-log + the HS-REV companion at the ACTIVE review grain (epic in steady-state, milestone in MVP).",
-      "heyspex_record_wip once for the worked epic; heyspex_export_events; do NOT git commit / push.",
-      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
-    ],
-  },
-  resolve_diagnose: {
-    label: "Resolve / diagnose — worked an HS-DIAG or a Resolution item",
-    is_close: true,
-    close_tool: true,
-    procedures: ["session-close-protocol", "resolution-diagnose-workflow"],
-    steps: [
-      "If the flag was a stale-cache false positive (the file on disk contradicts it): re-stamp via heyspex_record_alignment — do NOT re-file work that already exists.",
-      "If a real diagnose/fix completed: heyspex_submit_for_review on it + change-log; HS-REV per active grain.",
-      "heyspex_record_wip if anything remains open; heyspex_export_events.",
-      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
-    ],
-  },
-  mid_rollover: {
-    label: "Mid-implementation rollover — claimed but not finished",
-    is_close: false,
-    close_tool: false,
-    procedures: ["context-rollover-checkpoint"],
-    steps: [
-      "This is NOT a session close. Do NOT flip status, mint an HS-REV, or submit_for_review.",
-      "Record a lightweight WIP checkpoint (heyspex_record_wip) so the next session resumes; leave the spec in_progress.",
-      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
-      'See heyspex_preflight({ intent: "context_rollover" }) / the context-rollover-checkpoint procedure for the full checkpoint shape.',
-    ],
-  },
-};
-
-const CLOSE_SESSION_THREAD_TYPES = Object.keys(CLOSE_SESSION_THREAD_PATHS);
-
-const CLOSE_SESSION_MIXED_RULE =
-  "If the session spanned MORE THAN ONE thread type (e.g. filed a plan AND finished a task), request each applicable type and run the UNION of their steps — ordered, idempotent (re-running submit_for_review / export_events is safe), and surface the ambiguity. Never drop an owed obligation; never duplicate one.";
-
-function buildCloseSessionPreflight(vaultRoot, threadType, injectedCatalog) {
-  const path = CLOSE_SESSION_THREAD_PATHS[threadType];
-  if (!path) {
-    return {
-      error: "UNKNOWN_THREAD_TYPE",
-      message: `Unknown thread_type "${threadType}" for close_session. Valid thread types: ${CLOSE_SESSION_THREAD_TYPES.join(", ")}.`,
-    };
-  }
-  const catalog =
-    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
-  if (!catalog) {
-    return {
-      error: "CATALOG_NOT_FOUND",
-      message:
-        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
-    };
-  }
-  const procedures = path.procedures.map((name) =>
-    resolveRow(catalog, { procedure: name, severity: "required" }),
-  );
-  const close_tool = path.close_tool ? buildCloseTool("close_session") : null;
-  return {
-    intent: "close_session",
-    thread_type: threadType,
-    thread_label: path.label,
-    is_close: path.is_close,
-    steps: path.steps,
-    procedures,
-    mixed_thread_rule: CLOSE_SESSION_MIXED_RULE,
-    ...(close_tool ? { close_tool } : {}),
-  };
-}
-
-/**
- * `injectedCatalog` — see {@link executeListProcedures}; same contract here
- * (threaded through to `buildCloseSessionPreflight` for the close_session
- * thread-type path too, so a single HTTP fetch covers both branches).
- */
-export function executeRunPreflight(vaultRoot, args = {}, injectedCatalog) {
-  const intent = String(args.intent ?? "").trim();
-  if (!intent) {
-    return {
-      error: "MISSING_INTENT",
-      message: `intent is required. Valid intents: ${VALID_INTENTS.join(", ")}.`,
-    };
-  }
-  // Thread-type-aware close-out: when a thread_type is declared, return that
-  // type's CONDITIONAL close path instead of the static checklist ([[HS-RES-32MJ]]).
-  const threadType = String(args.thread_type ?? "").trim();
-  if (intent === "close_session" && threadType) {
-    return buildCloseSessionPreflight(vaultRoot, threadType, injectedCatalog);
-  }
-  const recommendations = PREFLIGHT_INTENT_MAP[intent];
-  if (!recommendations) {
-    return {
-      error: "UNKNOWN_INTENT",
-      message: `Unknown intent "${intent}". Valid intents: ${VALID_INTENTS.join(", ")}.`,
-    };
-  }
-  const catalog =
-    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
-  if (!catalog) {
-    return {
-      error: "CATALOG_NOT_FOUND",
-      message:
-        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
-    };
-  }
-
-  const procedures = recommendations.map((row) => resolveRow(catalog, row));
-
-  const filing_tool = buildFilingTool(intent);
-  const close_tool = buildCloseTool(intent);
-
-  const result = {
-    intent,
-    procedures,
-    ...(filing_tool ? { filing_tool } : {}),
-    ...(close_tool ? { close_tool } : {}),
-  };
-
-  // Family-overlap advisory for filing intents: warn agents to check whether
-  // a closed family already covered this goal with no iterates_on edge.
-  const FILING_ADVISORY =
-    "Family-overlap check (warn-only): before filing, check whether a CLOSED family already shipped against this goal with no iterates_on: edge — compare both TITLE and JTBD (job-to-be-done) statement, not title alone, since two differently-titled specs can still be the same job (owner-approved 2026-08-23 job-based-duplicate-detection extension) — if so this may be round 2; see entity-model §Iteration lineage. Never blocks filing.";
-  const FILING_INTENTS_WITH_ADVISORY = [
-    "file_epic",
-    "file_task",
-    "promote_research",
-  ];
-  if (FILING_INTENTS_WITH_ADVISORY.includes(intent)) {
-    result.advisory = FILING_ADVISORY;
-  }
-
-  // Static close_session call (no thread_type declared): nudge toward the
-  // conditional path so the agent runs the right minimal-complete close-out.
-  if (intent === "close_session") {
-    result.thread_type_hint = {
-      note: 'Close-out is thread-type-aware. Re-call heyspex_preflight({ intent: "close_session", thread_type: "<type>" }) to get the conditional close path for what this session actually did.',
-      thread_types: CLOSE_SESSION_THREAD_TYPES.map((t) => ({
-        thread_type: t,
-        label: CLOSE_SESSION_THREAD_PATHS[t].label,
-        is_close: CLOSE_SESSION_THREAD_PATHS[t].is_close,
-      })),
-      mixed: CLOSE_SESSION_MIXED_RULE,
-    };
-  }
-
-  // [[HS-EN4F]]: research intents carry the absolute hs-res route.
-  if (RESEARCH_TOOLING_INTENTS.includes(intent)) {
-    const research_tooling = buildResearchTooling();
-    if (research_tooling) result.research_tooling = research_tooling;
-  }
-
-  return result;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// [[HS-EN4F]] — the hs-res route, in absolute paths. The /hs-res command and
-// its SKILL.md spell the gather/synthesis CLIs repo-relative
-// (`node dev-factory/spexcrawl/...`), which only resolves inside the platform
-// checkout. An agent in a customer repo (sales-coach, 2026-10-02) looked for
-// hs-res there, did not find it, concluded "the tooling isn't installed" and
-// fanned out Sonnet subagents on WebSearch. The research preflight is the one
-// call every research path must make (the HS-K0ZP gate refuses WebSearch /
-// WebFetch until it runs), so it carries the route: absolute commands derived
-// from where THIS module sits — the MCP server serving the customer repo runs
-// out of the platform checkout, so these paths resolve from any working
-// directory. Null when the platform does not ship the CLIs (published package).
-// ─────────────────────────────────────────────────────────────────────────────
-const RESEARCH_TOOLING_INTENTS = [
-  "research",
-  "file_research",
-  "promote_research",
-];
-const DEFAULT_PLATFORM_ROOT = resolve(
-  dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "..",
-);
-
-export function buildResearchTooling(
-  platformRoot = DEFAULT_PLATFORM_ROOT,
-  exists = existsSync,
-) {
-  const abs = (...parts) => join(platformRoot, ...parts).replace(/\\/g, "/");
-  const spexcrawl = abs("dev-factory", "spexcrawl", "spexcrawl-cli.mjs");
-  const firecrawl = abs("dev-factory", "spexcrawl", "firecrawl-cli.mjs");
-  const synthesize = abs("dev-factory", "spexcrawl", "synthesize-cli.mjs");
-  const skill = abs(".commandcode", "skills", "hs-res", "SKILL.md");
-  if (![spexcrawl, firecrawl, synthesize].every((p) => exists(p))) return null;
-  return {
-    method:
-      "hs-res (the confidence ladder) — URL DISCOVERY defaults to self-hosted Firecrawl search; FULL-PAGE fetch of each cited URL defaults to SpexCrawl scrape (Firecrawl scrape is a per-URL retry only); DeepSeek synthesizes. Zero Claude/Anthropic sub-agents. Owner ruling 2026-10-10: SpexCrawl search is blocked on all four engines, so it is no longer the default discovery step. Hosted api.firecrawl.dev stays ask-before-spend and is never a default.",
-    note: "These commands run from ANY repo. A project with no /hs-res command or skill of its own does NOT mean the tooling is missing — use these absolute paths. Firecrawl search returns titles/URLs/snippets only: snippets are discovery, never evidence — scrape the full page of every URL you cite. Native WebSearch/WebFetch is the last resort only when both backends report unavailable; never fan out Sonnet sub-agents for research.",
-    skill_path: exists(skill) ? skill : null,
-    // Owner ruling 2026-10-10 (HS-5PG6): discovery = Firecrawl search, fetch = SpexCrawl scrape.
-    discover_primary: `node "${firecrawl}" search "<query>" --json`,
-    fetch_primary: `node "${spexcrawl}" scrape "<url>" --json`,
-    fetch_retry: `node "${firecrawl}" scrape "<url>" --json`,
-    optional_combined: `node "${spexcrawl}" search "<query>" --json`,
-    // Legacy field names kept for existing consumers. They now mirror the new
-    // order: gather_* = discovery, scrape_* = fetch. `gather_primary` is NO
-    // LONGER SpexCrawl search (that moved to optional_combined).
-    gather_primary: `node "${firecrawl}" search "<query>" --json`,
-    gather_fallback: `node "${spexcrawl}" search "<query>" --json`,
-    scrape_primary: `node "${spexcrawl}" scrape "<url>" --json`,
-    scrape_fallback: `node "${firecrawl}" scrape "<url>" --json`,
-    synthesize: `node "${synthesize}" --prompt-file <path> --json`,
-    grounding_first:
-      "Before any gather: method triage (known-target-retrieval vs the ladder), ground-first (heyspex_recall_memories), and check for a working reference the owner already runs (e.g. `docker ps` for a local Firecrawl on :3002). Record the four-part grounding result (already built / already decided / owner reference / residual delta).",
-  };
-}
-
-export const PREFLIGHT_INTENTS = VALID_INTENTS;
-export { CLOSE_SESSION_THREAD_TYPES };
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Read-path selector wiring ([[HS-DJWP-MCPC-TASK-wire-the-mcp-server-s-vault-reads]]
-// of [[HS-T6GS-MCPC-EPIC-mcp-server-reads-the-vault-through-the]]).
-//
-// The three functions below are the cloud-reliant siblings of
-// `executeListProcedures` / `executeGetProcedure` / `executeRunPreflight`.
-// They never call `loadCatalog(vaultRoot)` in the `neon` tier — the catalog
-// (or, for `executeGetProcedureViaTier`, the full procedure body) is fetched
-// once over HTTP via the caller-supplied `consoleFetch` and handed to the
-// existing pure functions as an `injectedCatalog`, so the filtering /
-// preflight-mapping logic itself is never duplicated. In `disk` tier each
-// wrapper calls the untouched, byte-for-byte-unchanged pure function — same
-// disk-only code path as before this task.
-//
-// `consoleFetch` is passed in (not imported) because this module is
-// deliberately transport-free "pure-logic" (see file header) — cli.mjs owns
-// the bound `makeConsoleFetch` client and threads it through here, mirroring
-// how `readViaSelector` itself never imports console-fetch.mjs.
-// ─────────────────────────────────────────────────────────────────────────────
-
-/** Row shape from `GET /api/procedures` — mirrors `summarize()` above (see that route's docstring: "do not invent a new shape here"). */
-function catalogFromProceduresRoute(body) {
-  const rows = Array.isArray(body?.procedures) ? body.procedures : [];
-  return { procedures: rows };
-}
-
-/**
- * Fetch the procedure catalog via `GET /api/procedures` (disk: `loadCatalog`).
- * Exported for callers that need the raw catalog object outside the three
- * higher-level wrappers below (none today; kept for symmetry / testability).
- */
-export async function loadCatalogViaTier({
-  vaultRoot,
-  tier,
-  consoleFetch,
-  consoleUrl,
-}) {
-  return readViaSelector({
-    tier,
-    diskRead: () => loadCatalog(vaultRoot),
-    neonRead: async () => {
-      const res = await consoleFetch("/api/procedures");
-      if (!res.ok) {
-        throw consoleReadErrorFrom(res, `GET /api/procedures returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
-      }
-      return catalogFromProceduresRoute(res.body);
-    },
-    routeLabel: "GET /api/procedures",
-    consoleUrl,
-  });
-}
-
-/** Cloud-reliant sibling of {@link executeListProcedures}. */
-export async function executeListProceduresViaTier(opts) {
-  const { value, degraded } = await withDegradationScope(() => executeListProceduresViaTierInner(opts));
-  return mergeDegradation(value, degraded);
-}
-
-async function executeListProceduresViaTierInner({
-  vaultRoot,
-  args,
-  tier,
-  consoleFetch,
-  consoleUrl,
-}) {
-  return readViaSelector({
-    tier,
-    diskRead: () => executeListProcedures(vaultRoot, args),
-    neonRead: async () => {
-      const catalog = await loadCatalogViaTier({
-        vaultRoot,
-        tier: "neon",
-        consoleFetch,
-        consoleUrl,
-      });
-      if (!catalog) {
-        return {
-          error: "CATALOG_NOT_FOUND",
-          message:
-            "GET /api/procedures returned no catalog (console reports it missing).",
-        };
-      }
-      // Filtering happens HERE, client-side — the route has no tag/trigger/query
-      // params (it always answers the full unfiltered set), unlike the disk path
-      // which filters inside executeListProcedures itself. Passing the fetched
-      // catalog as `injectedCatalog` runs the SAME filter logic either way.
-      return executeListProcedures(vaultRoot, args, catalog);
-    },
-    routeLabel: "GET /api/procedures",
-    consoleUrl,
-  });
-}
-
-/** Cloud-reliant sibling of {@link executeGetProcedure}. Single round trip: `GET /api/procedures/<name>` returns catalog entry + full body together. */
-export async function executeGetProcedureViaTier({
-  vaultRoot,
-  args,
-  tier,
-  consoleFetch,
-  consoleUrl,
-}) {
-  return readViaSelector({
-    tier,
-    diskRead: () => executeGetProcedure(vaultRoot, args),
-    neonRead: async () => {
-      const name = String(args?.name ?? "").trim();
-      if (!name) {
-        return {
-          error: "MISSING_NAME",
-          message: 'name is required (e.g. "spec-hierarchy")',
-        };
-      }
-      const res = await consoleFetch(
-        `/api/procedures/${encodeURIComponent(name)}`,
-      );
-      if (res.ok) {
-        return {
-          procedure: res.body?.procedure,
-          content: res.body?.content,
-          source: res.body?.source ?? null,
-        };
-      }
-      // Aligned with the sibling *ViaTier functions ([[HS-DJWP-MCPC-TASK]]
-      // round 3 fix — a 500 {error:'boom'} was previously swallowed as a real
-      // answer regardless of status code): ONLY a 404 PROCEDURE_NOT_FOUND is a
-      // real "no such procedure" answer, matching the route's own contract
-      // (its docstring: "an unknown name is a 404 error code, never an empty
-      // 200 success"). Everything else — a 500 CATALOG_NOT_FOUND included, a
-      // reachable console reporting a server-side config break — throws so the
-      // selector surfaces CONSOLE_UNREACHABLE_CLOUD_MODE rather than silently
-      // degrading; the epic's no-silent-degrade rule treats "console answered,
-      // but the answer means something is broken" the same as unreachable.
-      if (res.status === 404 && res.body?.error === "PROCEDURE_NOT_FOUND") {
-        return { error: res.body.error, message: res.body.message };
-      }
-      throw consoleReadErrorFrom(
-        res,
-        `GET /api/procedures/${name} returned ${res.status}: ${res.body?.error ? `${res.body.error}${res.body.message ? ` — ${res.body.message}` : ""}` : res.error || JSON.stringify(res.body ?? {})}`,
-        null,
-      );
-    },
-    routeLabel: "GET /api/procedures/[name]",
-    consoleUrl,
-  });
-}
-
-/** Cloud-reliant sibling of {@link executeRunPreflight}. One catalog fetch covers both the static intent map AND the close_session thread-type path. */
-export async function executeRunPreflightViaTier(opts) {
-  const { value, degraded } = await withDegradationScope(() => executeRunPreflightViaTierInner(opts));
-  return mergeDegradation(value, degraded);
-}
-
-async function executeRunPreflightViaTierInner({
-  vaultRoot,
-  args,
-  tier,
-  consoleFetch,
-  consoleUrl,
-}) {
-  return readViaSelector({
-    tier,
-    diskRead: () => executeRunPreflight(vaultRoot, args),
-    neonRead: async () => {
-      const catalog = await loadCatalogViaTier({
-        vaultRoot,
-        tier: "neon",
-        consoleFetch,
-        consoleUrl,
-      });
-      if (!catalog) {
-        return {
-          error: "CATALOG_NOT_FOUND",
-          message:
-            "GET /api/procedures returned no catalog (console reports it missing).",
-        };
-      }
-      return executeRunPreflight(vaultRoot, args, catalog);
-    },
-    routeLabel: "GET /api/procedures",
-    consoleUrl,
-  });
-}
+/**
+ * HeySpex procedure-discovery MCP tools.
+ *
+ * Pure-logic module backing the `heyspex_list_procedures`,
+ * `heyspex_get_procedure`, and `heyspex_preflight` MCP tools mounted in
+ * cli.mjs. Reads the committed catalog at specs/protocols/.catalog.json
+ * (generated by scripts/build-procedure-catalog.mjs) and the underlying
+ * markdown bodies under specs/protocols/.
+ *
+ * Spec: [[HS-EPIC-3QS8-agent-procedure-discovery-enforcement-la]]
+ * Pattern source: vendor/heyspex-mcp/design-tools.mjs (the
+ * heyspex_design_* family is the canonical template this module mirrors).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { consoleReadErrorFrom, mergeDegradation, readViaSelector, withDegradationScope } from "./read-path.mjs";
+import { pageListToolResult } from "./list-tools.mjs";
+import { isDevFactoryOverlayOpen } from "./dev-factory-overlay.mjs";
+
+const CATALOG_FILE = ["specs", "protocols", ".catalog.json"];
+const PROTOCOLS_DIR = ["specs", "protocols"];
+
+function normalize(value) {
+  return String(value ?? "").toLowerCase();
+}
+
+export function loadCatalog(vaultRoot) {
+  const path = join(vaultRoot, ...CATALOG_FILE);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function summarize(entry) {
+  return {
+    name: entry.name,
+    id: entry.id,
+    title: entry.title,
+    tags: Array.isArray(entry.tags) ? entry.tags : [],
+    triggers: Array.isArray(entry.triggers) ? entry.triggers : [],
+    summary: entry.summary ?? "",
+    path: entry.path,
+  };
+}
+
+/**
+ * `injectedCatalog` (HS-DJWP-MCPC-TASK read-path wiring): when provided, used
+ * verbatim INSTEAD of `loadCatalog(vaultRoot)` — the cloud-reliant selector
+ * wrapper below fetches the catalog once over HTTP and injects it here so
+ * this function never touches disk in that tier. `undefined` (the default)
+ * preserves today's disk-only behavior byte-for-byte.
+ */
+export function executeListProcedures(vaultRoot, args = {}, injectedCatalog) {
+  const catalog =
+    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
+  if (!catalog) {
+    return {
+      error: "CATALOG_NOT_FOUND",
+      message:
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
+    };
+  }
+  const procedures = Array.isArray(catalog.procedures)
+    ? catalog.procedures
+    : [];
+  const tagFilter = args.tag ? normalize(args.tag) : null;
+  const triggerFilter = args.trigger ? normalize(args.trigger) : null;
+  const queryFilter = args.query ? normalize(args.query) : null;
+
+  const matches = [];
+  for (const entry of procedures) {
+    if (tagFilter) {
+      const tags = (entry.tags ?? []).map(normalize);
+      if (!tags.includes(tagFilter)) continue;
+    }
+    if (triggerFilter) {
+      const triggers = (entry.triggers ?? []).map(normalize);
+      if (!triggers.includes(triggerFilter)) continue;
+    }
+    if (queryFilter) {
+      const haystack = [entry.name, entry.title, entry.summary]
+        .map(normalize)
+        .join(" ");
+      if (!haystack.includes(queryFilter)) continue;
+    }
+    matches.push(summarize(entry));
+  }
+
+  // One page on a (name, id) keyset cursor, fitted to the byte budget of the
+  // tool — never the whole catalog, never a total count
+  // ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).
+  const paged = pageListToolResult("heyspex_list_procedures", matches, args, {
+    keyOf: (p) => p.name,
+    idOf: (p) => p.id ?? p.name,
+    extra: {
+      filters_applied: {
+        tag: args.tag ?? null,
+        trigger: args.trigger ?? null,
+        query: args.query ?? null,
+      },
+    },
+  });
+  if (paged.error) return paged.error;
+  return paged.result;
+}
+
+function findEntry(catalog, name) {
+  const procedures = Array.isArray(catalog.procedures)
+    ? catalog.procedures
+    : [];
+  return procedures.find((p) => p.name === name) || null;
+}
+
+export function executeGetProcedure(vaultRoot, args = {}) {
+  const name = String(args.name ?? "").trim();
+  if (!name) {
+    return {
+      error: "MISSING_NAME",
+      message: 'name is required (e.g. "spec-hierarchy")',
+    };
+  }
+  const catalog = loadCatalog(vaultRoot);
+  if (!catalog) {
+    return {
+      error: "CATALOG_NOT_FOUND",
+      message:
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
+    };
+  }
+  const entry = findEntry(catalog, name);
+  if (!entry) {
+    return {
+      error: "PROCEDURE_NOT_FOUND",
+      message: `No procedure named "${name}" in catalog. Call heyspex_list_procedures to browse.`,
+    };
+  }
+  const bodyPath = join(vaultRoot, ...PROTOCOLS_DIR, `${name}.md`);
+  if (!existsSync(bodyPath)) {
+    return {
+      error: "BODY_FILE_MISSING",
+      message: `Catalog entry exists but ${entry.path} not found on disk. Regenerate the catalog.`,
+    };
+  }
+  const content = readFileSync(bodyPath, "utf8");
+  return {
+    procedure: {
+      name: entry.name,
+      id: entry.id,
+      title: entry.title,
+      tags: Array.isArray(entry.tags) ? entry.tags : [],
+      triggers: Array.isArray(entry.triggers) ? entry.triggers : [],
+      summary: entry.summary ?? "",
+      path: entry.path,
+      status: entry.status ?? null,
+      created: entry.created ?? null,
+      lastModified: entry.lastModified ?? null,
+      byteSize: entry.byteSize ?? null,
+    },
+    content,
+    source: entry.path,
+  };
+}
+
+/**
+ * Procedures every customer vault ships (the universal template protocols; a
+ * drift test pins this list to the template manifest's protocol dests). Every
+ * other PREFLIGHT_INTENT_MAP procedure is platform-only: a vault whose runtime
+ * catalog lacks it gets the row DEMOTED to advisory by {@link resolveRow}, never
+ * deleted. Promoting more procedures to universal is a later template version.
+ */
+export const UNIVERSAL_PROCEDURES = Object.freeze([
+  "canonical-frontmatter-templates",
+  "spec-hierarchy",
+  "memory-protocol",
+  "session-close-protocol",
+  "spec-summary-authoring",
+  "destructive-action-checklist",
+]);
+
+/** Audience of a preflight row, by procedure name. */
+export function procedureAudience(name) {
+  return UNIVERSAL_PROCEDURES.includes(name) ? "universal" : "platform";
+}
+
+const DEMOTED_REASON = "not in this vault's catalog (platform-only procedure)";
+
+/**
+ * Resolve one preflight row against the supplied (runtime) catalog. Shared by
+ * the static intent path AND the close_session thread-type path. A row whose
+ * procedure is present is returned exactly as before; an absent one is demoted
+ * to `advisory` (original severity kept in `demoted_from`) with
+ * `missing_from_catalog: true` still set for consumers.
+ */
+export function resolveRow(catalog, row) {
+  const entry = findEntry(catalog, row.procedure);
+  const base = {
+    procedure: row.procedure,
+    ...(row.why !== undefined ? { why: row.why } : {}),
+    severity: row.severity,
+    path: entry?.path ?? null,
+    title: entry?.title ?? null,
+    missing_from_catalog: entry ? undefined : true,
+  };
+  if (entry) return base;
+  return {
+    ...base,
+    severity: "advisory",
+    demoted_from: row.severity,
+    reason: DEMOTED_REASON,
+  };
+}
+
+// Bootstrap intent → procedure map (eight intents per HS-EPIC-3QS8 §Open
+// questions "Trigger taxonomy"). Each row names the procedure slug (matches
+// specs/protocols/<slug>.md), a `why` blurb the agent can quote, and a
+// severity. Extension rule: add a new intent when a third unique use case
+// appears — new intents land in their own tasks, not edits to this map.
+const PREFLIGHT_INTENT_MAP = {
+  // [[HS-K0ZP]]: "about to do research" is a governed trigger. Running this
+  // preflight writes the proof-of-use marker that unlocks WebSearch / WebFetch /
+  // heyspex_save_research for the session (spexharness/src/gates/research-protocol-gate.mjs
+  // on every PreToolUse front, preflight-gate.mjs inside the MCP server). Before
+  // it, those calls are refused -- the protocol was prose an agent could skip.
+  research: [
+    {
+      procedure: "research-capture-protocol",
+      why: "Method triage FIRST (known-target-retrieval vs the confidence ladder), ground-first (heyspex_recall_memories + /hs-ground) before any external pass, and the offer-before-save step: a web search offers to save findings, it does not auto-file a research doc.",
+      severity: "required",
+    },
+    {
+      procedure: "capture-guardrails",
+      why: "A known-target lookup never enters the research-doc pipeline; the exit for a quick retrieval is a memory-reference or a fold into the consuming spec.",
+      severity: "recommended",
+    },
+  ],
+  promote_research: [
+    {
+      procedure: "research-capture-protocol",
+      why: "Confirm the research doc is complete (prerequisites, conclusion, sources) before promotion.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-hierarchy",
+      why: "Mandatory default: target_milestone NEW. Existing-milestone attach only when status: open and thesis clearly extends; in_progress requires explicit owner override.",
+      severity: "required",
+    },
+    {
+      procedure: "pillar-assignment-protocol",
+      why: "Every spawned epic must name a pillar before execution breakdown.",
+      severity: "recommended",
+    },
+  ],
+  file_iteration: [
+    {
+      procedure: "supersession-protocol",
+      why: "§Iterates-on: choose the right tier; a re-attempt is neither supersession nor amends.",
+      severity: "required",
+    },
+    {
+      procedure: "research-capture-protocol",
+      why: 'Promote flow asks "is this a re-attempt?" and populates iterates_on: — confirm iteration lineage is recorded.',
+      severity: "required",
+    },
+    {
+      procedure: "internal-linking-protocol",
+      why: "Iteration structure and tier-based lineage tracking; see entity-model §Iteration lineage for tier semantics.",
+      severity: "recommended",
+    },
+  ],
+  file_milestone: [
+    {
+      procedure: "spec-hierarchy",
+      why: "Defines which level a new spec belongs at and the milestone frontmatter shape.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-summary-authoring",
+      why: "Every milestone needs a plain-language summary: at filing time — pass summary to heyspex_file_spec / POST /api/specs.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique HS-MIL-<suffix> id and prevents duplicates.",
+      severity: "required",
+    },
+  ],
+  file_epic: [
+    {
+      procedure: "spec-hierarchy",
+      why: "Defines epic frontmatter, required parent-milestone link, and child layout.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-summary-authoring",
+      why: "Every epic needs a plain-language summary at plan-ingest filing time — pass summary to heyspex_push_plan / heyspex_file_spec / POST /api/specs. Do not file tasks in the same pass.",
+      severity: "required",
+    },
+    {
+      procedure: "pillar-assignment-protocol",
+      why: "Every epic must name a pillar (hard-blocked at filing). Covers picking an existing HS-PILR theme or authoring a net-new one.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique HS-EPIC-<suffix> id and prevents duplicates.",
+      severity: "required",
+    },
+    {
+      procedure: "plan-ingest-agent-workflow",
+      why: "Linkage + manifest registration steps when ingesting an external plan into the epic.",
+      severity: "recommended",
+    },
+    {
+      procedure: "builder-fleet-capability-reference",
+      why: "Optional builder_profile + ## Builder fleet notes at epic filing — anticipate local builder model class and context tier.",
+      severity: "recommended",
+    },
+  ],
+  file_task: [
+    {
+      procedure: "spec-hierarchy",
+      why: "Defines task frontmatter, required parent-epic link, and child-task fan-out rules.",
+      severity: "required",
+    },
+    {
+      procedure: "builder-fleet-capability-reference",
+      why: "Required ## Builder brief + dispatch frontmatter (suggested_model, recommended_num_ctx, context_files) for fleet-calibrated tasks.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-summary-authoring",
+      why: "Every task needs a plain-language summary at the /hs-next breakdown moment — pass summary to heyspex_file_spec / POST /api/specs. Tasks are never filed during plan ingest.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique HS-TASK-<suffix> id and prevents duplicates.",
+      severity: "required",
+    },
+    {
+      procedure: "checks-manifest-authoring",
+      why: "Every task ships a FROZEN specs/checks/<task-id>.checks.json — each AC classified machine|property|human with named runnable checks, authored at breakdown before any builder sees the brief. A task without one is not ready to dispatch.",
+      severity: "required",
+    },
+    {
+      procedure: "unit-test-authoring-protocol",
+      why: "How the tests behind the manifest checks are written: pure-core/thin-shell, colocation, the five case families, and the mutation gate as the quality oracle.",
+      severity: "recommended",
+    },
+  ],
+  file_diagnose: [
+    {
+      procedure: "spec-hierarchy",
+      why: "Defines diagnose frontmatter, the standalone-default / optional epic-or-milestone parent rule, and severity.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique HS-DIAG-<suffix> id and prevents duplicates.",
+      severity: "required",
+    },
+    {
+      procedure: "resolution-diagnose-workflow",
+      why: "The end-to-end bug→diagnose procedure: intake, §Step 2 symptom-vs-core classification (if fixing exactly this leaves the same class of failure possible, you are still on the symptom), severity ranking, §Step 6 sibling sweep — which now owes a receipt in the body's ## Sweep section — and close-out.",
+      severity: "required",
+    },
+    {
+      procedure: "checks-manifest-authoring",
+      why: 'A bug is the case where a regression check is worth the most and costs the least — the reproduction is already written. Freeze one runnable check per acceptance criterion via `checks:` on heyspex_file_spec, and make at least one of them FAIL when the fix is reverted; "the test passes now" is also what a symptom-level fix produces. REQUIRED WITH AN OUT: a trivial bug may file with no manifest — filing still succeeds and returns a `no_checks_manifest` warning — but skipping is a decision to state, not a step to forget.',
+      severity: "required",
+    },
+  ],
+  file_research: [
+    {
+      procedure: "capture-guardrails",
+      why: "A brand-new idea surfacing in conversation (no existing HS-CAP-*/HS-RES-* id already in play) goes through Capture → Ground=Expand → Promote-to-research first via heyspex_active_capture — never straight to file_research/research dispatch tooling. Skip only when the research target already has an existing capture or research id.",
+      severity: "recommended",
+    },
+    {
+      procedure: "spec-hierarchy",
+      why: "Confirms research is a standalone entity (HS-RES-<id>), how it links back to consumers, and that promotion defaults to a NEW milestone.",
+      severity: "required",
+    },
+    {
+      procedure: "research-capture-protocol",
+      why: "Required template (Executive Summary + Sources) and the back-wikilink + maintenance rules for a research doc.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique HS-RES-<suffix> id and prevents duplicates.",
+      severity: "required",
+    },
+  ],
+  file_memory_lesson: [
+    {
+      procedure: "memory-protocol",
+      why: "How to file a memory-lesson and link it back to the originating spec; the four-axis capture rubric.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique memory slug/id and prevents duplicates.",
+      severity: "required",
+    },
+  ],
+  file_memory_decision: [
+    {
+      procedure: "memory-protocol",
+      why: "How to file a memory-decision and link it back to the originating spec; the four-axis capture rubric.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique memory slug/id and prevents duplicates.",
+      severity: "required",
+    },
+  ],
+  file_memory_reference: [
+    {
+      procedure: "memory-protocol",
+      why: "How to file a memory-reference and link it back to the originating spec; the four-axis capture rubric.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique memory slug/id and prevents duplicates.",
+      severity: "required",
+    },
+  ],
+  file_memory_ui_pattern: [
+    {
+      procedure: "memory-protocol",
+      why: "How to file a memory-ui-pattern and link it back to the originating spec; the four-axis capture rubric.",
+      severity: "required",
+    },
+    {
+      procedure: "vault-id-assignment-protocol",
+      why: "Allocates a unique memory slug/id and prevents duplicates.",
+      severity: "required",
+    },
+  ],
+  file_review: [
+    {
+      procedure: "session-close-protocol",
+      why: "The HS-REV companion doc shape (four required sections) and the close-out flow it belongs to.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-hierarchy",
+      why: 'Confirms the review parents the spec under review (parent: "[[<spec>]]" is required).',
+      severity: "recommended",
+    },
+  ],
+  file_capture: [
+    {
+      procedure: "capture-guardrails",
+      why: "Captures are session-based and NOT research — human words stay verbatim in `## Notes`; AI authors separate layers on an explicit pass. Drive them via heyspex_active_capture, not heyspex_file_spec.",
+      severity: "required",
+    },
+  ],
+  destructive_action: [
+    {
+      procedure: "destructive-action-checklist",
+      why: "Run before any PR that deletes, archives, or routes data-destroying actions.",
+      severity: "required",
+    },
+    {
+      procedure: "dev-server-lifecycle-and-db-safety",
+      why: "If the action is a DB migration / Neon branch reset / .next delete, stop the running dev server first — check ground-truth status via heyspex_dev_server_status.",
+      severity: "recommended",
+    },
+  ],
+  protocol_edit: [
+    {
+      procedure: "spec-hierarchy",
+      why: '§Agent autonomy row "Modify a protocol doc" — protocol edits require explicit user approval.',
+      severity: "required",
+    },
+  ],
+  memory_creation: [
+    {
+      procedure: "memory-protocol",
+      why: "How to file a lesson/decision/reference/ui-pattern memory and link it back to the originating spec.",
+      severity: "required",
+    },
+  ],
+  close_session: [
+    {
+      procedure: "session-close-protocol",
+      why: "Required agent close-out checklist (status flips, review-doc creation, hand-off). " + "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
+      severity: "required",
+    },
+    {
+      procedure: "memory-protocol",
+      why: "Self-check for learnings is step 0 of close-out — capture any non-obvious lesson/decision as a memory spec.",
+      severity: "recommended",
+    },
+  ],
+  context_rollover: [
+    {
+      procedure: "context-rollover-checkpoint",
+      why: "Lightweight mid-flight checkpoint when compaction interrupts implementation — record WIP + handoff, then resume. Do NOT flip status / write HS-REV (that is session close, not rollover).",
+      severity: "required",
+    },
+  ],
+  claim_spec: [
+    {
+      procedure: "spec-hierarchy",
+      why: "A spec is claimable iff it is its own current ClaimTarget — read §Claim eligibility before claiming an Epic/Milestone with open descendants; the console endpoint returns 409 claim_blocked_by_descendants otherwise ([[HS-TASK-0RVD]]).",
+      severity: "required",
+    },
+    {
+      procedure: "pre-execution-alignment-gate",
+      why: "The /hs-next surface routes the claim through this gate; the brief sections (world_state_new / world_state_modified / graph_delta) and the 4-option menu are documented here.",
+      severity: "recommended",
+    },
+  ],
+  execute_spec: [
+    {
+      procedure: "dev-factory-delegation-routing",
+      why: "The COO operating contract: delegation is table-driven. Before delegating build/breakdown/critic work, consult dev-factory/routing-table.json — build → free local fleet, breakdown/critic → DeepSeek V4, cloud/Opus escalation-only. NEVER spawn a Claude subagent on your own (expensive) tier for mechanical, gate-verified build.",
+      severity: "required",
+    },
+    {
+      procedure: "pre-execution-alignment-gate",
+      why: "The first pre-flight before executing an epic/milestone — break down a childless node or revisit a drifted breakdown; hard gate with override-with-reason.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-hierarchy",
+      why: "Confirms the level you are executing and the parent/child linkage the breakdown must respect.",
+      severity: "recommended",
+    },
+    {
+      procedure: "builder-fleet-capability-reference",
+      why: "Context tier ladder + task Builder brief contract when breaking down or dispatching to the local fleet.",
+      severity: "recommended",
+    },
+    {
+      procedure: "unit-test-authoring-protocol",
+      why: "Before writing any test: pure-core/thin-shell structure, colocated <module>.test.ts, the five case families every pure module covers, and the mutation gate as the test-quality oracle.",
+      severity: "recommended",
+    },
+    {
+      procedure: "checks-manifest-authoring",
+      why: "The frozen specs/checks/<task-id>.checks.json is the external completion gate — builders satisfy its named checks and never edit it; hs check run <task-id> is the per-criterion verdict.",
+      severity: "recommended",
+    },
+    {
+      procedure: "dev-server-lifecycle-and-db-safety",
+      why: "Execution often involves DB migrations / dependency installs / .next deletes that break a running dev server — check ground-truth status (heyspex_dev_server_status) and stop the server first.",
+      severity: "recommended",
+    },
+  ],
+  exit_plan_mode: [
+    {
+      procedure: "plan-quality-canonical-check",
+      why: "Run dual overlap+code audit and canonical/supersession check before exit; revise plan to V2.",
+      severity: "required",
+    },
+    {
+      procedure: "plan-ingest-agent-workflow",
+      why: "After the plan is approved, do NOT start coding. First ingest the approved plan into the vault as an epic (file it with children:[]; tasks fan out later via /hs-next) AND claim it via heyspex_claim_spec before executing. ExitPlanMode is the plan→execute seam — without this step agents skip filing+claiming and go straight to code.",
+      severity: "required",
+    },
+    {
+      procedure: "supersession-protocol",
+      why: "If the plan deprecates an existing spec, file the supersession edge per protocol.",
+      severity: "recommended",
+    },
+  ],
+  recommend_location: [
+    {
+      procedure: "rule-placement-protocol",
+      why: "Cost ranking for where a new rule belongs: procedure ≥ memory > spec > CLAUDE.md. CLAUDE.md is the most expensive surface (always-loaded, customer-inherited) — never the default.",
+      severity: "required",
+    },
+    {
+      procedure: "memory-protocol",
+      why: "When the right home is a memory (rank 2 in rule-placement-protocol), this defines the lesson/decision/reference/ui-pattern shape and tagging conventions.",
+      severity: "recommended",
+    },
+    {
+      procedure: "foundations-placement-protocol",
+      why: "When the thing to place is a high-level vision/strategy concept (a principle, a north-star idea, a business claim) rather than an agent-behavior rule: ranks the foundations homes (North Star > Operating Model > Principles > Architecture > Positioning > Research) and gates a foundational edit behind user sign-off.",
+      severity: "recommended",
+    },
+  ],
+  focus_pivot: [
+    {
+      procedure: "focus-intent-routing",
+      why: 'How to detect a roadmap focus-pivot utterance and route it through heyspex_set_focus_areas — covers negation handling ("stop working on X" must NOT add X), the closed-tag-vocabulary constraint (heyspex_list_known_tags first), and the confirmation beat before applying.',
+      severity: "required",
+    },
+  ],
+  server_impacting_action: [
+    {
+      procedure: "dev-server-lifecycle-and-db-safety",
+      why: "Before a DB migration, Neon branch reset, dependency install, .next delete, or starting a second dev server: check ground-truth status (heyspex_dev_server_status / `hs server status`) and stop a live server first — running a migration under a live server strands its in-memory schema and forces a restart.",
+      severity: "required",
+    },
+  ],
+  restructure_content: [
+    {
+      procedure: "internal-linking-protocol",
+      why: "Before re-parenting an epic, editing a milestone epics[] roster, or moving trackable work to a new canonical home — leave a summary + wikilink stub at the old home so wikilinks and lexical retrieval signal are preserved.",
+      severity: "required",
+    },
+    {
+      procedure: "section-supersede-protocol",
+      why: "Before editing or deleting a section that has gone stale: the three-way test for edit-in-place vs supersede-the-section vs retire-the-whole-document, the stub properties a reviewer checks, and the rule that the repair stays a proposal a person approves — a linked heading is never silently rewritten.",
+      severity: "required",
+    },
+    {
+      procedure: "spec-hierarchy",
+      why: "Confirms bidirectional linkage shape (epics: ⇄ milestone:, children: ⇄ parent:) that re-parent edits must maintain.",
+      severity: "recommended",
+    },
+    {
+      procedure: "supersession-protocol",
+      why: "If the move replaces dead guidance (not merely relocates live work), use supersession instead of a cross-reference stub.",
+      severity: "recommended",
+    },
+    {
+      procedure: "doc-canonicalization-protocol",
+      why: "If the restructure is an evergreen-doc split/merge rather than plan-side re-parent, use doc-canonicalization instead.",
+      severity: "recommended",
+    },
+  ],
+};
+
+const VALID_INTENTS = Object.keys(PREFLIGHT_INTENT_MAP);
+
+// Maps a file_* intent to the canonical filing tool the agent should call.
+// This is the core of [[HS-EPIC-WDP3]]: surface the deterministic tool inline
+// in the preflight response so an agent that reaches the procedure layer is
+// routed at the right answer — instead of pattern-matching a sibling spec's
+// frontmatter. Every non-capture kind files via heyspex_file_spec (the server
+// generates frontmatter from the canonical template); captures are
+// session-based and route at heyspex_active_capture. Intents not listed here
+// (destructive_action, protocol_edit, close_session, claim_spec, execute_spec,
+// recommend_location) govern actions, not spec creation — close_session carries
+// close_tool; others carry no filing_tool block.
+const CLOSE_TOOL_MAP = {
+  close_session: {
+    tool: "heyspex_submit_for_review",
+    minimal_call: { spec_id: "<completed-review-unit-or-task-id>" },
+    note: "Status SSOT is PATCH /api/specs/:id/status — not frontmatter edits. This tool applies review-grain coercion, parent rollup, and releases the claim. Still run session-close-protocol steps 2–7 (change-log, HS-REV or review seed, WIP, export).",
+  },
+};
+
+// Build the close_tool block for action intents that flip status at session end.
+function buildCloseTool(intent) {
+  return CLOSE_TOOL_MAP[intent] ?? null;
+}
+
+const FILE_SPEC_NOTE =
+  "Use this. The server generates frontmatter from the canonical template. Do not compose frontmatter from a sibling spec.";
+const FILING_TOOL_MAP = {
+  file_milestone: { type: "milestone" },
+  file_epic: {
+    type: "epic",
+    parentKey: "milestone",
+    parentExample: "[[HS-MIL-...]]",
+  },
+  file_task: {
+    type: "task",
+    parentKey: "parent",
+    parentExample: "[[HS-EPIC-...]]",
+  },
+  file_diagnose: {
+    type: "diagnose",
+    note: `${FILE_SPEC_NOTE} By default a diagnose is filed standalone — it has no parent and does not nest under any epic or milestone, so it lives on its own in the Resolution lane rather than inside a planned work item. Keep it standalone for a cross-cutting bug, or one that isn't part of any single epic's or milestone's scope (the common case). Only set parent: "[[HS-EPIC-...]]" or "[[HS-MIL-...]]" when the bug clearly belongs to that epic's or milestone's work and you want it tracked under it.`,
+  },
+  file_research: { type: "research" },
+  file_memory_lesson: { type: "memory-lesson" },
+  file_memory_decision: { type: "memory-decision" },
+  file_memory_reference: { type: "memory-reference" },
+  file_memory_ui_pattern: { type: "memory-ui-pattern" },
+  file_review: {
+    type: "review",
+    parentKey: "parent",
+    parentExample: "[[<spec-under-review>]]",
+    note: `${FILE_SPEC_NOTE} A review's parent is the spec it reviews — parent is required.`,
+  },
+  file_capture: {
+    tool: "heyspex_active_capture",
+    minimal_call: { spec_id: "<HS-CAP-...>" },
+    note: "Captures are session-based; use heyspex_active_capture, NOT heyspex_file_spec.",
+  },
+};
+
+// Build the filing_tool block for a given intent, or null when the intent does
+// not create a spec.
+function buildFilingTool(intent) {
+  const spec = FILING_TOOL_MAP[intent];
+  if (!spec) return null;
+  // Captures (and any future bespoke tool) carry an explicit shape.
+  if (spec.tool) {
+    return {
+      tool: spec.tool,
+      minimal_call: spec.minimal_call,
+      note: spec.note,
+    };
+  }
+  const minimal_call = { type: spec.type };
+  if (spec.parentKey) minimal_call[spec.parentKey] = spec.parentExample;
+  minimal_call.name = "<title>";
+  return {
+    tool: "heyspex_file_spec",
+    minimal_call,
+    note: spec.note ?? FILE_SPEC_NOTE,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Thread-type-aware session close-out ([[HS-RES-32MJ]]). Close-out is NOT
+// one-size-fits-all: the thread type decides whether there is a close at all and
+// which steps run; the grain ladder (session-close-protocol) decides which spec
+// is the review unit on the execution paths. Thread-type is DECLARED, not
+// inferred — two of the five candidate signals (specs-filed-by-type,
+// research-saved) are not session-scoped on either tier, so a positive
+// declaration is the robust path. Mirrors the prose decision table in
+// session-close-protocol §"Thread-type close-out".
+// ─────────────────────────────────────────────────────────────────────────────
+const CLOSE_SESSION_THREAD_PATHS = {
+  capture_only: {
+    label: "Capture-only — brain-offload via /hs-capture; no claim, no code",
+    is_close: false,
+    close_tool: false,
+    procedures: ["research-capture-protocol"],
+    steps: [
+      "No session close-out is owed — a capture is not a review unit.",
+      "Exit = promote to research (heyspex_promote_capture) or leave the capture pinned.",
+      "Do NOT submit_for_review, mint an HS-REV, record a WIP ledger, or flush an audit export.",
+    ],
+  },
+  research_only: {
+    label: "Research-only — saved an HS-RES; no claimed spec",
+    is_close: false,
+    close_tool: false,
+    procedures: ["research-capture-protocol"],
+    steps: [
+      "Save findings via heyspex_save_research / heyspex_complete_research (external scope needs >=1 cited URL).",
+      "Research is evergreen: do NOT submit_for_review or flip status, and do NOT mint an HS-REV.",
+      "No execution WIP ledger is owed. Audit export (heyspex_export_events) is optional.",
+    ],
+  },
+  plan_ingest_only: {
+    label: "Plan/ingest-only — filed milestone+epics; no task execution",
+    is_close: false,
+    close_tool: false,
+    procedures: ["plan-ingest-agent-workflow", "spec-hierarchy"],
+    steps: [
+      "Confirm every new spec is registered + linked: heyspex_validate_linkage (heyspex_register_spec for any orphan).",
+      "Confirm each milestone/epic carries an authored summary and a re-derived ## Intended outcome.",
+      "No task close, no HS-REV, no execution WIP ledger — epics are filed with children: [].",
+    ],
+  },
+  one_task: {
+    label: "One-task execution — claimed and completed a single task",
+    is_close: true,
+    close_tool: true,
+    procedures: ["session-close-protocol", "memory-protocol"],
+    steps: [
+      "heyspex_submit_for_review({ spec_id }) on the completed unit (status API SSOT — never hand-edit status:). Grain-coercion, parent rollup, and claim release happen server-side.",
+      "Append a change-log roll-up / review seed to the task.",
+      "Create an HS-REV companion + parent ## Review back-link ONLY if the active review grain is task; otherwise the change-log seed is enough.",
+      "heyspex_record_wip for the worked epic (skip only if the epic closed this session).",
+      "heyspex_export_events to flush the audit log. Do NOT git commit / push.",
+      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
+    ],
+  },
+  multi_task_epic: {
+    label: "Multi-task / epic push — completed several tasks under an epic",
+    is_close: true,
+    close_tool: true,
+    procedures: ["session-close-protocol", "memory-protocol"],
+    steps: [
+      "heyspex_submit_for_review on each completed unit; parent rollup is automatic when the last child lands.",
+      "One consolidated change-log + the HS-REV companion at the ACTIVE review grain (epic in steady-state, milestone in MVP).",
+      "heyspex_record_wip once for the worked epic; heyspex_export_events; do NOT git commit / push.",
+      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
+    ],
+  },
+  resolve_diagnose: {
+    label: "Resolve / diagnose — worked an HS-DIAG or a Resolution item",
+    is_close: true,
+    close_tool: true,
+    procedures: ["session-close-protocol", "resolution-diagnose-workflow"],
+    steps: [
+      "If the flag was a stale-cache false positive (the file on disk contradicts it): re-stamp via heyspex_record_alignment — do NOT re-file work that already exists.",
+      "If a real diagnose/fix completed: heyspex_submit_for_review on it + change-log; HS-REV per active grain.",
+      "heyspex_record_wip if anything remains open; heyspex_export_events.",
+      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
+    ],
+  },
+  mid_rollover: {
+    label: "Mid-implementation rollover — claimed but not finished",
+    is_close: false,
+    close_tool: false,
+    procedures: ["context-rollover-checkpoint"],
+    steps: [
+      "This is NOT a session close. Do NOT flip status, mint an HS-REV, or submit_for_review.",
+      "Record a lightweight WIP checkpoint (heyspex_record_wip) so the next session resumes; leave the spec in_progress.",
+      "Hand-off: if the human asks for a hand-off, or work remains for a next session, run the /hs-handoff create flow — `hs handoff record --new-code --spec <next> --phase … --link … --blocker …` (minted code) and hand back `/hs-handoff <CODE>` plus `claude \"/hs-next <id>\"`; never a freehand prompt.",
+      'See heyspex_preflight({ intent: "context_rollover" }) / the context-rollover-checkpoint procedure for the full checkpoint shape.',
+    ],
+  },
+};
+
+const CLOSE_SESSION_THREAD_TYPES = Object.keys(CLOSE_SESSION_THREAD_PATHS);
+
+const CLOSE_SESSION_MIXED_RULE =
+  "If the session spanned MORE THAN ONE thread type (e.g. filed a plan AND finished a task), request each applicable type and run the UNION of their steps — ordered, idempotent (re-running submit_for_review / export_events is safe), and surface the ambiguity. Never drop an owed obligation; never duplicate one.";
+
+function buildCloseSessionPreflight(vaultRoot, threadType, injectedCatalog) {
+  const path = CLOSE_SESSION_THREAD_PATHS[threadType];
+  if (!path) {
+    return {
+      error: "UNKNOWN_THREAD_TYPE",
+      message: `Unknown thread_type "${threadType}" for close_session. Valid thread types: ${CLOSE_SESSION_THREAD_TYPES.join(", ")}.`,
+    };
+  }
+  const catalog =
+    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
+  if (!catalog) {
+    return {
+      error: "CATALOG_NOT_FOUND",
+      message:
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
+    };
+  }
+  const procedures = path.procedures.map((name) =>
+    resolveRow(catalog, { procedure: name, severity: "required" }),
+  );
+  const close_tool = path.close_tool ? buildCloseTool("close_session") : null;
+  return {
+    intent: "close_session",
+    thread_type: threadType,
+    thread_label: path.label,
+    is_close: path.is_close,
+    steps: path.steps,
+    procedures,
+    mixed_thread_rule: CLOSE_SESSION_MIXED_RULE,
+    ...(close_tool ? { close_tool } : {}),
+  };
+}
+
+/**
+ * `injectedCatalog` — see {@link executeListProcedures}; same contract here
+ * (threaded through to `buildCloseSessionPreflight` for the close_session
+ * thread-type path too, so a single HTTP fetch covers both branches).
+ */
+// [[HS-J3NY-C86Z-TASK-replace-hard-coded-owner-defaults-on]]: the execute_spec delegation row used
+// to tell EVERY agent "build -> free local fleet, breakdown/critic -> DeepSeek V4" from the owner's
+// dev-factory/routing-table.json, a file a customer install does not have. That wording is now the
+// owner's only: it shows when the HS-9JMD dev-factory overlay gate is open (heyspex-app source
+// checkout + owner account + HEYSPEX_DEV_FACTORY not 0). Everyone else is told the harness defaults.
+export const CUSTOMER_DELEGATION_WHY =
+  "Delegation follows your SpexFleet seats, which default to the models your harness provides: under Claude Code every seat runs a Claude model by its tier (judgement/planning -> opus, build/execution -> sonnet, mechanical -> haiku, in-session sub-agents inherit your session), under GitHub Copilot every seat runs auto. `hs seat list` shows each seat's model and any override you set with `hs seat set <seat> <model>`. Hand mechanical, gate-verified build work to the build seat instead of doing it on your own top-tier session.";
+
+/** True when the owner's dev-factory overlay may load for this package checkout. Never throws. */
+export function ownerRoutingOverlayOpen(root = DEFAULT_PLATFORM_ROOT) {
+  try {
+    return isDevFactoryOverlayOpen(root);
+  } catch {
+    return false;
+  }
+}
+
+/** Swap owner-only routing text for the harness-default text when the overlay is closed. Pure. */
+export function harnessConditionalRow(row, { overlayOpen = false } = {}) {
+  if (row?.procedure !== "dev-factory-delegation-routing" || overlayOpen) return row;
+  return { ...row, why: CUSTOMER_DELEGATION_WHY };
+}
+
+export function executeRunPreflight(vaultRoot, args = {}, injectedCatalog) {
+  const intent = String(args.intent ?? "").trim();
+  if (!intent) {
+    return {
+      error: "MISSING_INTENT",
+      message: `intent is required. Valid intents: ${VALID_INTENTS.join(", ")}.`,
+    };
+  }
+  // Thread-type-aware close-out: when a thread_type is declared, return that
+  // type's CONDITIONAL close path instead of the static checklist ([[HS-RES-32MJ]]).
+  const threadType = String(args.thread_type ?? "").trim();
+  if (intent === "close_session" && threadType) {
+    return buildCloseSessionPreflight(vaultRoot, threadType, injectedCatalog);
+  }
+  const recommendations = PREFLIGHT_INTENT_MAP[intent];
+  if (!recommendations) {
+    return {
+      error: "UNKNOWN_INTENT",
+      message: `Unknown intent "${intent}". Valid intents: ${VALID_INTENTS.join(", ")}.`,
+    };
+  }
+  const catalog =
+    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
+  if (!catalog) {
+    return {
+      error: "CATALOG_NOT_FOUND",
+      message:
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
+    };
+  }
+
+  const overlayOpen =
+    typeof args.overlay_open === "boolean" ? args.overlay_open : ownerRoutingOverlayOpen();
+  const procedures = recommendations
+    .map((row) => harnessConditionalRow(row, { overlayOpen }))
+    .map((row) => resolveRow(catalog, row));
+
+  const filing_tool = buildFilingTool(intent);
+  const close_tool = buildCloseTool(intent);
+
+  const result = {
+    intent,
+    procedures,
+    ...(filing_tool ? { filing_tool } : {}),
+    ...(close_tool ? { close_tool } : {}),
+  };
+
+  // Family-overlap advisory for filing intents: warn agents to check whether
+  // a closed family already covered this goal with no iterates_on edge.
+  const FILING_ADVISORY =
+    "Family-overlap check (warn-only): before filing, check whether a CLOSED family already shipped against this goal with no iterates_on: edge — compare both TITLE and JTBD (job-to-be-done) statement, not title alone, since two differently-titled specs can still be the same job (owner-approved 2026-08-23 job-based-duplicate-detection extension) — if so this may be round 2; see entity-model §Iteration lineage. Never blocks filing.";
+  const FILING_INTENTS_WITH_ADVISORY = [
+    "file_epic",
+    "file_task",
+    "promote_research",
+  ];
+  if (FILING_INTENTS_WITH_ADVISORY.includes(intent)) {
+    result.advisory = FILING_ADVISORY;
+  }
+
+  // Static close_session call (no thread_type declared): nudge toward the
+  // conditional path so the agent runs the right minimal-complete close-out.
+  if (intent === "close_session") {
+    result.thread_type_hint = {
+      note: 'Close-out is thread-type-aware. Re-call heyspex_preflight({ intent: "close_session", thread_type: "<type>" }) to get the conditional close path for what this session actually did.',
+      thread_types: CLOSE_SESSION_THREAD_TYPES.map((t) => ({
+        thread_type: t,
+        label: CLOSE_SESSION_THREAD_PATHS[t].label,
+        is_close: CLOSE_SESSION_THREAD_PATHS[t].is_close,
+      })),
+      mixed: CLOSE_SESSION_MIXED_RULE,
+    };
+  }
+
+  // [[HS-EN4F]]: research intents carry the absolute hs-res route.
+  if (RESEARCH_TOOLING_INTENTS.includes(intent)) {
+    const research_tooling = buildResearchTooling();
+    if (research_tooling) result.research_tooling = research_tooling;
+  }
+
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// [[HS-EN4F]] — the hs-res route, in absolute paths. The /hs-res command and
+// its SKILL.md spell the gather/synthesis CLIs repo-relative
+// (`node dev-factory/spexcrawl/...`), which only resolves inside the platform
+// checkout. An agent in a customer repo (sales-coach, 2026-10-02) looked for
+// hs-res there, did not find it, concluded "the tooling isn't installed" and
+// fanned out Sonnet subagents on WebSearch. The research preflight is the one
+// call every research path must make (the HS-K0ZP gate refuses WebSearch /
+// WebFetch until it runs), so it carries the route: absolute commands derived
+// from where THIS module sits — the MCP server serving the customer repo runs
+// out of the platform checkout, so these paths resolve from any working
+// directory. Null when the platform does not ship the CLIs (published package).
+// ─────────────────────────────────────────────────────────────────────────────
+const RESEARCH_TOOLING_INTENTS = [
+  "research",
+  "file_research",
+  "promote_research",
+];
+const DEFAULT_PLATFORM_ROOT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+export function buildResearchTooling(
+  platformRoot = DEFAULT_PLATFORM_ROOT,
+  exists = existsSync,
+) {
+  const abs = (...parts) => join(platformRoot, ...parts).replace(/\\/g, "/");
+  const spexcrawl = abs("dev-factory", "spexcrawl", "spexcrawl-cli.mjs");
+  const firecrawl = abs("dev-factory", "spexcrawl", "firecrawl-cli.mjs");
+  const synthesize = abs("dev-factory", "spexcrawl", "synthesize-cli.mjs");
+  const skill = abs(".commandcode", "skills", "hs-res", "SKILL.md");
+  if (![spexcrawl, firecrawl, synthesize].every((p) => exists(p))) return null;
+  return {
+    method:
+      "hs-res (the confidence ladder) — URL DISCOVERY defaults to self-hosted Firecrawl search; FULL-PAGE fetch of each cited URL defaults to SpexCrawl scrape (Firecrawl scrape is a per-URL retry only); DeepSeek synthesizes. Zero Claude/Anthropic sub-agents. Owner ruling 2026-10-10: SpexCrawl search is blocked on all four engines, so it is no longer the default discovery step. Hosted api.firecrawl.dev stays ask-before-spend and is never a default.",
+    note: "These commands run from ANY repo. A project with no /hs-res command or skill of its own does NOT mean the tooling is missing — use these absolute paths. Firecrawl search returns titles/URLs/snippets only: snippets are discovery, never evidence — scrape the full page of every URL you cite. Native WebSearch/WebFetch is the last resort only when both backends report unavailable; never fan out Sonnet sub-agents for research.",
+    skill_path: exists(skill) ? skill : null,
+    // Owner ruling 2026-10-10 (HS-5PG6): discovery = Firecrawl search, fetch = SpexCrawl scrape.
+    discover_primary: `node "${firecrawl}" search "<query>" --json`,
+    fetch_primary: `node "${spexcrawl}" scrape "<url>" --json`,
+    fetch_retry: `node "${firecrawl}" scrape "<url>" --json`,
+    optional_combined: `node "${spexcrawl}" search "<query>" --json`,
+    // Legacy field names kept for existing consumers. They now mirror the new
+    // order: gather_* = discovery, scrape_* = fetch. `gather_primary` is NO
+    // LONGER SpexCrawl search (that moved to optional_combined).
+    gather_primary: `node "${firecrawl}" search "<query>" --json`,
+    gather_fallback: `node "${spexcrawl}" search "<query>" --json`,
+    scrape_primary: `node "${spexcrawl}" scrape "<url>" --json`,
+    scrape_fallback: `node "${firecrawl}" scrape "<url>" --json`,
+    synthesize: `node "${synthesize}" --prompt-file <path> --json`,
+    grounding_first:
+      "Before any gather: method triage (known-target-retrieval vs the ladder), ground-first (heyspex_recall_memories), and check for a working reference the owner already runs (e.g. `docker ps` for a local Firecrawl on :3002). Record the four-part grounding result (already built / already decided / owner reference / residual delta).",
+  };
+}
+
+export const PREFLIGHT_INTENTS = VALID_INTENTS;
+export { CLOSE_SESSION_THREAD_TYPES };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Read-path selector wiring ([[HS-DJWP-MCPC-TASK-wire-the-mcp-server-s-vault-reads]]
+// of [[HS-T6GS-MCPC-EPIC-mcp-server-reads-the-vault-through-the]]).
+//
+// The three functions below are the cloud-reliant siblings of
+// `executeListProcedures` / `executeGetProcedure` / `executeRunPreflight`.
+// They never call `loadCatalog(vaultRoot)` in the `neon` tier — the catalog
+// (or, for `executeGetProcedureViaTier`, the full procedure body) is fetched
+// once over HTTP via the caller-supplied `consoleFetch` and handed to the
+// existing pure functions as an `injectedCatalog`, so the filtering /
+// preflight-mapping logic itself is never duplicated. In `disk` tier each
+// wrapper calls the untouched, byte-for-byte-unchanged pure function — same
+// disk-only code path as before this task.
+//
+// `consoleFetch` is passed in (not imported) because this module is
+// deliberately transport-free "pure-logic" (see file header) — cli.mjs owns
+// the bound `makeConsoleFetch` client and threads it through here, mirroring
+// how `readViaSelector` itself never imports console-fetch.mjs.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Row shape from `GET /api/procedures` — mirrors `summarize()` above (see that route's docstring: "do not invent a new shape here"). */
+function catalogFromProceduresRoute(body) {
+  const rows = Array.isArray(body?.procedures) ? body.procedures : [];
+  return { procedures: rows };
+}
+
+/**
+ * Fetch the procedure catalog via `GET /api/procedures` (disk: `loadCatalog`).
+ * Exported for callers that need the raw catalog object outside the three
+ * higher-level wrappers below (none today; kept for symmetry / testability).
+ */
+export async function loadCatalogViaTier({
+  vaultRoot,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
+  return readViaSelector({
+    tier,
+    diskRead: () => loadCatalog(vaultRoot),
+    neonRead: async () => {
+      const res = await consoleFetch("/api/procedures");
+      if (!res.ok) {
+        throw consoleReadErrorFrom(res, `GET /api/procedures returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+      }
+      return catalogFromProceduresRoute(res.body);
+    },
+    routeLabel: "GET /api/procedures",
+    consoleUrl,
+  });
+}
+
+/** Cloud-reliant sibling of {@link executeListProcedures}. */
+export async function executeListProceduresViaTier(opts) {
+  const { value, degraded } = await withDegradationScope(() => executeListProceduresViaTierInner(opts));
+  return mergeDegradation(value, degraded);
+}
+
+async function executeListProceduresViaTierInner({
+  vaultRoot,
+  args,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
+  return readViaSelector({
+    tier,
+    diskRead: () => executeListProcedures(vaultRoot, args),
+    neonRead: async () => {
+      const catalog = await loadCatalogViaTier({
+        vaultRoot,
+        tier: "neon",
+        consoleFetch,
+        consoleUrl,
+      });
+      if (!catalog) {
+        return {
+          error: "CATALOG_NOT_FOUND",
+          message:
+            "GET /api/procedures returned no catalog (console reports it missing).",
+        };
+      }
+      // Filtering happens HERE, client-side — the route has no tag/trigger/query
+      // params (it always answers the full unfiltered set), unlike the disk path
+      // which filters inside executeListProcedures itself. Passing the fetched
+      // catalog as `injectedCatalog` runs the SAME filter logic either way.
+      return executeListProcedures(vaultRoot, args, catalog);
+    },
+    routeLabel: "GET /api/procedures",
+    consoleUrl,
+  });
+}
+
+/** Cloud-reliant sibling of {@link executeGetProcedure}. Single round trip: `GET /api/procedures/<name>` returns catalog entry + full body together. */
+export async function executeGetProcedureViaTier({
+  vaultRoot,
+  args,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
+  return readViaSelector({
+    tier,
+    diskRead: () => executeGetProcedure(vaultRoot, args),
+    neonRead: async () => {
+      const name = String(args?.name ?? "").trim();
+      if (!name) {
+        return {
+          error: "MISSING_NAME",
+          message: 'name is required (e.g. "spec-hierarchy")',
+        };
+      }
+      const res = await consoleFetch(
+        `/api/procedures/${encodeURIComponent(name)}`,
+      );
+      if (res.ok) {
+        return {
+          procedure: res.body?.procedure,
+          content: res.body?.content,
+          source: res.body?.source ?? null,
+        };
+      }
+      // Aligned with the sibling *ViaTier functions ([[HS-DJWP-MCPC-TASK]]
+      // round 3 fix — a 500 {error:'boom'} was previously swallowed as a real
+      // answer regardless of status code): ONLY a 404 PROCEDURE_NOT_FOUND is a
+      // real "no such procedure" answer, matching the route's own contract
+      // (its docstring: "an unknown name is a 404 error code, never an empty
+      // 200 success"). Everything else — a 500 CATALOG_NOT_FOUND included, a
+      // reachable console reporting a server-side config break — throws so the
+      // selector surfaces CONSOLE_UNREACHABLE_CLOUD_MODE rather than silently
+      // degrading; the epic's no-silent-degrade rule treats "console answered,
+      // but the answer means something is broken" the same as unreachable.
+      if (res.status === 404 && res.body?.error === "PROCEDURE_NOT_FOUND") {
+        return { error: res.body.error, message: res.body.message };
+      }
+      throw consoleReadErrorFrom(
+        res,
+        `GET /api/procedures/${name} returned ${res.status}: ${res.body?.error ? `${res.body.error}${res.body.message ? ` — ${res.body.message}` : ""}` : res.error || JSON.stringify(res.body ?? {})}`,
+        null,
+      );
+    },
+    routeLabel: "GET /api/procedures/[name]",
+    consoleUrl,
+  });
+}
+
+/** Cloud-reliant sibling of {@link executeRunPreflight}. One catalog fetch covers both the static intent map AND the close_session thread-type path. */
+export async function executeRunPreflightViaTier(opts) {
+  const { value, degraded } = await withDegradationScope(() => executeRunPreflightViaTierInner(opts));
+  return mergeDegradation(value, degraded);
+}
+
+async function executeRunPreflightViaTierInner({
+  vaultRoot,
+  args,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
+  return readViaSelector({
+    tier,
+    diskRead: () => executeRunPreflight(vaultRoot, args),
+    neonRead: async () => {
+      const catalog = await loadCatalogViaTier({
+        vaultRoot,
+        tier: "neon",
+        consoleFetch,
+        consoleUrl,
+      });
+      if (!catalog) {
+        return {
+          error: "CATALOG_NOT_FOUND",
+          message:
+            "GET /api/procedures returned no catalog (console reports it missing).",
+        };
+      }
+      return executeRunPreflight(vaultRoot, args, catalog);
+    },
+    routeLabel: "GET /api/procedures",
+    consoleUrl,
+  });
+}