heyspex 0.1.0 → 0.2.0

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

@@ -12,23 +12,25 @@
  * heyspex_design_* family is the canonical template this module mirrors).
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
-import { readViaSelector } from './read-path.mjs';
+import { readViaSelector } from "./read-path.mjs";
+import { pageListToolResult } from "./list-tools.mjs";
 
-const CATALOG_FILE = ['specs', 'protocols', '.catalog.json'];
-const PROTOCOLS_DIR = ['specs', 'protocols'];
+const CATALOG_FILE = ["specs", "protocols", ".catalog.json"];
+const PROTOCOLS_DIR = ["specs", "protocols"];
 
 function normalize(value) {
-  return String(value ?? '').toLowerCase();
+  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'));
+    return JSON.parse(readFileSync(path, "utf8"));
   } catch {
     return null;
   }
@@ -41,7 +43,7 @@ function summarize(entry) {
     title: entry.title,
     tags: Array.isArray(entry.tags) ? entry.tags : [],
     triggers: Array.isArray(entry.triggers) ? entry.triggers : [],
-    summary: entry.summary ?? '',
+    summary: entry.summary ?? "",
     path: entry.path,
   };
 }
@@ -54,15 +56,18 @@ function summarize(entry) {
  * preserves today's disk-only behavior byte-for-byte.
  */
 export function executeListProcedures(vaultRoot, args = {}, injectedCatalog) {
-  const catalog = injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
+  const catalog =
+    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
   if (!catalog) {
     return {
-      error: 'CATALOG_NOT_FOUND',
+      error: "CATALOG_NOT_FOUND",
       message:
-        'specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.',
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
     };
   }
-  const procedures = Array.isArray(catalog.procedures) ? catalog.procedures : [];
+  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;
@@ -80,59 +85,68 @@ export function executeListProcedures(vaultRoot, args = {}, injectedCatalog) {
     if (queryFilter) {
       const haystack = [entry.name, entry.title, entry.summary]
         .map(normalize)
-        .join(' ');
+        .join(" ");
       if (!haystack.includes(queryFilter)) continue;
     }
     matches.push(summarize(entry));
   }
 
-  matches.sort((a, b) => a.name.localeCompare(b.name));
-
-  return {
-    procedures: matches,
-    count: matches.length,
-    total: procedures.length,
-    filters_applied: {
-      tag: args.tag ?? null,
-      trigger: args.trigger ?? null,
-      query: args.query ?? null,
+  // 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 : [];
+  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();
+  const name = String(args.name ?? "").trim();
   if (!name) {
-    return { error: 'MISSING_NAME', message: 'name is required (e.g. "spec-hierarchy")' };
+    return {
+      error: "MISSING_NAME",
+      message: 'name is required (e.g. "spec-hierarchy")',
+    };
   }
   const catalog = loadCatalog(vaultRoot);
   if (!catalog) {
     return {
-      error: 'CATALOG_NOT_FOUND',
+      error: "CATALOG_NOT_FOUND",
       message:
-        'specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.',
+        "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',
+      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',
+      error: "BODY_FILE_MISSING",
       message: `Catalog entry exists but ${entry.path} not found on disk. Regenerate the catalog.`,
     };
   }
-  const content = readFileSync(bodyPath, 'utf8');
+  const content = readFileSync(bodyPath, "utf8");
   return {
     procedure: {
       name: entry.name,
@@ -140,7 +154,7 @@ export function executeGetProcedure(vaultRoot, args = {}) {
       title: entry.title,
       tags: Array.isArray(entry.tags) ? entry.tags : [],
       triggers: Array.isArray(entry.triggers) ? entry.triggers : [],
-      summary: entry.summary ?? '',
+      summary: entry.summary ?? "",
       path: entry.path,
       status: entry.status ?? null,
       created: entry.created ?? null,
@@ -152,395 +166,471 @@ export function executeGetProcedure(vaultRoot, args = {}) {
   };
 }
 
+/**
+ * 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: "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: "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',
+      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: "supersession-protocol",
+      why: "§Iterates-on: choose the right tier; a re-attempt is neither supersession nor amends.",
+      severity: "required",
     },
     {
-      procedure: 'research-capture-protocol',
+      procedure: "research-capture-protocol",
       why: 'Promote flow asks "is this a re-attempt?" and populates iterates_on: — confirm iteration lineage is recorded.',
-      severity: 'required',
+      severity: "required",
     },
     {
-      procedure: 'internal-linking-protocol',
-      why: 'Iteration structure and tier-based lineage tracking; see entity-model §Iteration lineage for tier semantics.',
-      severity: 'recommended',
+      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-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: "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',
+      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-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: "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: "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: "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: "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',
+      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: "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: "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: "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: "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: "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',
+      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: "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: "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: "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',
+      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',
+      severity: "required",
     },
   ],
   file_research: [
     {
-      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: "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: "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',
+      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: "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',
+      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: "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',
+      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: "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',
+      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: "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',
+      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: "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',
+      procedure: "spec-hierarchy",
       why: 'Confirms the review parents the spec under review (parent: "[[<spec>]]" is required).',
-      severity: 'recommended',
+      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',
+      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: "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',
+      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',
+      procedure: "spec-hierarchy",
       why: '§Agent autonomy row "Modify a protocol doc" — protocol edits require explicit user approval.',
-      severity: 'required',
+      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',
+      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).',
-      severity: 'required',
+      procedure: "session-close-protocol",
+      why: "Required agent close-out checklist (status flips, review-doc creation, hand-off).",
+      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',
+      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',
+      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: "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',
+      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: "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: "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: "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: "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: "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: "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',
+      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-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: "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',
+      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: "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: "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',
+      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',
+      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',
+      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',
+      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: "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: 'spec-hierarchy',
-      why: 'Confirms bidirectional linkage shape (epics: ⇄ milestone:, children: ⇄ parent:) that re-parent edits must maintain.',
-      severity: 'recommended',
+      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: '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: "spec-hierarchy",
+      why: "Confirms bidirectional linkage shape (epics: ⇄ milestone:, children: ⇄ parent:) that re-parent edits must maintain.",
+      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',
+      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",
     },
   ],
 };
@@ -559,10 +649,9 @@ const VALID_INTENTS = Object.keys(PREFLIGHT_INTENT_MAP);
 // 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).',
+    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).",
   },
 };
 
@@ -572,30 +661,38 @@ function buildCloseTool(intent) {
 }
 
 const FILE_SPEC_NOTE =
-  'Use this. The server generates frontmatter from the canonical template. Do not compose frontmatter from a sibling spec.';
+  "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_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',
+    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_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>]]',
+    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.',
+    tool: "heyspex_active_capture",
+    minimal_call: { spec_id: "<HS-CAP-...>" },
+    note: "Captures are session-based; use heyspex_active_capture, NOT heyspex_file_spec.",
   },
 };
 
@@ -606,13 +703,17 @@ function buildFilingTool(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 };
+    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>';
+  minimal_call.name = "<title>";
   return {
-    tool: 'heyspex_file_spec',
+    tool: "heyspex_file_spec",
     minimal_call,
     note: spec.note ?? FILE_SPEC_NOTE,
   };
@@ -630,81 +731,81 @@ function buildFilingTool(intent) {
 // ─────────────────────────────────────────────────────────────────────────────
 const CLOSE_SESSION_THREAD_PATHS = {
   capture_only: {
-    label: 'Capture-only — brain-offload via /hs-capture; no claim, no code',
+    label: "Capture-only — brain-offload via /hs-capture; no claim, no code",
     is_close: false,
     close_tool: false,
-    procedures: ['research-capture-protocol'],
+    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.',
+      "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',
+    label: "Research-only — saved an HS-RES; no claimed spec",
     is_close: false,
     close_tool: false,
-    procedures: ['research-capture-protocol'],
+    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.',
+      "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',
+    label: "Plan/ingest-only — filed milestone+epics; no task execution",
     is_close: false,
     close_tool: false,
-    procedures: ['plan-ingest-agent-workflow', 'spec-hierarchy'],
+    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: [].',
+      "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',
+    label: "One-task execution — claimed and completed a single task",
     is_close: true,
     close_tool: true,
-    procedures: ['session-close-protocol', 'memory-protocol'],
+    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.',
+      "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.",
     ],
   },
   multi_task_epic: {
-    label: 'Multi-task / epic push — completed several tasks under an epic',
+    label: "Multi-task / epic push — completed several tasks under an epic",
     is_close: true,
     close_tool: true,
-    procedures: ['session-close-protocol', 'memory-protocol'],
+    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.',
+      "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.",
     ],
   },
   resolve_diagnose: {
-    label: 'Resolve / diagnose — worked an HS-DIAG or a Resolution item',
+    label: "Resolve / diagnose — worked an HS-DIAG or a Resolution item",
     is_close: true,
     close_tool: true,
-    procedures: ['session-close-protocol', 'resolution-diagnose-workflow'],
+    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.',
+      "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.",
     ],
   },
   mid_rollover: {
-    label: 'Mid-implementation rollover — claimed but not finished',
+    label: "Mid-implementation rollover — claimed but not finished",
     is_close: false,
     close_tool: false,
-    procedures: ['context-rollover-checkpoint'],
+    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.',
+      "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.",
       'See heyspex_preflight({ intent: "context_rollover" }) / the context-rollover-checkpoint procedure for the full checkpoint shape.',
     ],
   },
@@ -713,37 +814,31 @@ const CLOSE_SESSION_THREAD_PATHS = {
 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.';
+  "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(', ')}.`,
+      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);
+  const catalog =
+    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
   if (!catalog) {
     return {
-      error: 'CATALOG_NOT_FOUND',
+      error: "CATALOG_NOT_FOUND",
       message:
-        'specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.',
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
     };
   }
-  const procedures = path.procedures.map((name) => {
-    const entry = findEntry(catalog, name);
-    return {
-      procedure: name,
-      severity: 'required',
-      path: entry?.path ?? null,
-      title: entry?.title ?? null,
-      missing_from_catalog: entry ? undefined : true,
-    };
-  });
-  const close_tool = path.close_tool ? buildCloseTool('close_session') : null;
+  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',
+    intent: "close_session",
     thread_type: threadType,
     thread_label: path.label,
     is_close: path.is_close,
@@ -760,46 +855,37 @@ function buildCloseSessionPreflight(vaultRoot, threadType, injectedCatalog) {
  * thread-type path too, so a single HTTP fetch covers both branches).
  */
 export function executeRunPreflight(vaultRoot, args = {}, injectedCatalog) {
-  const intent = String(args.intent ?? '').trim();
+  const intent = String(args.intent ?? "").trim();
   if (!intent) {
     return {
-      error: 'MISSING_INTENT',
-      message: `intent is required. Valid intents: ${VALID_INTENTS.join(', ')}.`,
+      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) {
+  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(', ')}.`,
+      error: "UNKNOWN_INTENT",
+      message: `Unknown intent "${intent}". Valid intents: ${VALID_INTENTS.join(", ")}.`,
     };
   }
-  const catalog = injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
+  const catalog =
+    injectedCatalog !== undefined ? injectedCatalog : loadCatalog(vaultRoot);
   if (!catalog) {
     return {
-      error: 'CATALOG_NOT_FOUND',
+      error: "CATALOG_NOT_FOUND",
       message:
-        'specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.',
+        "specs/protocols/.catalog.json not found. Run `node scripts/build-procedure-catalog.mjs`.",
     };
   }
 
-  const procedures = recommendations.map((row) => {
-    const entry = findEntry(catalog, row.procedure);
-    return {
-      procedure: row.procedure,
-      why: row.why,
-      severity: row.severity,
-      path: entry?.path ?? null,
-      title: entry?.title ?? null,
-      missing_from_catalog: entry ? undefined : true,
-    };
-  });
+  const procedures = recommendations.map((row) => resolveRow(catalog, row));
 
   const filing_tool = buildFilingTool(intent);
   const close_tool = buildCloseTool(intent);
@@ -814,15 +900,19 @@ export function executeRunPreflight(vaultRoot, args = {}, injectedCatalog) {
   // 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'];
+    "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') {
+  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) => ({
@@ -834,9 +924,64 @@ export function executeRunPreflight(vaultRoot, args = {}, injectedCatalog) {
     };
   }
 
+  // [[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) — SpexCrawl via the Companion is primary, self-hosted Firecrawl is the automatic fallback, DeepSeek synthesizes. Zero Claude/Anthropic sub-agents.",
+    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. Native WebSearch/WebFetch is the last resort only when both gather backends report unavailable; never fan out Sonnet sub-agents for research.",
+    skill_path: exists(skill) ? skill : null,
+    gather_primary: `node "${spexcrawl}" search "<query>" --json`,
+    scrape_primary: `node "${spexcrawl}" scrape "<url>" --json`,
+    gather_fallback: `node "${firecrawl}" search "<query>" --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 };
 
@@ -871,12 +1016,17 @@ function catalogFromProceduresRoute(body) {
  * 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 }) {
+export async function loadCatalogViaTier({
+  vaultRoot,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
   return readViaSelector({
     tier,
     diskRead: () => loadCatalog(vaultRoot),
     neonRead: async () => {
-      const res = await consoleFetch('/api/procedures');
+      const res = await consoleFetch("/api/procedures");
       if (!res.ok) {
         throw new Error(
           `GET /api/procedures returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`,
@@ -884,22 +1034,34 @@ export async function loadCatalogViaTier({ vaultRoot, tier, consoleFetch, consol
       }
       return catalogFromProceduresRoute(res.body);
     },
-    routeLabel: 'GET /api/procedures',
+    routeLabel: "GET /api/procedures",
     consoleUrl,
   });
 }
 
 /** Cloud-reliant sibling of {@link executeListProcedures}. */
-export async function executeListProceduresViaTier({ vaultRoot, args, tier, consoleFetch, consoleUrl }) {
+export async function executeListProceduresViaTier({
+  vaultRoot,
+  args,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
   return readViaSelector({
     tier,
     diskRead: () => executeListProcedures(vaultRoot, args),
     neonRead: async () => {
-      const catalog = await loadCatalogViaTier({ vaultRoot, tier: 'neon', consoleFetch, consoleUrl });
+      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).',
+          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
@@ -908,24 +1070,39 @@ export async function executeListProceduresViaTier({ vaultRoot, args, tier, cons
       // catalog as `injectedCatalog` runs the SAME filter logic either way.
       return executeListProcedures(vaultRoot, args, catalog);
     },
-    routeLabel: 'GET /api/procedures',
+    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 }) {
+export async function executeGetProcedureViaTier({
+  vaultRoot,
+  args,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
   return readViaSelector({
     tier,
     diskRead: () => executeGetProcedure(vaultRoot, args),
     neonRead: async () => {
-      const name = String(args?.name ?? '').trim();
+      const name = String(args?.name ?? "").trim();
       if (!name) {
-        return { error: 'MISSING_NAME', message: 'name is required (e.g. "spec-hierarchy")' };
+        return {
+          error: "MISSING_NAME",
+          message: 'name is required (e.g. "spec-hierarchy")',
+        };
       }
-      const res = await consoleFetch(`/api/procedures/${encodeURIComponent(name)}`);
+      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 };
+        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
@@ -937,34 +1114,46 @@ export async function executeGetProcedureViaTier({ vaultRoot, args, tier, consol
       // 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') {
+      if (res.status === 404 && res.body?.error === "PROCEDURE_NOT_FOUND") {
         return { error: res.body.error, message: res.body.message };
       }
       throw new Error(
-        `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 ?? {})}`,
+        `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 ?? {})}`,
       );
     },
-    routeLabel: 'GET /api/procedures/[name]',
+    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({ vaultRoot, args, tier, consoleFetch, consoleUrl }) {
+export async function executeRunPreflightViaTier({
+  vaultRoot,
+  args,
+  tier,
+  consoleFetch,
+  consoleUrl,
+}) {
   return readViaSelector({
     tier,
     diskRead: () => executeRunPreflight(vaultRoot, args),
     neonRead: async () => {
-      const catalog = await loadCatalogViaTier({ vaultRoot, tier: 'neon', consoleFetch, consoleUrl });
+      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).',
+          error: "CATALOG_NOT_FOUND",
+          message:
+            "GET /api/procedures returned no catalog (console reports it missing).",
         };
       }
       return executeRunPreflight(vaultRoot, args, catalog);
     },
-    routeLabel: 'GET /api/procedures',
+    routeLabel: "GET /api/procedures",
     consoleUrl,
   });
 }