heyspex 0.1.0

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

@@ -0,0 +1,970 @@
+/**
+ * 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 { join } from 'node:path';
+
+import { readViaSelector } from './read-path.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));
+  }
+
+  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,
+    },
+  };
+}
+
+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,
+  };
+}
+
+// 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 = {
+  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: '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).',
+      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: '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.',
+    ],
+  },
+  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.',
+    ],
+  },
+  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.',
+    ],
+  },
+  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.',
+      '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) => {
+    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;
+  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) => {
+    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 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,
+    };
+  }
+
+  return result;
+}
+
+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 new Error(
+          `GET /api/procedures returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`,
+        );
+      }
+      return catalogFromProceduresRoute(res.body);
+    },
+    routeLabel: 'GET /api/procedures',
+    consoleUrl,
+  });
+}
+
+/** Cloud-reliant sibling of {@link executeListProcedures}. */
+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 });
+      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 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 ?? {})}`,
+      );
+    },
+    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 }) {
+  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,
+  });
+}