heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/prompts.mjs

@@ -0,0 +1,1460 @@
+// MCP prompts (prompts/list, prompts/get): the PROMPTS catalog and every
+// handle*Prompt renderer (/hs-next, /hs-capture, /hs-ground, /hs-push, /hs-ship,
+// /hs-review, /hs-res, procedures, design, promote/split research). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeGetPattern as executeDesignGetPattern, executeListPatterns as executeDesignListPatterns, listProposals as listDesignProposals } from './design-tools.mjs';
+import { PREFLIGHT_INTENTS, executeGetProcedure, executeListProcedures, executeRunPreflight } from './procedure-tools.mjs';
+import { buildHsResPromptMarkdown, loadResearchFocus } from './research-focus.mjs';
+import { resolveNextReviewPayload } from './next-review.mjs';
+import { applyOnDeckHttpAugments, attachConsoleStatusToOnDeck, injectCloudWipState, injectFrozenMilestoneOrder, nextReviewDeps, resolveNextOnDeckPayload } from './on-deck-brief.mjs';
+import { buildPushWorkflowMarkdown, buildShipWorkflowMarkdown } from './plan-push.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+import { capturePinWarningBanner, createCaptureSessionOnConsole, drainCaptureOutbox, getCaptureSessionOnConsole, isCaptureSpecId, listPendingCaptureSessions, normalizeCaptureBuffer, patchCaptureSessionOnConsole, writeCaptureFocusVendor } from './capture-tools.mjs';
+import { buildHsCapturePromptMarkdown, executePinCapture, extractCaptureCoreFromBody, extractCaptureNotesFromBody, findCaptureSpecFile } from './capture-focus.mjs';
+import { outboxCount } from './capture-outbox.mjs';
+import { findSpecFile, loadSpec, parseFrontmatter } from './vault-io.mjs';
+import { injectNeonFocusPin } from './focus-tools.mjs';
+
+// MCP prompts — surfaced in Cursor/Claude as slash commands (e.g. /hs-next)
+export const PROMPTS = [
+  {
+    name: 'hs-push',
+    description:
+      'Push an epic implementation plan into the HeySpex vault (write specs, validate IDs, linkage checklist).',
+    arguments: [
+      {
+        name: 'epic_name',
+        description: 'Working title for the epic (optional if plan is only in chat)',
+        required: false,
+      },
+      {
+        name: 'plan_hint',
+        description: 'One-line summary of what to file',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-push-next',
+    description:
+      'Full workflow: push epic plan to HeySpex AND pin on deck (focus.yaml, NEXT STEP, in_progress).',
+    arguments: [
+      {
+        name: 'epic_name',
+        description: 'Working title for the epic',
+        required: false,
+      },
+      {
+        name: 'implementation_prompt',
+        description: 'Ready-to-paste prompt for the NEXT STEP block',
+        required: false,
+      },
+      {
+        name: 'focus_reason',
+        description: 'Why this epic is on deck',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-capture',
+    description:
+      'Capture-only session: load or auto-create the capture on deck, then append user words via heyspex_update_capture. Works from any MCP agent without console pre-setup, or after console + New → Capture.',
+    arguments: [
+      {
+        name: 'spec_id',
+        description: 'Optional HS-CAP-* id (default: .heyspex/capture-focus.yaml)',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-res',
+    description:
+      'Research capture from a doc-toolbar Promote pin. Loads .heyspex/research-focus.yaml, confirms scope with the user, runs the deep dive, and finalizes via heyspex_complete_research (writes HS-RES-*, updates idea promoted_to, clears pin).',
+    arguments: [],
+  },
+  {
+    name: 'hs-next',
+    description:
+      'Next on-deck execution prompt from the HeySpex roadmap. Use `/hs-next` for focus.yaml default, or `/hs-next HS-EPIC-XXXX` for a specific epic.',
+    arguments: [
+      {
+        name: 'spec_id',
+        description: 'Specific epic/task ID to fetch (e.g., "HS-EPIC-6RKN"). If omitted, uses focus.yaml or manifest order.',
+        required: false,
+      },
+      {
+        name: 'roadmap_id',
+        description: "Roadmap to query (default: env HEYSPEX_ROADMAP_ID or 'HS-ROADMAP-PRODUCT')",
+        required: false,
+      },
+      {
+        name: 'include_horizon',
+        description: 'Include horizon backlog when no scheduled open tasks remain',
+        required: false,
+      },
+      {
+        name: 'ignore_focus',
+        description: 'Skip .heyspex/focus.yaml override and use manifest traversal',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-review',
+    description:
+      'Next review-ready spec from the HeySpex review queue. Use `/hs-review` for `.heyspex/review-focus.yaml` default (or oldest in_review with HS-REV companion), or `/hs-review HS-TASK-XXXX` for a specific spec. Pastes parent body + HS-REV doc + four-axis rubric so a reviewing agent can walk acceptance.',
+    arguments: [
+      {
+        name: 'spec_id',
+        description:
+          'Specific spec id to fetch review context for (e.g., "HS-TASK-RVDC"). If omitted, uses .heyspex/review-focus.yaml or oldest in_review.',
+        required: false,
+      },
+      {
+        name: 'roadmap_id',
+        description: "Roadmap to query (default: env HEYSPEX_ROADMAP_ID or 'HS-ROADMAP-PRODUCT')",
+        required: false,
+      },
+      {
+        name: 'ignore_focus',
+        description: 'Skip .heyspex/review-focus.yaml override and use manifest/folder-scan traversal',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-backfill',
+    description:
+      'Retroactively backfill completed work into the vault (Review column). Creates epic + tasks with status: in_review and generates review doc.',
+    arguments: [
+      {
+        name: 'epic_name',
+        description: 'Title of the epic (what was accomplished)',
+        required: true,
+      },
+      {
+        name: 'summary',
+        description: 'Brief summary of what was done',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-ground',
+    description:
+      'Holistic scan, north-star alignment, architecture placement, plan stress-test, then enhance and optimize before push.',
+    arguments: [
+      {
+        name: 'topic',
+        description: 'Short title of the feature or request',
+        required: false,
+      },
+      {
+        name: 'summary',
+        description: 'Longer description or draft plan from chat',
+        required: false,
+      },
+      {
+        name: 'save_research',
+        description: 'If true, offer heyspex_save_research when discovery is large',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'hs-design-list',
+    description:
+      'Browse design system patterns from spex-console/public/design-system/. Compact summaries — use /hs-design-get for full JSON. Filter by tag, layer, or query substring.',
+    arguments: [
+      { name: 'tag', description: 'Filter to patterns whose hsTags contains this tag (e.g. "on-deck")', required: false },
+      { name: 'layer', description: 'Filter by hsLayer (primitive|semantic|component|pattern)', required: false },
+      { name: 'query', description: 'Substring match against name/title/description', required: false },
+    ],
+  },
+  {
+    name: 'hs-design-get',
+    description:
+      'Fetch one full design-system pattern (registry-item.json) by slug. Use this instead of grepping spex-console/DESIGN.md.',
+    arguments: [
+      { name: 'name', description: 'Pattern slug (e.g. "on-deck-callout-sky")', required: true },
+    ],
+  },
+  {
+    name: 'hs-design-propose',
+    description:
+      'File a new design pattern as a draft proposal at specs/design-proposals/<name>.json (humans review and promote).',
+    arguments: [
+      { name: 'name', description: 'Kebab-case slug for the new pattern', required: false },
+      { name: 'title', description: 'Short human title for the pattern', required: false },
+    ],
+  },
+  {
+    name: 'hs-procedure-list',
+    description:
+      'Browse HeySpex procedures from specs/protocols/.catalog.json. Compact summaries — use /hs-procedure for the full body. Filter by tag, trigger intent, or query substring.',
+    arguments: [
+      { name: 'tag', description: 'Filter to procedures whose tags include this value (e.g. "vault", "mcp")', required: false },
+      { name: 'trigger', description: 'Filter by trigger intent (e.g. "file_milestone", "destructive_action")', required: false },
+      { name: 'query', description: 'Substring match against name/title/summary', required: false },
+    ],
+  },
+  {
+    name: 'hs-procedure',
+    description:
+      'Fetch one full procedure body from specs/protocols/<name>.md by slug. Use this instead of grepping example specs for structural conventions.',
+    arguments: [
+      { name: 'name', description: 'Procedure slug (e.g. "spec-hierarchy", "memory-protocol")', required: true },
+    ],
+  },
+  {
+    name: 'hs-preflight',
+    description:
+      'Pre-flight checklist for a named agent intent — returns the procedures to consult before acting, each annotated with severity (required/recommended) and a short why. Then fetch each body via /hs-procedure.',
+    arguments: [
+      { name: 'intent', description: 'Intent slug: file_milestone | file_epic | file_task | file_iteration | file_diagnose | file_research | file_memory_lesson | file_memory_decision | file_memory_reference | file_memory_ui_pattern | file_review | file_capture | destructive_action | protocol_edit | memory_creation | close_session | claim_spec | execute_spec | exit_plan_mode | recommend_location | focus_pivot | server_impacting_action', required: true },
+    ],
+  },
+  {
+    name: 'hs-promote-research',
+    description:
+      'Promote a research doc (HS-RES-*) to a milestone with AI-assisted epic stubs ([[HS-TASK-QQHP]]). Two-phase: first call without accepted_stubs returns proposed stubs for human review; second call with accepted_stubs executes the transactional writes (research.enhances/spawned_epics/status + milestone.epics/informed_by + new epic files).',
+    arguments: [
+      { name: 'research_id', description: 'HS-RES-* id of the research to promote', required: true },
+      { name: 'target_milestone', description: 'HS-MIL-* id, basename, or "NEW"', required: true },
+      { name: 'intent', description: 'spawn | augment | both', required: true },
+      { name: 'new_milestone_name', description: 'Required when target_milestone === "NEW"', required: false },
+      { name: 'spawn_epic_count', description: 'Hint for AI proposer (default 2, clamped to [1,6])', required: false },
+      { name: 'augment_epic_ids', description: 'HS-EPIC-* ids to augment (required when intent includes "augment")', required: false },
+    ],
+  },
+  {
+    name: 'hs-split-research',
+    description:
+      'Split a research doc (HS-RES-*) into N (≥2) child research docs before promotion ([[HS-TASK-GTH9]]). Original becomes a closed audit archive with `split_into:` linkage; each child carries `split_from:` + a caller-prepared body_slice + a subset of original.sources_captures. Capture files\' `informs_research:` arrays update bidirectionally.',
+    arguments: [
+      { name: 'research_id', description: 'HS-RES-* id of the research to split', required: true },
+    ],
+  },
+  {
+    name: 'hs-promote-capture',
+    description:
+      'Promote 1+ captures (HS-CAP-*) into a research doc (new or existing) with AI-assisted outline ([[HS-TASK-WQCE]]). Two-phase for NEW research: first call returns a proposed { name, outline, tags, enhances_suggestion } for human review; second call with accepted_outline executes the transactional writes (research file create, capture.informs_research + first-time promoted_to). Existing research is single-phase append. Closed research is allowed with a TARGET_RESEARCH_CLOSED warning.',
+    arguments: [
+      { name: 'capture_ids', description: 'Comma-separated HS-CAP-* ids (1+)', required: true },
+      { name: 'target_research', description: 'HS-RES-* id or "NEW"', required: true },
+      { name: 'new_research_name', description: 'Required when target_research === "NEW"', required: false },
+      { name: 'enhances', description: 'Optional HS-MIL-* id/basename to set on NEW research', required: false },
+    ],
+  },
+];
+
+/**
+ * /hs-promote-research prompt — returns instruction text telling the agent to
+ * invoke the heyspex_promote_research tool with the right args. The tool is
+ * MCP-callable directly; this prompt is the slash-command bridge.
+ */
+export function handlePromoteResearchPrompt(args = {}) {
+  const researchId = args.research_id ? String(args.research_id).trim() : '';
+  const target = args.target_milestone ? String(args.target_milestone).trim() : '';
+  const intent = args.intent ? String(args.intent).trim() : '';
+
+  const lines = [
+    '# /hs-promote-research — research → milestone promotion',
+    '',
+    '**Default policy:** `target_milestone: "NEW"` (omit the field to default). Only attach to an existing milestone when it is `status: open` and clearly extends the same thesis. Spawning into `in_progress` milestones is blocked unless the owner approves `attach_to_in_progress_milestone: true` + `attach_override_reason`.',
+    '',
+    'Invoke `mcp__heyspex__heyspex_promote_research` with the args below.',
+    '',
+    '**Two-phase flow.** Call once without `accepted_stubs` to get AI-proposed epic stubs back for human review. Then call again with `accepted_stubs: [...]` (agent-edited subset) to execute the transactional writes.',
+    '',
+    '## Phase 1 — proposal',
+    '',
+    '```',
+    'heyspex_promote_research({',
+    `  research_id: "${researchId || 'HS-RES-XXXX'}",`,
+    `  target_milestone: "${target || 'NEW'}",`,
+    `  new_milestone_name: "${target === 'NEW' || !target ? 'Milestone title' : '(omit when not NEW)'}",`,
+    `  intent: "${intent || 'spawn | augment | both'}",`,
+    intent === 'augment'
+      ? '  augment_epic_ids: ["HS-EPIC-…"]'
+      : '  // spawn_epic_count: 2 (optional hint for AI)',
+    '})',
+    '```',
+    '',
+    'Show the user `proposed_stubs[]`. Let them edit/remove/approve.',
+    '',
+    '## Phase 2 — execute (after human confirms)',
+    '',
+    '```',
+    'heyspex_promote_research({',
+    `  research_id: "${researchId || 'HS-RES-XXXX'}",`,
+    `  target_milestone: "${target || 'HS-MIL-YYYY | NEW'}",`,
+    `  intent: "${intent || 'spawn'}",`,
+    '  accepted_stubs: [/* confirmed stub objects from phase 1 */]',
+    '})',
+    '```',
+    '',
+    'On success: research gets `enhances:` + `spawned_epics:` + `enhances_epics:` set and **stays `status: open`** (research is evergreen — [[research-is-evergreen]]); milestone\'s `epics:` + `informed_by:` extended; new epic files created with `parent` / `milestone` / `derived_from`. All writes roll back if any step fails.',
+  ];
+
+  return {
+    description: 'hs-promote-research — research → milestone promotion',
+    messages: [
+      {
+        role: 'user',
+        content: { type: 'text', text: lines.join('\n') },
+      },
+    ],
+  };
+}
+
+/**
+ * /hs-split-research prompt — returns instruction text telling the agent to
+ * invoke the heyspex_split_research tool. Single-phase (no AI), caller
+ * partitions body_slice + sources_captures across child entries.
+ */
+export function handleSplitResearchPrompt(args = {}) {
+  const researchId = args.research_id ? String(args.research_id).trim() : '';
+
+  const lines = [
+    '# /hs-split-research — split research that spans multiple milestones',
+    '',
+    'Invoke `mcp__heyspex__heyspex_split_research` after the human has prepared the body-slice + sources_captures partition for each child.',
+    '',
+    'The original research becomes a closed audit archive with `split_into:` linkage; each child carries `split_from:` plus its own `sources_captures` subset and body. Children land as `status: open` — milestone binding happens later via `/hs-promote-research`.',
+    '',
+    '## Call shape',
+    '',
+    '```',
+    'heyspex_split_research({',
+    `  research_id: "${researchId || 'HS-RES-XXXX'}",`,
+    '  splits: [',
+    '    {',
+    '      name: "Child research title #1",',
+    '      target_milestone: "HS-MIL-YYYY",   // or "NEW"',
+    '      // new_milestone_name: "…",       // required when target_milestone === "NEW"',
+    '      body_slice: "…markdown for this child\'s body…",',
+    '      sources_captures: ["HS-CAP-AAAA"]  // subset of original.sources_captures',
+    '    },',
+    '    {',
+    '      name: "Child research title #2",',
+    '      target_milestone: "HS-MIL-ZZZZ",',
+    '      body_slice: "…",',
+    '      sources_captures: ["HS-CAP-BBBB", "HS-CAP-CCCC"]',
+    '    }',
+    '    // … ≥2 entries total',
+    '  ]',
+    '})',
+    '```',
+    '',
+    '## Rules',
+    '',
+    '- Refuses to split if the original already has `split_into:` set (no double-split). The archive stays `status: open` — research is evergreen ([[research-is-evergreen]]).',
+    '- Each `sources_captures` entry must be a subset of the original\'s `sources_captures:`. Captures may appear in multiple children (Capture → Research is M:N).',
+    '- Caller prepares `body_slice` — no AI auto-partition in v1.',
+    '- All writes commit transactionally; any single-step failure rolls back the rest.',
+  ];
+
+  return {
+    description: 'hs-split-research — split research across milestones',
+    messages: [
+      {
+        role: 'user',
+        content: { type: 'text', text: lines.join('\n') },
+      },
+    ],
+  };
+}
+
+/**
+ * /hs-promote-capture prompt — returns instruction text telling the agent to
+ * invoke the heyspex_promote_capture tool. Two-phase for NEW research,
+ * single-phase append for existing research.
+ */
+export function handlePromoteCapturePrompt(args = {}) {
+  const captureIdsRaw = args.capture_ids ? String(args.capture_ids).trim() : '';
+  const captureIds = captureIdsRaw
+    ? captureIdsRaw
+        .split(/[,\s]+/)
+        .filter((v) => v.length > 0)
+    : [];
+  const target = args.target_research ? String(args.target_research).trim() : '';
+  const newName = args.new_research_name ? String(args.new_research_name).trim() : '';
+  const enhances = args.enhances ? String(args.enhances).trim() : '';
+
+  const captureIdsRendered =
+    captureIds.length > 0
+      ? `[${captureIds.map((id) => `"${id}"`).join(', ')}]`
+      : '["HS-CAP-AAAA", "HS-CAP-BBBB"]';
+
+  const lines = [
+    '# /hs-promote-capture — capture(s) → research promotion',
+    '',
+    'Invoke `mcp__heyspex__heyspex_promote_capture` with the args below.',
+    '',
+    '**Flow depends on target_research:**',
+    '- `target_research: "NEW"` → **two-phase**: first call without `accepted_outline` returns a proposed `{ name, outline, tags, enhances_suggestion }` for human review. Second call with `accepted_outline` populated executes the writes.',
+    '- `target_research: "HS-RES-XXXX"` (existing) → **single-phase**: appends captures into the existing research\'s `sources_captures:`, sets each capture\'s `informs_research:`, and sets `promoted_to:` on captures that had none. Idempotent on re-runs.',
+    '',
+    '## Phase 1 — proposal (NEW research only)',
+    '',
+    '```',
+    'heyspex_promote_capture({',
+    `  capture_ids: ${captureIdsRendered},`,
+    `  target_research: "${target || 'NEW'}",`,
+    `  new_research_name: "${newName || 'Working title for the new research doc'}",`,
+    enhances ? `  enhances: "${enhances}",` : '  // enhances: "HS-MIL-…",   // optional',
+    '})',
+    '```',
+    '',
+    'Show the user `proposed_outline`. Let them edit name/outline/tags/enhances_suggestion.',
+    '',
+    '## Phase 2 — execute (after human confirms, or single-phase for existing research)',
+    '',
+    '```',
+    'heyspex_promote_capture({',
+    `  capture_ids: ${captureIdsRendered},`,
+    `  target_research: "${target || 'NEW or HS-RES-XXXX'}",`,
+    target === 'NEW' || !target ? `  new_research_name: "${newName || 'Final research title'}",` : '',
+    target === 'NEW' || !target
+      ? '  accepted_outline: { name, outline, tags, enhances_suggestion? }'
+      : '  // existing target — no accepted_outline needed',
+    '})',
+  ]
+    .filter(Boolean)
+    .concat([
+      '```',
+      '',
+      'On success: capture.informs_research extended for every input capture; capture.promoted_to set on first promotion only; research.sources_captures extended (research file created if NEW). Closed-research target returns `warning: "TARGET_RESEARCH_CLOSED"` but still appends. All writes commit transactionally; any failure rolls back.',
+    ]);
+
+  return {
+    description: 'hs-promote-capture — capture(s) → research promotion',
+    messages: [
+      {
+        role: 'user',
+        content: { type: 'text', text: lines.join('\n') },
+      },
+    ],
+  };
+}
+
+export function handlePromptsList() {
+  return { prompts: PROMPTS };
+}
+
+export function handleDesignListPrompt(vaultRoot, args = {}) {
+  const result = executeDesignListPatterns(vaultRoot, args);
+  if (result.error) {
+    return {
+      description: `hs-design-list — ${result.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Could not list design patterns:\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+
+  const filterSummary = [
+    args.tag ? `tag=${args.tag}` : null,
+    args.layer ? `layer=${args.layer}` : null,
+    args.query ? `query="${args.query}"` : null,
+  ].filter(Boolean).join(', ') || 'no filters';
+
+  const lines = [
+    `# HeySpex design patterns — ${result.count}/${result.total}`,
+    '',
+    `_Filters: ${filterSummary}_`,
+    '',
+  ];
+  if (result.patterns.length === 0) {
+    lines.push('_No matching patterns. Drop a filter or call `heyspex_design_list_patterns` with different args._');
+  } else {
+    for (const p of result.patterns) {
+      const tagList = p.tags.length > 0 ? ` · tags: ${p.tags.join(', ')}` : '';
+      lines.push(`- **\`${p.name}\`** — ${p.title ?? '(untitled)'} _(layer: ${p.layer ?? '—'})${tagList}_`);
+      if (p.summary) lines.push(`  ${p.summary}`);
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push('Fetch a full registry item with `heyspex_design_get_pattern({ name: "<slug>" })`.');
+  }
+
+  return {
+    description: `hs-design-list — ${result.count} pattern(s)`,
+    messages: [
+      { role: 'user', content: { type: 'text', text: lines.join('\n') } },
+    ],
+  };
+}
+
+export function handleDesignGetPrompt(vaultRoot, args = {}) {
+  const name = String(args.name ?? '').trim();
+  if (!name) {
+    return {
+      description: 'hs-design-get — missing pattern name',
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Call `/hs-design-get <pattern-slug>` (e.g. `/hs-design-get on-deck-callout-sky`). Use `/hs-design-list` first to discover slugs.',
+          },
+        },
+      ],
+    };
+  }
+  const result = executeDesignGetPattern(vaultRoot, { name });
+  if (result.error) {
+    return {
+      description: `hs-design-get — ${result.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Could not fetch \`${name}\`:\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\`\n\nRun \`/hs-design-list\` to see available patterns.`,
+          },
+        },
+      ],
+    };
+  }
+
+  const text = [
+    `# Design pattern — \`${result.pattern.name}\``,
+    '',
+    `_Source: ${result.source}_`,
+    '',
+    '```json',
+    JSON.stringify(result.pattern, null, 2),
+    '```',
+    '',
+    `For the prose anchor in \`spex-console/DESIGN.md\`, call \`heyspex_design_get_doc({ name: "${result.pattern.name}" })\`.`,
+  ].join('\n');
+
+  return {
+    description: `hs-design-get — ${result.pattern.name}`,
+    messages: [{ role: 'user', content: { type: 'text', text } }],
+  };
+}
+
+export function handleDesignProposePrompt(vaultRoot, args = {}) {
+  const existingProposals = listDesignProposals(vaultRoot);
+  const slugHint = String(args.name ?? '<kebab-case-slug>').trim();
+  const titleHint = String(args.title ?? '<short human title>').trim();
+
+  const text = [
+    '# HeySpex hs-design-propose',
+    '',
+    'Draft a new design pattern proposal. The MCP tool writes the JSON to `specs/design-proposals/<name>.json`; a human reviews and promotes it into `spex-console/public/design-system/r/` later.',
+    '',
+    '**Execute:** Call MCP tool `heyspex_design_propose_pattern` with JSON:',
+    '',
+    '```json',
+    JSON.stringify(
+      {
+        name: slugHint,
+        title: titleHint,
+        description: '<one-paragraph: purpose, anatomy, when to use>',
+        hsLayer: '<primitive|semantic|component|pattern>',
+        hsTags: ['<tag1>', '<tag2>'],
+        hsDecisionRefs: ['<memory-decision-basename>'],
+        cssVars: {
+          dark: { '--example-var': '#000000' },
+          light: { '--example-var': '#ffffff' },
+        },
+        hsCodePreview: '<optional standalone HTML snippet>',
+      },
+      null,
+      2,
+    ),
+    '```',
+    '',
+    '**Conventions:**',
+    '- `name` must be kebab-case and unique against `spex-console/public/design-system/r/*.json`.',
+    '- `hsLayer` is required — pick the most specific tier the pattern fits.',
+    '- After filing, edit `specs/design-proposals/<name>.json` directly to refine before promotion.',
+    '',
+    existingProposals.length > 0
+      ? `_Existing proposals (${existingProposals.length}): ${existingProposals.map((s) => `\`${s}\``).join(', ')}_`
+      : '_No existing proposals yet._',
+  ].join('\n');
+
+  return {
+    description: 'hs-design-propose — draft a new pattern',
+    messages: [{ role: 'user', content: { type: 'text', text } }],
+  };
+}
+
+export function handleProcedureListPrompt(vaultRoot, args = {}) {
+  const result = executeListProcedures(vaultRoot, args);
+  if (result.error) {
+    return {
+      description: `hs-procedure-list — ${result.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Could not list procedures:\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+
+  const filterSummary = [
+    args.tag ? `tag=${args.tag}` : null,
+    args.trigger ? `trigger=${args.trigger}` : null,
+    args.query ? `query="${args.query}"` : null,
+  ].filter(Boolean).join(', ') || 'no filters';
+
+  const lines = [
+    `# HeySpex procedures — ${result.procedures.length} on this page${result.next_cursor ? ' (more available — pass `after`)' : ''}`,
+    '',
+    `_Filters: ${filterSummary}_`,
+    '',
+  ];
+  if (result.procedures.length === 0) {
+    lines.push('_No matching procedures. Drop a filter or call `heyspex_list_procedures` with different args._');
+  } else {
+    for (const p of result.procedures) {
+      const tagList = p.tags.length > 0 ? ` · tags: ${p.tags.join(', ')}` : '';
+      const triggerList = p.triggers.length > 0 ? ` · triggers: ${p.triggers.join(', ')}` : '';
+      lines.push(`- **\`${p.name}\`** — ${p.title ?? '(untitled)'}${tagList}${triggerList}`);
+      if (p.summary) lines.push(`  ${p.summary}`);
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push('Fetch a full procedure body with `/hs-procedure <name>` (e.g. `/hs-procedure spec-hierarchy`).');
+  }
+
+  return {
+    description: `hs-procedure-list — ${result.procedures.length} procedure(s)${result.next_cursor ? ' (paged)' : ''}`,
+    messages: [
+      { role: 'user', content: { type: 'text', text: lines.join('\n') } },
+    ],
+  };
+}
+
+export function handleProcedurePrompt(vaultRoot, args = {}) {
+  const name = String(args.name ?? '').trim();
+  if (!name) {
+    return {
+      description: 'hs-procedure — missing procedure name',
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Call `/hs-procedure <name>` (e.g. `/hs-procedure spec-hierarchy`). Use `/hs-procedure-list` first to discover slugs.',
+          },
+        },
+      ],
+    };
+  }
+  const result = executeGetProcedure(vaultRoot, { name });
+  if (result.error) {
+    return {
+      description: `hs-procedure — ${result.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Could not fetch \`${name}\`:\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\`\n\nRun \`/hs-procedure-list\` to see available procedures.`,
+          },
+        },
+      ],
+    };
+  }
+
+  const { procedure, content, source } = result;
+  const tagList = procedure.tags.length > 0 ? procedure.tags.join(', ') : '—';
+  const triggerList = procedure.triggers.length > 0 ? procedure.triggers.join(', ') : '—';
+
+  const text = [
+    `# Procedure — \`${procedure.name}\``,
+    '',
+    `**${procedure.title ?? '(untitled)'}** · id \`${procedure.id ?? '—'}\` · status \`${procedure.status ?? '—'}\``,
+    `tags: ${tagList} · triggers: ${triggerList}`,
+    '',
+    `_Source: \`${source}\`_`,
+    '',
+    '---',
+    '',
+    content,
+  ].join('\n');
+
+  return {
+    description: `hs-procedure — ${procedure.name}`,
+    messages: [{ role: 'user', content: { type: 'text', text } }],
+  };
+}
+
+export function handlePreflightPrompt(vaultRoot, args = {}) {
+  const intent = String(args.intent ?? '').trim();
+  if (!intent) {
+    return {
+      description: 'hs-preflight — missing intent',
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Call \`/hs-preflight <intent>\`. Valid intents: ${PREFLIGHT_INTENTS.join(', ')}.`,
+          },
+        },
+      ],
+    };
+  }
+  const result = executeRunPreflight(vaultRoot, { intent });
+  if (result.error) {
+    return {
+      description: `hs-preflight — ${result.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Pre-flight failed:\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+
+  const lines = [
+    `# Pre-flight — \`${result.intent}\``,
+    '',
+    `Consult these procedures before acting. Fetch each body with \`/hs-procedure <name>\`.`,
+    '',
+  ];
+  for (const row of result.procedures) {
+    const badge =
+      row.severity === 'required'
+        ? '**required**'
+        : row.severity === 'advisory'
+          ? '_advisory (not in this vault)_'
+          : '_recommended_';
+    const path = row.path ? ` · \`${row.path}\`` : ' · _missing from catalog_';
+    lines.push(`- ${badge} — **\`${row.procedure}\`**${path}`);
+    if (row.title) lines.push(`  ${row.title}`);
+    if (row.why) lines.push(`  Why: ${row.why}`);
+  }
+
+  if (result.filing_tool) {
+    const ft = result.filing_tool;
+    lines.push('');
+    lines.push('## File it with the canonical tool');
+    lines.push('');
+    lines.push(`Call \`${ft.tool}\` — do **not** copy a sibling spec's frontmatter.`);
+    lines.push('');
+    lines.push('```jsonc');
+    lines.push(`${ft.tool}(${JSON.stringify(ft.minimal_call ?? {}, null, 2)})`);
+    lines.push('```');
+    if (ft.note) lines.push(`> ${ft.note}`);
+  }
+
+  if (result.close_tool) {
+    const ct = result.close_tool;
+    lines.push('');
+    lines.push('## Close-out status flip (required)');
+    lines.push('');
+    lines.push(`Call \`${ct.tool}\` — **never** hand-edit \`status:\` in frontmatter.`);
+    lines.push('');
+    lines.push('```jsonc');
+    lines.push(`${ct.tool}(${JSON.stringify(ct.minimal_call ?? {}, null, 2)})`);
+    lines.push('```');
+    if (ct.note) lines.push(`> ${ct.note}`);
+  }
+
+  return {
+    description: `hs-preflight — ${result.intent} (${result.procedures.length})`,
+    messages: [{ role: 'user', content: { type: 'text', text: lines.join('\n') } }],
+  };
+}
+
+export function handleResPrompt(vaultRoot) {
+  const focus = loadResearchFocus(vaultRoot);
+  const markdown = buildHsResPromptMarkdown(focus, { vaultRoot });
+  return {
+    description: focus?.source_idea_id
+      ? `Research on deck: ${focus.source_idea_id} (scope: ${focus.scope || 'internal'})`
+      : 'No research pinned — run console Promote first',
+    messages: [
+      {
+        role: 'user',
+        content: { type: 'text', text: markdown },
+      },
+    ],
+  };
+}
+
+export function handleReviewPrompt(vaultRoot, config, args = {}) {
+  const { error, result } = resolveNextReviewPayload(
+    vaultRoot,
+    config,
+    args,
+    nextReviewDeps(),
+  );
+
+  if (error) {
+    return {
+      description: `hs-review — ${error.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `HeySpex could not resolve the next review-ready spec:\n\n\`\`\`json\n${JSON.stringify(error, null, 2)}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+
+  const header = `# Next review — ${result.spec_id}
+
+**${result.title}** · status \`${result.status}\` · source \`${result.source_kind}\`${result.phase_name ? ` · phase **${result.phase_name}**` : ''}${typeof result.age_in_review_days === 'number' ? ` · age ${result.age_in_review_days}d` : ''}
+
+---
+
+`;
+
+  return {
+    description: `Next review: ${result.spec_id} — ${result.title}`,
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `${header}${result.user_prompt_markdown ?? result.prompt_markdown}\n\n---\n\n_Review this spec next. Parent: \`${result.parent_spec_path}\` · Review doc: \`${result.review_doc_path}\` · resolved ${result.resolved_at}_`,
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * [[HS-PG9I-TASK]] — synthesize the minimal markdown body the prompt builder needs
+ * to render the Summary section for a DB-resident (not-yet-materialized) capture,
+ * whose state lives in the content_buffer rather than a markdown file.
+ */
+export function buildResumePromptBody(norm = {}) {
+  let body = '# Core Idea\n';
+  if (norm.core) body += `\n${norm.core}\n`;
+  if (norm.summary) body += `\n## Summary\n\n${norm.summary}\n`;
+  return body;
+}
+
+/**
+ * [[HS-PG9I-TASK]] / [[HS-34KP-RES]] — resolve and attach to an EXPLICITLY named
+ * capture, DB-first with a disk fallback for materialized/legacy captures. Mirrors
+ * handleActiveCapture's id-honoring pattern. Never lists pending sessions and never
+ * creates a new capture — a missing id returns a clear "no such capture" message.
+ * When the capture already has a Core Idea, the prompt renders the resume branch
+ * (expand / iterate / promote) instead of a fresh first-capture instruction.
+ */
+export async function resumeCaptureById(vaultRoot, identity, promptName, wantedId) {
+  // DB FIRST: a pending capture session has no markdown file yet, so a disk-only
+  // lookup would 404 it. Resolve the live session row by id.
+  const got = await getCaptureSessionOnConsole(wantedId);
+  if (got.ok && got.session) {
+    let session = got.session;
+    // Attach this agent/session to the named capture — no second row (Q3 semantics).
+    const attachResult = await patchCaptureSessionOnConsole(session.id, {
+      attach: { agent: identity.agent, sessionId: identity.sessionId },
+    });
+    // Keep the capture-on-deck pin pointing at the resumed capture so a later no-id
+    // call — in this or a fresh session — resolves back to it, not to whatever was
+    // most-recently-active.
+    // Measured, not assumed ([[HS-IOJW-5YDH-DIAG]] sweep): the return value used to
+    // be discarded, so a pin that never persisted still rendered a clean "resumed"
+    // prompt — and the next no-id /hs-capture then resolved to a DIFFERENT capture.
+    const focusPin = await writeCaptureFocusVendor(vaultRoot, {
+      specId: session.id,
+      specPath: session.specPath || '',
+      reason: `Resumed via /${promptName}`,
+      claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+    });
+    // Flush any offline-buffered captures into this session now that we're
+    // online (append against the live buffer, not a blank one — HS-K27H).
+    const drain = await drainCaptureOutbox(
+      vaultRoot,
+      session.id,
+      identity,
+      session.contentBuffer && typeof session.contentBuffer === 'object'
+        ? session.contentBuffer
+        : {},
+    );
+    if (drain.drained > 0) {
+      const refetched = await getCaptureSessionOnConsole(session.id);
+      if (refetched.ok && refetched.session) session = refetched.session;
+    }
+    const contentBuffer = session.contentBuffer || {};
+    const norm = normalizeCaptureBuffer(contentBuffer);
+    const isResume = norm.core.length > 0;
+    const resolved = {
+      spec_id: session.id,
+      spec_path: session.specPath || null,
+      name: contentBuffer.name || `Capture ${session.id}`,
+      core_idea: norm.core,
+      notes: norm.notes,
+      body: buildResumePromptBody(norm),
+      frontmatter: { id: session.id, status: session.status },
+    };
+    const openedAgo = session.createdAt
+      ? formatTimeSince(new Date(session.createdAt))
+      : 'unknown';
+    const banner = isResume
+      ? `_Resumed capture \`${session.id}\` — it already has a Core Idea. This is a **resume**, not a new capture: offer to expand, iterate, or promote to research; do not re-capture from scratch._\n\n`
+      : `_Attached to capture \`${session.id}\` (opened by ${session.openedBy}, ${openedAgo} ago)._\n\n`;
+    const markdown =
+      capturePinWarningBanner(focusPin, session.id) +
+      banner +
+      buildHsCapturePromptMarkdown(resolved, { fresh: false, resume: isResume });
+    return {
+      description: `Capture on deck: ${session.id} (${isResume ? 'resumed' : 'attached'}${attachResult.ok ? '' : ' — attach failed'}${focusPin.pinned ? '' : ' — PIN NOT WRITTEN'})`,
+      messages: [{ role: 'user', content: { type: 'text', text: markdown } }],
+    };
+  }
+
+  // DB miss (404 / GET_FAILED) or console unreachable → fall back to disk for a
+  // materialized / legacy capture whose live session row is gone.
+  const specPath =
+    findCaptureSpecFile(vaultRoot, wantedId) || findSpecFile(vaultRoot, wantedId);
+  if (specPath) {
+    const spec = loadSpec(vaultRoot, specPath);
+    if (spec) {
+      const coreIdea = extractCaptureCoreFromBody(spec.body) || '';
+      const isResume = coreIdea.trim().length > 0;
+      // Re-pin the capture-on-deck to this materialized capture.
+      const pin = executePinCapture(vaultRoot, parseFrontmatter, loadSpec, {
+        spec_id: wantedId,
+        reason: `Resumed via /${promptName}`,
+      });
+      const resolved = {
+        spec_id: spec.frontmatter?.id || wantedId,
+        spec_path: specPath,
+        name: spec.frontmatter?.name || `Capture ${wantedId}`,
+        core_idea: coreIdea,
+        notes: extractCaptureNotesFromBody(spec.body) || '',
+        body: spec.body || '',
+        frontmatter: spec.frontmatter || { id: wantedId },
+      };
+      const banner = isResume
+        ? `_Resumed capture \`${resolved.spec_id}\` from disk — it already has a Core Idea. This is a **resume**, not a new capture: offer to expand, iterate, or promote to research; do not re-capture from scratch._\n\n`
+        : `_Attached to capture \`${resolved.spec_id}\` (from disk)._\n\n`;
+      const markdown = banner + buildHsCapturePromptMarkdown(resolved, { fresh: false, resume: isResume });
+      return {
+        description: `Capture on deck: ${resolved.spec_id} (${isResume ? 'resumed' : 'attached'} from disk${pin.error ? ' — pin failed' : ''})`,
+        messages: [{ role: 'user', content: { type: 'text', text: markdown } }],
+      };
+    }
+  }
+
+  // Neither a live session nor a disk file → clear not-found. NEVER auto-create a
+  // near-miss id (the [[capture-guardrails]] "scope to the intended id" rule).
+  return {
+    description: `${promptName} — no such capture ${wantedId}`,
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text:
+            `**No capture \`${wantedId}\` found.**\n\n` +
+            `There is no live capture session or vault file with that id, so I did **not** open a workspace — ` +
+            `and I did **not** create a new capture, which would silently drop the id you named.\n\n` +
+            `- To start a fresh capture, run \`/hs-capture\` with no id.\n` +
+            `- If you expected \`${wantedId}\` to exist, double-check the id.`,
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * [[HS-TASK-MJJK]] — /hs-capture prompt handler rewired for session-first attach.
+ *
+ * 1. Query GET /api/capture/sessions?status=pending for an existing session.
+ * 2. If found: attach to it (PATCH with agent info); no new row created.
+ * 3. If not found: POST to create a new pending session.
+ * 4. If API unreachable: fall back to file-based logic (no regression).
+ *
+ * Running /hs-capture twice back-to-back results in one row, not two (Q3 attach semantics).
+ */
+export async function handleCapturePrompt(vaultRoot, args = {}) {
+  const promptName = 'hs-capture';
+  const identity = detectAgentIdentity();
+
+  // [[HS-PG9I-TASK]] / [[HS-34KP-RES]] — honor an EXPLICIT capture id (resume-aware).
+  // Pre-fix bug: the id was pinned but the session-first path below IGNORED the pin,
+  // listed pending sessions, and minted a NEW capture (VDPB → V5KI). When an id is
+  // named we resolve THAT capture (DB-first, disk fallback) and short-circuit — never
+  // fall through to list/create. This is the cross-session resume guarantee: re-entering
+  // /hs-capture with an id reopens the same capture instead of attaching to whatever was
+  // most-recently-active. A missing id returns a clear error, never a silent auto-create.
+  if (args.spec_id && isCaptureSpecId(args.spec_id)) {
+    const wantedId = String(args.spec_id).trim().toUpperCase();
+    return await resumeCaptureById(vaultRoot, identity, promptName, wantedId);
+  }
+
+  // [[HS-TASK-MJJK]] — No explicit id: query sessions API for pending sessions first
+  const sessionsResult = await listPendingCaptureSessions();
+
+  if (sessionsResult.ok && sessionsResult.sessions.length > 0) {
+    // Attach to existing session (Q3: attach silently, no second row)
+    let session = sessionsResult.sessions[0];
+    const attachResult = await patchCaptureSessionOnConsole(session.id, {
+      attach: {
+        agent: identity.agent,
+        sessionId: identity.sessionId,
+      },
+    });
+
+    // Flush any offline-buffered captures into this session now that we're
+    // online (append against the live buffer, not a blank one — HS-K27H).
+    const drain = await drainCaptureOutbox(
+      vaultRoot,
+      session.id,
+      identity,
+      session.contentBuffer && typeof session.contentBuffer === 'object'
+        ? session.contentBuffer
+        : {},
+    );
+    if (drain.drained > 0) {
+      const refetched = await getCaptureSessionOnConsole(session.id);
+      if (refetched.ok && refetched.session) session = refetched.session;
+    }
+
+    // Calculate time since session was opened
+    const openedAgo = session.createdAt
+      ? formatTimeSince(new Date(session.createdAt))
+      : 'unknown';
+
+    // Build resolved object for prompt markdown
+    const contentBuffer = session.contentBuffer || {};
+    const resolved = {
+      spec_id: session.id,
+      spec_path: session.specPath || null,
+      name: contentBuffer.name || `Capture ${session.id}`,
+      core_idea: contentBuffer.core_idea || '',
+      notes: contentBuffer.notes || '',
+      body: '',  // Body is in contentBuffer, not a file
+      frontmatter: { id: session.id, status: session.status },
+    };
+
+    const attachNote = `_Attached to existing capture \`${session.id}\` (opened by ${session.openedBy}, ${openedAgo} ago)._\n\n`;
+    const markdown = attachNote + buildHsCapturePromptMarkdown(resolved, { fresh: false });
+
+    return {
+      description: `Capture on deck: ${session.id} (attached${attachResult.ok ? '' : ' — attach failed'})`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: markdown,
+          },
+        },
+      ],
+    };
+  }
+
+  // No pending session found — try to create a new one via API
+  if (sessionsResult.ok) {
+    const createResult = await createCaptureSessionOnConsole({
+      opened_by: 'agent',
+      opened_by_session: identity.sessionId,
+      mode: 'attended',
+      status: 'pending',
+    });
+
+    if (createResult.ok && createResult.session) {
+      let session = createResult.session;
+
+      // Pin capture-on-deck + layer-2 metadata to Neon ([[HS-TASK-CFL2]]; file
+      // is the offline fallback).
+      const focusPin = await writeCaptureFocusVendor(vaultRoot, {
+        specId: session.id,
+        specPath: session.specPath || '',
+        reason: `Auto-created via /${promptName}`,
+        claim: { claimed_by: identity.agent, claim_session: identity.sessionId },
+      });
+
+      // Flush any offline-buffered captures into the new session (a fresh
+      // session's buffer is empty, so {} is genuinely correct here).
+      const drain = await drainCaptureOutbox(vaultRoot, session.id, identity, {});
+      if (drain.drained > 0) {
+        const refetched = await getCaptureSessionOnConsole(session.id);
+        if (refetched.ok && refetched.session) session = refetched.session;
+      }
+
+      const contentBuffer = session.contentBuffer || {};
+      const resolved = {
+        spec_id: session.id,
+        spec_path: session.specPath || null,
+        name: contentBuffer.name || `Capture ${session.id}`,
+        core_idea: contentBuffer.core_idea || '',
+        notes: contentBuffer.notes || '',
+        body: '',
+        frontmatter: { id: session.id, status: session.status },
+      };
+
+      const freshNote = `_Auto-created \`${session.id}\` — no prior content. The user's next message will be the first capture._\n\n`;
+      const markdown =
+        capturePinWarningBanner(focusPin, session.id) +
+        freshNote +
+        buildHsCapturePromptMarkdown(resolved, { fresh: true });
+
+      return {
+        description: `Capture on deck: ${session.id} (auto-created via API)`,
+        messages: [
+          {
+            role: 'user',
+            content: {
+              type: 'text',
+              text: markdown,
+            },
+          },
+        ],
+      };
+    }
+  }
+
+  // API unreachable or create failed — capture is online-only, so we do NOT mint
+  // a local file scaffold ([[heyspex-is-online-only-no-offline]]). /hs-capture
+  // itself carries no user words yet (those arrive via heyspex_update_capture,
+  // which stashes to the offline buffer), so there's nothing to stash here — just
+  // a graceful, SaaS-grade message. Anything already buffered stays safe and will
+  // sync on reconnect.
+  const pending = outboxCount(vaultRoot);
+  const pendingNote = pending > 0
+    ? ` You have ${pending} capture${pending === 1 ? '' : 's'} saved offline; they'll sync automatically once the connection is back.`
+    : '';
+  return {
+    description: `${promptName} — server unreachable (capture deferred)`,
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text:
+            "**HeySpex can't reach the server right now, so I can't open your capture workspace yet.**\n\n" +
+            "Anything you've already captured is safe." + pendingNote + "\n\n" +
+            "Tell me what you'd like to capture and I'll hold onto your exact words — they'll be filed automatically the moment the connection is back. Nothing will be lost.",
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Format a time duration since a given date in human-readable form.
+ */
+export function formatTimeSince(date) {
+  const now = new Date();
+  const diffMs = now - date;
+  const diffMins = Math.floor(diffMs / 60000);
+  if (diffMins < 1) return '<1m';
+  if (diffMins < 60) return `${diffMins}m`;
+  const diffHours = Math.floor(diffMins / 60);
+  if (diffHours < 24) return `${diffHours}h`;
+  const diffDays = Math.floor(diffHours / 24);
+  return `${diffDays}d`;
+}
+
+export function handleGroundPrompt(args = {}) {
+  // Thin trigger (G7R2/G7R6): call the bounded report path and paste it verbatim.
+  // The legacy six-phase read-everything scaffold (buildGroundWorkflowMarkdown) is
+  // retired from the prompt surface — it caused the context-bloat failure documented
+  // in hs-ground-as-built-mcp-failure-modes.
+  const text = [
+    '# Ground plan (`/hs-ground`)',
+    '',
+    'Bounded pre-plan grounding. Substrate is production-lexical; **you are the reranker**.',
+    '',
+    '**Execute:** Call MCP tool `heyspex_ground_plan` with `report: true`:',
+    '',
+    '```json',
+    JSON.stringify(
+      {
+        topic: args.topic || '<Short feature title>',
+        summary: args.summary || args.plan_hint || '<Description from chat>',
+        areas: ['<optional: console | companion | mcp | vault | indexer>'],
+        report: true,
+        max_tokens: 2000,
+      },
+      null,
+      2,
+    ),
+    '```',
+    '',
+    '**Then:** Paste the returned report verbatim and act on it. Do **NOT** open the discovered specs, run broad `rg`, or read whole files — open only the one or two specs you judge directly relevant.',
+    '',
+    'If the footer shows **BLOCKING** conflicts, run `/hs-resolve` first, then re-run `/hs-ground`.',
+    '',
+    '**Handoff:** With a grounded plan, run `/hs-push` or `/hs-push-next`.',
+  ].join('\n');
+
+  return {
+    description: 'hs-ground — bounded pre-plan grounding before push',
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text,
+        },
+      },
+    ],
+  };
+}
+
+export function handlePushPrompt(name, args = {}) {
+  const onDeck = name === 'hs-push-next';
+  const workflow = buildPushWorkflowMarkdown({
+    on_deck: onDeck,
+    epic_name: args.epic_name,
+    plan_hint: args.plan_hint || args.implementation_prompt?.slice(0, 200),
+  });
+
+  const toolHint = [
+    '',
+    '---',
+    '',
+    '**Execute:** Call MCP tool `heyspex_push_plan` with JSON from the plan above, e.g.:',
+    '',
+    '```json',
+    JSON.stringify(
+      {
+        epic_name: args.epic_name || '<Epic title from plan>',
+        summary: '<Plain-language epic summary per spec-summary-authoring>',
+        plan_markdown: '<Epic body markdown>',
+        implementation_prompt: args.implementation_prompt || '<Optional NEXT STEP override>',
+        source_plan_paths: [
+          '.cursor/plans/<name>.plan.md',
+          'C:\\Users\\<you>\\.cursor\\plans\\<name>.plan.md',
+        ],
+        on_deck: onDeck,
+        focus_reason: args.focus_reason || (onDeck ? 'hs-push-next' : undefined),
+      },
+      null,
+      2,
+    ),
+    '```',
+    '',
+    onDeck
+      ? 'Then run `/hs-next` or `heyspex_next_on_deck` to pull the on-deck prompt.'
+      : 'When ready to implement, run `/hs-push-next` or re-push with `on_deck: true`.',
+  ].join('\n');
+
+  return {
+    description: onDeck
+      ? 'hs-push-next — push plan to HeySpex and pin on deck'
+      : 'hs-push — push epic plan to HeySpex vault',
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `${workflow}\n${toolHint}`,
+        },
+      },
+    ],
+  };
+}
+
+export function handleShipPrompt(args = {}) {
+  const workflow = buildShipWorkflowMarkdown();
+
+  const toolHint = [
+    '',
+    '---',
+    '',
+    '**Execute:** Call MCP tool `heyspex_backfill_epic` with JSON gathered from the conversation:',
+    '',
+    '```json',
+    JSON.stringify(
+      {
+        epic_name: args.epic_name || '<What was accomplished>',
+        summary: args.summary || '<Brief description>',
+        plan_markdown: '<What was done, acceptance criteria met>',
+        children: [
+          { name: '<Task 1>', summary: '<What was done>' },
+        ],
+        files_changed: [
+          '<path/to/file1.ts>',
+          '<path/to/file2.tsx>',
+        ],
+        roadmap_id: 'HS-ROADMAP-PRODUCT',
+        roadmap_phase: 'P0',
+      },
+      null,
+      2,
+    ),
+    '```',
+    '',
+    '**Roadmap registration:** By default, shipped epics are added to `P0` of `HS-ROADMAP-PRODUCT` so they appear in the kanban Review column. Use `skip_roadmap_registration: true` to disable.',
+    '',
+    'Then commit and push the new specs.',
+  ].join('\n');
+
+  return {
+    description: 'hs-backfill — retroactively backfill completed work into Review',
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `${workflow}\n${toolHint}`,
+        },
+      },
+    ],
+  };
+}
+
+export function handlePromptsGet(vaultRoot, config, params) {
+  const { name, arguments: args = {} } = params;
+
+  if (name === 'hs-push' || name === 'hs-push-next') {
+    return handlePushPrompt(name, args);
+  }
+
+  if (name === 'hs-backfill') {
+    return handleShipPrompt(args);
+  }
+
+  if (name === 'hs-ground') {
+    return handleGroundPrompt(args);
+  }
+
+  if (name === 'hs-capture') {
+    // [[HS-TASK-MJJK]] — async handler for session-first attach
+    return handleCapturePrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-res') {
+    return handleResPrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-review') {
+    return handleReviewPrompt(vaultRoot, config, args);
+  }
+
+  if (name === 'hs-design-list') {
+    return handleDesignListPrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-design-get') {
+    return handleDesignGetPrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-design-propose') {
+    return handleDesignProposePrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-procedure-list') {
+    return handleProcedureListPrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-procedure') {
+    return handleProcedurePrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-preflight') {
+    return handlePreflightPrompt(vaultRoot, args);
+  }
+
+  if (name === 'hs-promote-research') {
+    return handlePromoteResearchPrompt(args);
+  }
+
+  if (name === 'hs-split-research') {
+    return handleSplitResearchPrompt(args);
+  }
+
+  if (name === 'hs-promote-capture') {
+    return handlePromoteCapturePrompt(args);
+  }
+
+  if (name !== 'hs-next') {
+    throw new Error(`Unknown prompt: ${name}`);
+  }
+
+  // Async: resolves the Neon layer-1 pin (`injectNeonFocusPin`) before the sync
+  // resolver. handlePromptsGet stays sync and returns this promise; the
+  // `prompts/get` dispatcher already awaits a thenable result.
+  return handleNextOnDeckPrompt(vaultRoot, config, args);
+}
+
+/**
+ * The `hs-next` prompt body, async so it can consult the Neon layer-1 focus pin
+ * before running the synchronous on-deck resolver. Mirrors `handleNextOnDeck`
+ * (the tools/call path) — both inject `neon_pin_spec_id` via `injectNeonFocusPin`.
+ */
+export async function handleNextOnDeckPrompt(vaultRoot, config, args) {
+  const resolvedArgs = await injectCloudWipState(
+    vaultRoot,
+    await injectFrozenMilestoneOrder(await injectNeonFocusPin(args)),
+  );
+  const { error, result } = await resolveNextOnDeckAroundActiveClaims(
+    vaultRoot,
+    config,
+    resolvedArgs,
+  );
+
+  if (error) {
+    return {
+      description: `hs-next — ${error.error}`,
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `HeySpex could not resolve the next on-deck task:\n\n\`\`\`json\n${JSON.stringify(error, null, 2)}\n\`\`\``,
+          },
+        },
+      ],
+    };
+  }
+
+  await applyOnDeckHttpAugments(result, resolvedArgs);
+  await attachConsoleStatusToOnDeck(result);
+
+  const header = `# Next on deck — ${result.spec_id}
+
+**${result.title}** · status \`${result.status}\` · source \`${result.source_kind}\`
+${result.phase_name ? ` · phase **${result.phase_name}**` : ''}
+
+---
+
+`;
+
+  return {
+    description: `Next on deck: ${result.spec_id} — ${result.title}`,
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          // user_prompt_markdown is the post-HS-TASK-HSNX user-facing field;
+          // fall back to the @deprecated prompt_markdown alias for back-compat.
+          text: `${header}${result.user_prompt_markdown ?? result.prompt_markdown}\n\n---\n\n_Work this task next. Spec: \`${result.spec_path}\` · resolved ${result.resolved_at}_`,
+        },
+      },
+    ],
+  };
+}