heyspex 0.1.0

package/vendor/heyspex-mcp/capture-focus.mjs

@@ -0,0 +1,1366 @@
+/**
+ * Capture-on-deck — parallel pin to focus.yaml for epics.
+ * [[idea-capture-guardrails]] · MCP prompt `/hs-capture` (legacy alias: `/hs-idea`)
+ *
+ * Renamed from idea-focus.mjs by [[HS-TASK-SV2K-capture-rename-mcp-tools-and-slash-commands]].
+ * - Storage: `.heyspex/capture-focus.yaml` (legacy `.heyspex/idea-focus.yaml` auto-migrated on first load)
+ * - Bucket: `specs/captures/` writing `HS-CAP-*` ids with `type: capture` + `kind: idea`
+ * - Legacy `HS-IDEA-*` + `specs/captures/` paths still honored for read until [[HS-TASK-9HVY]] (E2)
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { mintFileKey, mintFamilyKey, parseSpecId } from './spec-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { scoreSufficiency, SUFFICIENCY_THRESHOLD } from '../../dev-factory/lib/sufficiency-score.mjs';
+
+export const CAPTURE_CORE_SOFT_MAX = 200;
+export const CAPTURE_CORE_HARD_MAX = 500;
+
+/** Word-based summary targets ([[HS-TASK-KR2S]]). */
+export const CAPTURE_SUMMARY_SOFT_WORDS = 150;
+export const CAPTURE_SUMMARY_HARD_WORDS = 250;
+/** Char hard-cap for storage safety (~250 words ≈ 1500 chars). */
+export const CAPTURE_SUMMARY_CHAR_HARD_MAX = 1500;
+
+/**
+ * Silent fuse for auto-created EMPTY capture scaffolds. An `ensureActiveCapturePin`
+ * auto-create (e.g. cli.mjs `/hs-capture` file-mode fallback when the console
+ * sessions API is unreachable) writes a bare scaffold file + pin. If the user
+ * never adds content, that pin would otherwise stay on deck forever — the
+ * HS-CAP-SID6 zombie. The pin carries `expires = now + CAPTURE_PIN_FUSE_MS`;
+ * `loadCaptureFocus` nulls it out once past, so an abandoned empty scaffold
+ * self-retires from on-deck. The fuse is dropped (see `clearCaptureFocusExpiry`)
+ * the instant real content lands, so a USED capture never expires. Only ever
+ * un-pins — the markdown file is left on disk, never deleted.
+ *
+ * 7 days mirrors the established epic-pin silent-fuse convention. Tunable here.
+ */
+export const CAPTURE_PIN_FUSE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Frontmatter statuses that mean a capture is no longer on deck. */
+const RETIRED_CAPTURE_STATUSES = new Set(['closed', 'superseded', 'abandoned', 'done']);
+
+/**
+ * [[HS-KFB2-6RGF-DIAG-capture-continuation-mints-a-new-orphan]]: a same-session
+ * follow-on to an idea that was JUST promoted should attach to that idea's
+ * lineage instead of minting a disconnected orphan. "Recently" is bounded by
+ * this window (checked against the retired capture's `updated:` timestamp) —
+ * generous enough to cover a working session, short enough that a follow-on
+ * days later (unrelated context) does not get force-linked to old research.
+ */
+export const RECENT_PROMOTION_LINEAGE_MS = 6 * 60 * 60 * 1000; // 6h
+
+/**
+ * v3 template — bare section headers, no scaffolding.
+ *
+ * Per [[HS-EPIC-Q1B7-idea-capture-modal-v3-single-textbox-cle]]: UI affordances
+ * (placeholders, helper copy) live in React; agent rules live in /hs-capture
+ * SKILL.md. Saved markdown bodies contain only saved data.
+ */
+export const CAPTURE_BODY_TEMPLATE = `# Core Idea
+
+## Summary
+
+## Notes
+`;
+
+export function captureFocusPath(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'capture-focus.yaml');
+}
+
+export function legacyIdeaFocusPath(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'idea-focus.yaml');
+}
+
+export function parseSimpleFocusYaml(raw) {
+  const state = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) continue;
+    const key = trimmed.slice(0, colon).trim();
+    let val = trimmed.slice(colon + 1).trim();
+    val = val.replace(/^["']|["']$/g, '');
+    state[key] = val;
+  }
+  return state;
+}
+
+/**
+ * One-shot migration: if `.heyspex/idea-focus.yaml` exists and the new
+ * `.heyspex/capture-focus.yaml` does not, rewrite legacy keys + paths and
+ * persist the new file. Idempotent — second call is a no-op.
+ *
+ * Mapping:
+ *   - `idea_spec_path:` → `capture_spec_path:`
+ *   - `idea_id:` → `capture_id:`
+ *   - `kind: idea` retained as `kind: idea` (kind field semantics unchanged)
+ *   - `specs/captures/HS-IDEA-…` in spec_path/idea_spec_path → `specs/captures/HS-CAP-…`
+ *
+ * Logs a one-line warning to stderr (visible in MCP server logs).
+ */
+export function migrateLegacyIdeaFocus(vaultRoot) {
+  const legacy = legacyIdeaFocusPath(vaultRoot);
+  const next = captureFocusPath(vaultRoot);
+  if (!existsSync(legacy)) return { migrated: false, reason: 'no_legacy_file' };
+  if (existsSync(next)) {
+    return { migrated: false, reason: 'new_file_already_present' };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(legacy, 'utf-8');
+  } catch (err) {
+    return { migrated: false, reason: 'read_failed', error: String(err) };
+  }
+
+  const state = parseSimpleFocusYaml(raw);
+  const remapPath = (p) =>
+    typeof p === 'string'
+      ? p.replace(/^specs\/ideas\//, 'specs/captures/').replace(/HS-IDEA-/g, 'HS-CAP-')
+      : p;
+
+  const remapId = (v) =>
+    typeof v === 'string' ? v.replace(/HS-IDEA-/g, 'HS-CAP-') : v;
+  const specPath = remapPath(state.spec_path || state.idea_spec_path || state.capture_spec_path || '');
+  const captureId = remapId(state.capture_id || state.idea_id || '');
+
+  const lines = [
+    '# HeySpex capture-on-deck — MCP /hs-capture ([[idea-capture-guardrails]])',
+    `kind: ${state.kind || 'idea'}`,
+  ];
+  if (specPath) lines.push(`spec_path: ${specPath}`);
+  if (captureId) lines.push(`capture_id: ${captureId}`);
+  lines.push(`pinned_at: ${state.pinned_at || new Date().toISOString()}`);
+  if (state.reason) lines.push(`reason: ${JSON.stringify(state.reason)}`);
+  if (state.expires) lines.push(`expires: ${state.expires}`);
+  if (state.claimed_by) lines.push(`claimed_by: ${JSON.stringify(state.claimed_by)}`);
+  if (state.claim_session) lines.push(`claim_session: ${JSON.stringify(state.claim_session)}`);
+
+  mkdirSync(join(vaultRoot, '.heyspex'), { recursive: true });
+  writeFileSync(next, `${lines.join('\n')}\n`, 'utf8');
+
+  try {
+    const stamped = `${legacy}.migrated-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    renameSync(legacy, stamped);
+    process.stderr.write?.(
+      `[heyspex-mcp] migrated ${legacy} → ${next}; backed up legacy file at ${stamped}\n`,
+    );
+  } catch {
+    process.stderr.write?.(
+      `[heyspex-mcp] migrated ${legacy} → ${next}; legacy file kept in place (rename failed)\n`,
+    );
+  }
+
+  return { migrated: true, from: legacy, to: next };
+}
+
+export function loadCaptureFocus(vaultRoot) {
+  migrateLegacyIdeaFocus(vaultRoot);
+  const p = captureFocusPath(vaultRoot);
+  if (!existsSync(p)) return null;
+  try {
+    const focus = parseSimpleFocusYaml(readFileSync(p, 'utf-8'));
+    if (focus.expires) {
+      const expiry = new Date(focus.expires);
+      if (expiry < new Date()) return null;
+    }
+    return focus;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCaptureFocus(vaultRoot, specPath, reason, claim, opts = {}) {
+  const dir = join(vaultRoot, '.heyspex');
+  mkdirSync(dir, { recursive: true });
+  // Mirror the pinned capture's frontmatter `kind:` into the pin so the on-deck
+  // pin reflects the real kind (idea | bug-fix | clip | reference | question |
+  // spec-import) rather than a hardcoded `idea`. Defaults to `idea` for the
+  // auto-created empty-scaffold path (a fresh capture is always kind: idea).
+  // See [[capture-guardrails]] §Capture-on-deck pin / §Import-origin kind.
+  const kind = typeof opts.kind === 'string' && opts.kind.trim() ? opts.kind.trim() : 'idea';
+  const lines = [
+    '# HeySpex capture-on-deck — MCP /hs-capture ([[idea-capture-guardrails]])',
+    `kind: ${kind}`,
+    `spec_path: ${specPath}`,
+    `pinned_at: ${new Date().toISOString()}`,
+  ];
+  if (reason) lines.push(`reason: ${JSON.stringify(reason)}`);
+  // Silent fuse for empty auto-created scaffolds — see CAPTURE_PIN_FUSE_MS.
+  if (opts.expires) lines.push(`expires: ${opts.expires}`);
+  if (claim?.claimed_by) lines.push(`claimed_by: ${JSON.stringify(claim.claimed_by)}`);
+  if (claim?.claim_session) lines.push(`claim_session: ${JSON.stringify(claim.claim_session)}`);
+  writeFileSync(captureFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+}
+
+/**
+ * Write an existing capture-focus pin again but with refreshed claim info.
+ * Preserves spec_path, reason, pinned_at. No-op if no pin file exists.
+ */
+export function updateCaptureFocusClaim(vaultRoot, claim) {
+  const focus = loadCaptureFocus(vaultRoot);
+  if (!focus?.spec_path) return false;
+  const dir = join(vaultRoot, '.heyspex');
+  mkdirSync(dir, { recursive: true });
+  const lines = [
+    '# HeySpex capture-on-deck — MCP /hs-capture ([[idea-capture-guardrails]])',
+    `kind: ${focus.kind || 'idea'}`,
+    `spec_path: ${focus.spec_path}`,
+    `pinned_at: ${focus.pinned_at || new Date().toISOString()}`,
+  ];
+  if (focus.reason) lines.push(`reason: ${JSON.stringify(focus.reason)}`);
+  // Preserve the empty-scaffold fuse across claim refreshes — dropping it here
+  // would let a still-empty auto-created capture become a permanent zombie. The
+  // fuse is cleared only when real content lands (clearCaptureFocusExpiry).
+  if (focus.expires) lines.push(`expires: ${focus.expires}`);
+  if (claim?.claimed_by) lines.push(`claimed_by: ${JSON.stringify(claim.claimed_by)}`);
+  if (claim?.claim_session) lines.push(`claim_session: ${JSON.stringify(claim.claim_session)}`);
+  writeFileSync(captureFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+  return true;
+}
+
+/**
+ * Drop the `expires` fuse from the current pin once a capture has real content.
+ * An auto-created empty scaffold carries a fuse so it self-retires from on-deck
+ * if abandoned (the HS-CAP-SID6 zombie); the moment the user adds content the capture is
+ * "real" and must never expire. Rewrites the pin preserving every other field.
+ *
+ * No-op (returns false) if there is no pin, the pin already has no fuse, or it
+ * has already expired (loadCaptureFocus returns null past expiry).
+ */
+export function clearCaptureFocusExpiry(vaultRoot) {
+  const focus = loadCaptureFocus(vaultRoot);
+  if (!focus?.spec_path || !focus.expires) return false;
+  const lines = [
+    '# HeySpex capture-on-deck — MCP /hs-capture ([[idea-capture-guardrails]])',
+    `kind: ${focus.kind || 'idea'}`,
+    `spec_path: ${focus.spec_path}`,
+    `pinned_at: ${focus.pinned_at || new Date().toISOString()}`,
+  ];
+  if (focus.reason) lines.push(`reason: ${JSON.stringify(focus.reason)}`);
+  if (focus.claimed_by) lines.push(`claimed_by: ${JSON.stringify(focus.claimed_by)}`);
+  if (focus.claim_session) lines.push(`claim_session: ${JSON.stringify(focus.claim_session)}`);
+  writeFileSync(captureFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+  return true;
+}
+
+const CAPTURE_ID_PREFIXES = ['HS-CAP-', 'HS-IDEA-'];
+
+export function findCaptureSpecFile(vaultRoot, specId) {
+  const wanted = String(specId || '').trim();
+  if (!wanted) return null;
+
+  for (const [dir, prefixGuard] of [
+    ['captures', 'HS-CAP-'],
+    ['ideas', 'HS-IDEA-'],
+  ]) {
+    const root = join(vaultRoot, 'specs', dir);
+    if (!existsSync(root)) continue;
+    const direct = join('specs', dir, `${wanted}.md`);
+    if (existsSync(join(vaultRoot, direct))) return direct;
+    try {
+      for (const file of readdirSync(root)) {
+        if (!file.endsWith('.md')) continue;
+        if (file.startsWith(wanted)) return join('specs', dir, file);
+        if (!CAPTURE_ID_PREFIXES.some((p) => wanted.startsWith(p))) continue;
+        const full = join(root, file);
+        const content = readFileSync(full, 'utf-8');
+        const idLine = content.match(/^id:\s*([A-Z0-9-]+)/m);
+        const legacyLine = content.match(/^legacy_idea_id:\s*([A-Z0-9-]+)/m);
+        if (idLine && idLine[1] === wanted) return join('specs', dir, file);
+        if (legacyLine && legacyLine[1] === wanted) return join('specs', dir, file);
+      }
+    } catch {
+      /* ignore and try next bucket */
+    }
+    void prefixGuard;
+  }
+  return null;
+}
+
+const NOTES_SECTION_RE = /^##\s*Notes\b/im;
+
+/** Summary brief — word-based soft/hard + char storage cap ([[HS-TASK-KR2S]]). */
+export const CAPTURE_SUMMARY_SOFT_MAX = CAPTURE_SUMMARY_SOFT_WORDS;
+export const CAPTURE_SUMMARY_HARD_MAX = CAPTURE_SUMMARY_HARD_WORDS;
+
+/** @deprecated renamed to CAPTURE_SUMMARY_SOFT_WORDS (HS-EPIC-OED2 → HS-TASK-KR2S). */
+export const CAPTURE_CONCEPT_SOFT_MAX = CAPTURE_SUMMARY_SOFT_WORDS;
+/** @deprecated renamed to CAPTURE_SUMMARY_HARD_WORDS (HS-EPIC-OED2 → HS-TASK-KR2S). */
+export const CAPTURE_CONCEPT_HARD_MAX = CAPTURE_SUMMARY_HARD_WORDS;
+
+function countWords(text) {
+  const trimmed = String(text ?? '').trim();
+  if (!trimmed) return 0;
+  return trimmed.split(/\s+/).length;
+}
+
+/** Heading text for the agent's deep-dive section (replaces the legacy <details>Details block). */
+export const CAPTURE_EXPANDED_CONCEPT_HEADING = 'Expanded Concept';
+
+/** @deprecated v2 <details> summary text — kept only for back-compat reads. */
+export const CAPTURE_DETAILS_SUMMARY = 'Details';
+
+/** Legacy summary text (kept for back-compat reads). */
+export const EXPANDED_IDEA_SUMMARY = 'Expanded idea (agent)';
+
+// Legacy back-compat read matcher: the pre-OED2 deep-dive lived in a
+// `<details><summary>Details</summary>…</details>` block. New writes use a
+// `## Expanded Concept` markdown section; this regex only recognizes the old
+// form on read. Prefix-match on the summary so customized legacy summaries
+// (e.g. "Expanded idea (agent) — full workflow spec" in HS-CAP-9PKD) still parse.
+const DETAILS_BLOCK_RE =
+  /<details>\s*\n<summary>\s*(?:Details|Expanded idea \(agent\))[^<\n]*<\/summary>[\s\S]*?<\/details>/i;
+
+/** Back-compat alias — older callers reference this name. */
+export const EXPANDED_IDEA_DETAILS_RE = DETAILS_BLOCK_RE;
+
+/**
+ * Read the agent deep-dive. Prefers the new `## Expanded Concept` markdown
+ * section; falls back to the legacy `<details>Details</details>` block.
+ */
+export function extractAgentExpansionFromBody(body) {
+  const normalized = body.replace(/\r\n/g, '\n');
+  const section = normalized.match(
+    /##[ \t]*Expanded[ \t]+Concept[ \t]*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/i,
+  );
+  if (section) return stripLeadingHtmlComments(section[1]);
+  const m = normalized.match(DETAILS_BLOCK_RE);
+  if (!m) return '';
+  const inner = m[0].match(/<summary>[\s\S]*?<\/summary>\s*\n+([\s\S]*?)<\/details>/i);
+  return inner?.[1]?.trim() ?? '';
+}
+
+/** Read the `## Expanded Concept` deep-dive (alias of extractAgentExpansionFromBody). */
+export const extractCaptureExpandedConceptFromBody = extractAgentExpansionFromBody;
+
+/** @deprecated renamed to extractCaptureExpandedConceptFromBody (HS-EPIC-OED2). */
+export const extractCaptureDetailsFromBody = extractAgentExpansionFromBody;
+
+/** Build the `## Expanded Concept` section (replaces the legacy <details> block). */
+export function buildAgentExpansionBlock(content) {
+  let inner = String(content ?? '').trim();
+  if (!inner) return '';
+  // Legacy callers may hand us a raw <details> blob — unwrap to inner content.
+  if (/<details>/i.test(inner)) {
+    inner = extractAgentExpansionFromBody(inner) || inner;
+  }
+  return `\n## ${CAPTURE_EXPANDED_CONCEPT_HEADING}\n\n${inner}\n`;
+}
+
+export function stripAgentExpansionFromBody(body) {
+  return body.replace(/\r\n/g, '\n').replace(DETAILS_BLOCK_RE, '').trimEnd();
+}
+
+function stripLeadingHtmlComments(text) {
+  return text.replace(/^(?:\s*<!--[\s\S]*?-->\s*\n+)+/, '').trim();
+}
+
+export function extractCaptureCoreFromBody(body) {
+  const normalized = body.replace(/\r\n/g, '\n');
+  // Use `[ \t]*\n` (non-newline whitespace + single newline) so empty sections —
+  // bare headers with no body content — match correctly. The original `\s*\n+`
+  // form was effectively `\n+` because `\s` already matches `\n`, so it would
+  // swallow the blank line between `# Core Idea` and `## Notes`, leaving no `\n`
+  // for the `(?=\n##\s)` lookahead and forcing the capture to absorb the next
+  // heading. See [[HS-TASK-Z9KG-a1-strip-body-templates-console-mcp]].
+  const coreMatch = normalized.match(
+    /#[ \t]*Core[ \t]+[Ii]dea[ \t]*\n([\s\S]*?)(?=\n##\s|\n#\s|$)/,
+  );
+  if (coreMatch) return coreMatch[1].trim();
+  const beforeNotes = normalized.split(NOTES_SECTION_RE)[0] ?? normalized;
+  return beforeNotes.replace(/^#\s+[^\n]+\n+/m, '').trim();
+}
+
+export function extractCaptureNotesFromBody(body) {
+  const withoutDetails = stripAgentExpansionFromBody(body);
+  const m = withoutDetails.match(/##[ \t]*Notes[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i);
+  return m ? stripLeadingHtmlComments(m[1]) : '';
+}
+
+/** Reads the `## Summary` section (legacy `## Concept` honored on read). */
+export function extractCaptureSummaryFromBody(body) {
+  const withoutDetails = stripAgentExpansionFromBody(body);
+  const m =
+    withoutDetails.match(/##[ \t]*Summary[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i) ??
+    withoutDetails.match(/##[ \t]*Concept[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i);
+  return m ? stripLeadingHtmlComments(m[1]) : '';
+}
+
+/** @deprecated renamed to extractCaptureSummaryFromBody (HS-EPIC-OED2). */
+export const extractCaptureConceptFromBody = extractCaptureSummaryFromBody;
+
+/**
+ * Reads the `## Example` section — a real verbatim example (labeled as such) or an
+ * AI-authored illustrative one. Slots between Notes and Expanded Concept, so the
+ * `(?=\n##\s|$)` lookahead stops it cleanly at `## Expanded Concept`. Mirrors the
+ * console reader so an MCP update preserves Example instead of dropping it on
+ * rebuild (extract-then-rebuild — [[HS-PR20-EPIC]]).
+ */
+export function extractCaptureExampleFromBody(body) {
+  const normalized = body.replace(/\r\n/g, '\n');
+  const m = normalized.match(/##[ \t]*Example[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i);
+  return m ? stripLeadingHtmlComments(m[1]) : '';
+}
+
+/**
+ * Reads the `## User Stories` section — "As a …, I want …, so that …" statements or
+ * free-form user-goal lines. Slots between Example and Expanded Concept. Mirrors the
+ * console reader so an MCP update preserves User Stories instead of dropping it on
+ * rebuild (owner directive 2026-07-10; entity-type design stays [[HS-USTY-EPIC]]).
+ */
+export function extractCaptureUserStoriesFromBody(body) {
+  const normalized = body.replace(/\r\n/g, '\n');
+  const m = normalized.match(/##[ \t]*User[ \t]+Stories[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i);
+  return m ? stripLeadingHtmlComments(m[1]) : '';
+}
+
+/**
+ * Reads the `## Done When` checklist — how the idea will be verified done. Slots
+ * between User Stories and Expanded Concept (mirrors the console materializer).
+ * The heyspex_update_capture schema has promised a `done_when` arg since the
+ * HS-NR43 gate remediation pointed at it; this reader (plus the writer wiring in
+ * executeUpdateCapture / buildCaptureBody) is what actually persists it —
+ * [[HS-AYCX-T9T6-TASK-grounding-time-sufficiency-check]].
+ */
+export function extractCaptureDoneWhenFromBody(body) {
+  const normalized = body.replace(/\r\n/g, '\n');
+  const m = normalized.match(/##[ \t]*Done[ \t]+When[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i);
+  return m ? stripLeadingHtmlComments(m[1]) : '';
+}
+
+/**
+ * Reads the `## JTBD (job-to-be-done)` section — the underlying job the user is
+ * trying to get done, authored by the `/hs-capture` enhancement pass. Slots
+ * between User Stories and Done When (mirrors the console reader/materializer).
+ * Replaces the interim `JTBD (job-to-be-done):` leading block inside
+ * `## Expanded Concept` per the 2026-08-23 owner ruling —
+ * [[HS-TIE7-PR20-TASK-jtbd-job-to-be-done-field-on-captures]] /
+ * [[research-capture-protocol]] §"JTBD (job-to-be-done) framing".
+ */
+export function extractCaptureJtbdFromBody(body) {
+  const normalized = body.replace(/\r\n/g, '\n');
+  const m = normalized.match(
+    /##[ \t]*JTBD[ \t]*\(job-to-be-done\)[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i,
+  );
+  return m ? stripLeadingHtmlComments(m[1]) : '';
+}
+
+const SOURCE_FENCE_RE = /```source\b[^\n]*\n([\s\S]*?)\n```/i;
+
+/**
+ * Reads the verbatim content of `## Source Material` — the inner ```source fence
+ * (captured external article/transcript/clipboard), or the raw section text when
+ * the fence is missing (hand-authored captures). Mirrors the console reader so an
+ * MCP update preserves Source Material instead of dropping it on rebuild.
+ */
+export function extractSourceMaterialFromBody(body) {
+  const withoutDetails = stripAgentExpansionFromBody(body);
+  const section = withoutDetails.match(
+    /##[ \t]*Source[ \t]+Material[ \t]*\n([\s\S]*?)(?=\n##\s|$)/i,
+  );
+  if (!section) return '';
+  const fence = section[1].match(SOURCE_FENCE_RE);
+  return fence ? fence[1] : stripLeadingHtmlComments(section[1]);
+}
+
+/**
+ * Build the capture body in summaries-first order:
+ * **Core Idea → Summary → Notes → Example → User Stories → JTBD → Done When →
+ * Expanded Concept → Source Material**. Byte-identical to the console
+ * `buildIdeaBody`.
+ *
+ * Legacy 3-arg signature `(core, notes, agentExpansion)` still works: when the
+ * 3rd arg looks like a `<details>` blob, it is routed to the Expanded Concept
+ * slot and Summary is left empty. `example` / `userStories` / `doneWhen` /
+ * `jtbd` are trailing params so legacy positional calls are unaffected.
+ */
+export function buildCaptureBody(
+  core,
+  notes = '',
+  summaryOrAgentExpansion = '',
+  agentExpansion = '',
+  sourceMaterial = '',
+  example = '',
+  userStories = '',
+  doneWhen = '',
+  jtbd = '',
+) {
+  const looksLikeDetails =
+    typeof summaryOrAgentExpansion === 'string' && /<details>/i.test(summaryOrAgentExpansion);
+  const summary = looksLikeDetails ? '' : summaryOrAgentExpansion;
+  const expandedContent = looksLikeDetails ? summaryOrAgentExpansion : agentExpansion;
+
+  const coreTrim = String(core ?? '').trim();
+  const notesTrim = String(notes ?? '').trim();
+  const summaryTrim = String(summary ?? '').trim();
+  const exampleTrim = String(example ?? '').trim();
+  // Source material preserves internal whitespace verbatim — trim only outer newlines.
+  const sourceTrim = String(sourceMaterial ?? '')
+    .replace(/\r\n/g, '\n')
+    .replace(/^\n+|\n+$/g, '');
+
+  // Empty core → bare `# Core Idea` header with no body. Parallel to the
+  // console `buildIdeaBody` fix in [[HS-TASK-4XAN]] — the italic
+  // `_Refine via /hs-capture_` placeholder forced fresh raw captures to
+  // look expanded to the [[HS-TASK-P2WA]] B3 save-time linter.
+  let out = '# Core Idea\n';
+  if (coreTrim) out += `\n${coreTrim}\n`;
+  out += '\n## Summary\n';
+  if (summaryTrim) out += `\n${summaryTrim}\n`;
+  out += '\n## Notes\n';
+  if (notesTrim) out += `\n${notesTrim}\n`;
+
+  // Example — conditional (like Expanded Concept/Source Material): emit the
+  // header only when populated so existing captures don't gain an empty header
+  // on save. A real verbatim example (labeled real) or an AI-authored
+  // illustrative one (labeled as such); the "always populated" intent is an
+  // expand-time authoring rule, not an always-present empty header.
+  if (exampleTrim) out += `\n## Example\n\n${exampleTrim}\n`;
+
+  // User Stories — conditional (same rule as Example); slots between Example and
+  // Expanded Concept. Mirrors the console buildIdeaBody.
+  const userStoriesTrim = String(userStories ?? '').trim();
+  if (userStoriesTrim) out += `\n## User Stories\n\n${userStoriesTrim}\n`;
+
+  // JTBD (job-to-be-done) — conditional (same rule as Example/User Stories);
+  // slots between User Stories and Done When. Authored by the /hs-capture
+  // enhancement pass — replaces the interim Expanded-Concept-leading-block
+  // convention (owner ruling 2026-08-23) — [[HS-TIE7-PR20-TASK]].
+  const jtbdTrim = String(jtbd ?? '').trim();
+  if (jtbdTrim) out += `\n## JTBD (job-to-be-done)\n\n${jtbdTrim}\n`;
+
+  // Done When — conditional; slots between User Stories and Expanded Concept
+  // (mirrors the console materializer). The sufficiency scorer's done-criteria
+  // element reads this section.
+  const doneWhenTrim = String(doneWhen ?? '').trim();
+  if (doneWhenTrim) out += `\n## Done When\n\n${doneWhenTrim}\n`;
+
+  // Expanded Concept — conditional (opt-in deep dive); unwraps any legacy <details> blob.
+  const expandedBlock = buildAgentExpansionBlock(expandedContent);
+  if (expandedBlock) out += expandedBlock.startsWith('\n') ? expandedBlock : `\n${expandedBlock}`;
+
+  // Source Material — conditional, LAST.
+  if (sourceTrim) {
+    out += `\n## Source Material\n\n\`\`\`source\n${sourceTrim}\n\`\`\`\n`;
+  }
+  return out;
+}
+
+export function validateSummaryLength(summary) {
+  const trimmed = String(summary ?? '').trim();
+  const len = trimmed.length;
+  const words = countWords(trimmed);
+  if (len === 0) return { ok: true, summaryLength: 0, summaryWordCount: 0 };
+  if (len > CAPTURE_SUMMARY_CHAR_HARD_MAX) {
+    return {
+      ok: false,
+      summaryLength: len,
+      summaryWordCount: words,
+      error: `Summary is ${len} chars (max ${CAPTURE_SUMMARY_CHAR_HARD_MAX}). The Summary is a brief paragraph — trim or move depth into Expanded Concept.`,
+    };
+  }
+  if (words > CAPTURE_SUMMARY_HARD_WORDS) {
+    return {
+      ok: false,
+      summaryLength: len,
+      summaryWordCount: words,
+      error: `Summary is ${words} words (max ${CAPTURE_SUMMARY_HARD_WORDS}). The Summary is a brief paragraph — trim or move depth into Expanded Concept.`,
+    };
+  }
+  const warning =
+    words > CAPTURE_SUMMARY_SOFT_WORDS
+      ? `Summary is ${words} words — aim for ≤${CAPTURE_SUMMARY_SOFT_WORDS} (one paragraph). Depth belongs in Expanded Concept.`
+      : undefined;
+  return { ok: true, summaryLength: len, summaryWordCount: words, warning };
+}
+
+/** @deprecated renamed to validateSummaryLength (HS-EPIC-OED2). */
+export const validateConceptLength = validateSummaryLength;
+
+export function formatUserNoteEntry(iso, role, text) {
+  const clean = text.trim().replace(/\n+/g, ' ');
+  const label = role === 'user' ? 'you' : role;
+  return `- **${iso} · ${label}:** "${clean}"`;
+}
+
+export function appendCaptureNote(existingNotes, entry) {
+  const base = existingNotes.trim();
+  if (!base || base.startsWith('_')) {
+    return `${entry}\n`;
+  }
+  return `${base}\n${entry}\n`;
+}
+
+export function validateCaptureCore(core) {
+  const len = core.trim().length;
+  if (len === 0) {
+    return { ok: false, error: 'Core idea cannot be empty.' };
+  }
+  if (len > CAPTURE_CORE_HARD_MAX) {
+    return {
+      ok: false,
+      error: `Core idea is ${len} chars (max ${CAPTURE_CORE_HARD_MAX}). Shorten while keeping the user's phrasing.`,
+    };
+  }
+  const warning =
+    len > CAPTURE_CORE_SOFT_MAX
+      ? `Core idea is ${len} chars — aim for ≤${CAPTURE_CORE_SOFT_MAX}. Prefer the user's own words.`
+      : undefined;
+  return { ok: true, warning };
+}
+
+export function stringifyCaptureSpec(frontmatter, body) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(frontmatter)) {
+    if (v === null || v === undefined) continue;
+    if (Array.isArray(v)) {
+      lines.push(`${k}:`);
+      for (const item of v) lines.push(`  - ${JSON.stringify(item)}`);
+    } else if (typeof v === 'string') {
+      lines.push(`${k}: ${yamlScalar(v)}`);
+    } else {
+      lines.push(`${k}: ${v}`);
+    }
+  }
+  lines.push('---', '', body.trim(), '');
+  return lines.join('\n');
+}
+
+export function resolveAgentClaim() {
+  const claudeSession = process.env.CLAUDE_SESSION_ID?.trim();
+  if (claudeSession) {
+    return { claimed_by: 'Claude Code', claim_session: claudeSession };
+  }
+  const cursorSession =
+    process.env.CURSOR_TRACE_ID?.trim() ||
+    process.env.CURSOR_SESSION_ID?.trim() ||
+    process.env.COMPOSER_SESSION_ID?.trim();
+  if (cursorSession) {
+    return { claimed_by: 'Cursor', claim_session: cursorSession };
+  }
+  const explicitAgent = process.env.HEYSPEX_AGENT?.trim();
+  const explicitSession =
+    process.env.HEYSPEX_SESSION_ID?.trim() || process.env.HEYSPEX_AGENT_SESSION?.trim();
+  if (explicitAgent || explicitSession) {
+    return {
+      claimed_by: explicitAgent || 'External agent',
+      claim_session: explicitSession || `mcp-${process.pid}`,
+    };
+  }
+  return { claimed_by: 'External agent', claim_session: `mcp-${process.pid}` };
+}
+
+/**
+ * Ensure a valid capture pin exists. Auto-creates a fresh HS-CAP-* when none is
+ * pinned or the pin points at a missing file. Used by /hs-capture,
+ * heyspex_active_capture, and heyspex_update_capture so agents can capture
+ * without console pre-setup.
+ */
+export function ensureActiveCapturePin(vaultRoot, parseFrontmatter, loadSpec, deps = {}) {
+  const {
+    allocateRandomVaultId,
+    occupiedCaptureIds,
+    pinReason = 'Auto-created via MCP',
+    claim = null,
+  } = deps;
+
+  let previousError = null;
+  let resolved = resolveActiveCapture(vaultRoot, parseFrontmatter, loadSpec);
+  if (!resolved.error) {
+    if (claim) updateCaptureFocusClaim(vaultRoot, claim);
+    return { resolved, fresh: false, auto_created: false };
+  }
+
+  previousError = resolved.error;
+  const recoverable =
+    resolved.error === 'NO_CAPTURE_PINNED' ||
+    resolved.error === 'CAPTURE_NOT_FOUND' ||
+    resolved.error === 'CAPTURE_RETIRED';
+  if (!recoverable) {
+    return { error: resolved.error, message: resolved.message };
+  }
+  if (!allocateRandomVaultId || !occupiedCaptureIds) {
+    return {
+      error: 'AUTO_CREATE_UNAVAILABLE',
+      message: 'Cannot auto-create capture spec without vault ID allocator.',
+    };
+  }
+
+  // HS-KFB2: when the capture being replaced was RECENTLY PROMOTED (not
+  // closed/superseded/abandoned), carry its lineage into the fresh capture
+  // instead of minting a disconnected orphan — this is exactly the "follow-on
+  // to an already-promoted idea" repro from the diagnose.
+  const lineage =
+    resolved.recentlyPromoted && resolved.promotedTo
+      ? { promotedTo: resolved.promotedTo, retiredCaptureBasename: resolved.retiredCaptureBasename }
+      : null;
+
+  const created = createFreshCaptureSpec(vaultRoot, allocateRandomVaultId, occupiedCaptureIds, lineage);
+  // Stamp the silent fuse: a freshly auto-created scaffold is empty, so it must
+  // self-retire from on-deck if the user never adds content (the SID6 fix). The
+  // fuse is dropped the moment real content lands (executeUpdateCapture →
+  // clearCaptureFocusExpiry).
+  const expires = new Date(Date.now() + CAPTURE_PIN_FUSE_MS).toISOString();
+  writeCaptureFocus(vaultRoot, created.spec_path, pinReason, claim, { expires });
+  resolved = resolveActiveCapture(vaultRoot, parseFrontmatter, loadSpec);
+  if (resolved.error) {
+    return {
+      error: resolved.error,
+      message: resolved.message || 'Auto-create failed after pin write.',
+    };
+  }
+  return {
+    resolved,
+    fresh: true,
+    auto_created: true,
+    replaced_stale_pin: previousError === 'CAPTURE_NOT_FOUND',
+    // HS-KFB2: surfaced so the calling tool/prompt can tell the agent this new
+    // capture continues a just-promoted idea — e.g. "consider whether this
+    // belongs appended to <continuation_of> instead of/alongside a new capture"
+    // (suggest, never auto-apply — [[HS-5HYS]] elicitation).
+    ...(created.continuation_of ? { continuation_of: created.continuation_of } : {}),
+  };
+}
+
+/**
+ * Missing-element key (scorer vocabulary) → the heyspex_update_capture argument
+ * that fills it. Mirrors the promote-time gate's how_to_resolve mapping
+ * (promote-capture.mjs §1b) so grounding-time and promote-time remediation
+ * never disagree.
+ */
+export const SUFFICIENCY_MISSING_TO_UPDATE_ARG = {
+  'core-idea': 'core_idea',
+  example: 'example',
+  'done-criteria': 'done_when',
+  kind: 'kind',
+  'user-stories': 'user_stories',
+};
+
+/**
+ * Grounding-time sufficiency verdict ([[HS-AYCX-T9T6-TASK-grounding-time-sufficiency-check]]):
+ * the SAME scorer and inputs the promote-time gate uses (promote-capture.mjs §1b,
+ * [[HS-0CFX-TASK]]), including the already-expanded bypass ([[HS-55YM-DIAG]]) —
+ * a populated `## Expanded Concept` means the gate would skip scoring, so it is
+ * reported here as a pass with the bypass named instead of re-scoring content
+ * the gate would never score. Never throws; a scorer error reports as fail with
+ * a `*scorer-error*` marker, matching the gate.
+ */
+export function computeCaptureSufficiency(frontmatter, body) {
+  const bodyText = String(body ?? '');
+  if (extractAgentExpansionFromBody(bodyText).trim().length > 0) {
+    return {
+      pass: true,
+      bypass: 'already-expanded',
+      score: 1,
+      threshold: SUFFICIENCY_THRESHOLD,
+      missing: [],
+    };
+  }
+  let suff;
+  try {
+    suff = scoreSufficiency({ frontmatter: { kind: frontmatter?.kind ?? undefined }, body: bodyText });
+  } catch {
+    suff = { pass: false, score: 0, missing: ['*scorer-error*'] };
+  }
+  const missing = Array.isArray(suff?.missing) ? suff.missing : [];
+  const verdict = {
+    pass: suff?.pass === true,
+    score: suff?.score ?? 0,
+    threshold: SUFFICIENCY_THRESHOLD,
+    missing,
+  };
+  if (!verdict.pass) {
+    verdict.remediation = missing
+      .map((key) => `${key} → ${SUFFICIENCY_MISSING_TO_UPDATE_ARG[key] ?? key}`)
+      .join(', ');
+    verdict.guidance =
+      'This capture would NOT yet pass the promote sufficiency gate. Elicit the missing elements from the user in THIS pass and write them via heyspex_update_capture (same spec_id): ' +
+      verdict.remediation +
+      '. Do not offer "promote to research" until the capture passes and the owner confirms satisfaction — never invent content to pass the gate.';
+  }
+  return verdict;
+}
+
+/**
+ * @param {string} vaultRoot
+ * @param {Function} parseFrontmatter
+ * @param {Function} loadSpec
+ * @param {object|null} [focusOverride] The capture-on-deck pin to resolve against.
+ *   Pass the LIVE pin here. The pin moved to the Neon control plane
+ *   (`capture_focus_pin` + `capture_focus_selection`, read by
+ *   `readCaptureFocusVendor`); the on-disk `.heyspex/capture-focus.yaml` is now
+ *   only the offline fallback, written when the console is unreachable. A caller
+ *   that lets this default to the file read gets whatever the last offline
+ *   capture left behind — on this repo that was a June pin, already promoted, so
+ *   every resolve returned CAPTURE_RETIRED and every gate built on it allowed
+ *   everything. Omit ONLY when there is genuinely no console to ask.
+ */
+export function resolveActiveCapture(vaultRoot, parseFrontmatter, loadSpec, focusOverride) {
+  const focus = focusOverride === undefined ? loadCaptureFocus(vaultRoot) : focusOverride;
+  if (!focus?.spec_path) {
+    return {
+      error: 'NO_CAPTURE_PINNED',
+      message:
+        'No capture on deck. Run /hs-capture or heyspex_update_capture to auto-create, use console + New → Capture, or call heyspex_pin_capture.',
+    };
+  }
+  const spec = loadSpec(vaultRoot, focus.spec_path);
+  if (!spec) {
+    return { error: 'CAPTURE_NOT_FOUND', message: `Pinned capture missing: ${focus.spec_path}` };
+  }
+  // Done-status gate: a pinned capture that has been closed/superseded/abandoned
+  // or promoted to another spec is no longer on deck. Returning a recoverable
+  // error lets ensureActiveCapturePin advance to a fresh capture instead of
+  // resurfacing a dead one indefinitely (the materialize re-pin → stuck-pin loop).
+  const status = String(spec.frontmatter?.status ?? '').trim().toLowerCase();
+  const promotedTo = String(spec.frontmatter?.promoted_to ?? '').trim();
+  const isPromoted = promotedTo !== '' && promotedTo !== 'null';
+  if (RETIRED_CAPTURE_STATUSES.has(status) || isPromoted) {
+    // Lineage carry-over (HS-KFB2): when retirement is because the capture was
+    // PROMOTED (not closed/superseded/abandoned), surface enough for the caller
+    // to attach a same-session follow-on to that idea's lineage instead of
+    // silently minting an orphan. `recentlyPromoted` bounds this to a real
+    // continuation, not a stale capture resurfacing weeks later.
+    const updatedAt = Date.parse(String(spec.frontmatter?.updated ?? ''));
+    const recentlyPromoted =
+      isPromoted && Number.isFinite(updatedAt) && Date.now() - updatedAt < RECENT_PROMOTION_LINEAGE_MS;
+    return {
+      error: 'CAPTURE_RETIRED',
+      message: `Pinned capture ${focus.spec_path} is ${
+        isPromoted ? `promoted to ${promotedTo}` : status
+      } — no longer on deck.`,
+      ...(isPromoted
+        ? {
+            promotedTo,
+            recentlyPromoted,
+            retiredCaptureId: spec.frontmatter?.id ?? null,
+            retiredCaptureBasename: focus.spec_path.replace(/^.*[\\/]/, '').replace(/\.md$/, ''),
+          }
+        : {}),
+    };
+  }
+  const id = spec.frontmatter?.id;
+  const core = extractCaptureCoreFromBody(spec.body);
+  const notes = extractCaptureNotesFromBody(spec.body);
+  return {
+    focus,
+    spec_path: focus.spec_path,
+    spec_id: id,
+    name: spec.frontmatter?.name,
+    status: spec.frontmatter?.status,
+    core_idea: core,
+    notes,
+    body: spec.body,
+    frontmatter: spec.frontmatter,
+    // Grounding-time sufficiency ([[HS-AYCX-T9T6-TASK-grounding-time-sufficiency-check]]):
+    // every active-capture read carries the promote gate's verdict so the agent
+    // elicits missing elements now instead of discovering them at promote time.
+    sufficiency: computeCaptureSufficiency(spec.frontmatter, spec.body),
+  };
+}
+
+export function buildHsCapturePromptMarkdown(resolved, options = {}) {
+  const { spec_id, name, core_idea, notes, spec_path } = resolved;
+  const notesBlock = notes.trim() ? notes : '_No notes yet._';
+  const isFresh = options.fresh === true;
+  // Grounding-time offer gate ([[HS-YPZA-T9T6-TASK-gate-the-promote-to-research-offer-on]]):
+  // the promote move is presented as LIVE only when the capture would pass the
+  // promote sufficiency gate. Owner intent (HS-3WON, verbatim): "I shouldn't
+  // have been prompted to do research if the sufficiency gate hasn't been
+  // passed." An explicit owner instruction to promote anyway still works — the
+  // gate governs what the SYSTEM offers, never what the owner may command.
+  const sufficiency =
+    resolved.sufficiency ?? computeCaptureSufficiency(resolved.frontmatter, resolved.body ?? '');
+  const sufficiencyPasses = sufficiency?.pass === true;
+  const missingList = (sufficiency?.missing ?? [])
+    .map((key) => `\`${key}\` (→ \`${SUFFICIENCY_MISSING_TO_UPDATE_ARG[key] ?? key}\`)`)
+    .join(', ');
+  const promoteMoveLine = sufficiencyPasses
+    ? `**promote to research** (\`heyspex_promote_capture\`; \`heyspex_promote_capture_to_diagnose\` for \`kind: bug-fix\`) — offer it ONLY after showing the enhanced capture and the owner confirms they are satisfied with it`
+    : `**enhance to readiness** — the capture would NOT yet pass the promote sufficiency gate (missing: ${missingList || 'nothing recorded'}); elicit those from the user and write them via \`heyspex_update_capture\`, and do NOT present promote as a live option until it passes (the owner may still explicitly instruct you to promote anyway)`;
+  // [[HS-PG9I-TASK]] — resume branch: when a re-opened capture already carries a
+  // Core Idea + Summary, tell the agent this is a RESUME (offer iterate / the
+  // gated second move), not a fresh brain-offload. Owner ruling 2026-07-11:
+  // grounding and expanding are the same act — the Expanded Concept is
+  // auto-written whenever the agent grounds, with no user confirmation, so
+  // "expand" is never a resume move to offer.
+  const isResume = options.resume === true;
+  const freshHeader = isFresh
+    ? `_Auto-created \`${spec_id}\` — no prior content. The user's next message will be the first capture._\n\n`
+    : isResume
+      ? `> **Resume — this capture already has a Core Idea + Summary.** Do **not** re-capture from scratch. ` +
+        `Greet the user with what's already here, then offer the two resume moves: ` +
+        `**iterate** (refine Core Idea / Summary / Notes with new input, still verbatim in Notes) ` +
+        `or ${promoteMoveLine}. ` +
+        `Any new words the user types are still captured verbatim into \`## Notes\`. If you ground the idea further, that grounding output is the Expanded Concept — write it to \`agent_expansion\` automatically, no confirmation. There is no separate expand skill and no "want me to expand?" offer — expansion happens automatically whenever you ground._\n\n`
+      : '';
+  const sufficiencySection = sufficiencyPasses
+    ? sufficiency?.bypass === 'already-expanded'
+      ? '_Passes (already expanded — the promote gate skips scoring once `## Expanded Concept` is populated)._'
+      : '_Passes — promote may be offered once the owner confirms satisfaction with the enhanced capture._'
+    : `**Not yet ready** — would bounce at promote. Missing: ${missingList || '_none recorded_'}. Elicit these from the user in this pass and write them via \`heyspex_update_capture\` — never invent content to pass the gate.`;
+
+  const summaryBlock = extractCaptureSummaryFromBody(resolved.body ?? '');
+  const summarySection = summaryBlock.trim()
+    ? summaryBlock
+    : '_No Summary saved yet._';
+
+  const expandedBlock = extractCaptureExpandedConceptFromBody(resolved.body ?? '');
+  const expandedSection = expandedBlock
+    ? `_Expanded Concept saved._\n\n${expandedBlock}`
+    : '_No Expanded Concept deep-dive saved yet._';
+
+  return `# Capture on deck — ${spec_id}
+
+**${name || spec_id}** · \`${spec_path}\`
+
+${freshHeader}## Your job — brain-offload capture (not epic/task filing)
+
+Works **with or without** a console-pinned capture — auto-creates \`HS-CAP-*\` when none is on deck. Doc order (summaries-first): **# Core Idea** → **## Summary** (brief) → **## Notes** (verbatim) → **## Example** (real or AI-illustrative, labeled) → **## Expanded Concept** (auto-written on grounding) → **## Source Material** ([[HS-EPIC-OED2-capture-model-rewrite-summaries-first-st]]).
+
+**Identity:** you are the user's **technical co-founder** — peer-level, honest, knows the codebase and roadmap. Push back when warranted. Keep grounding light and accurate. Anything needing deep verification gets flagged for promote-to-research — **never chased inline**.
+
+### Beat 1 — Capture every turn (confirm-free)
+
+Every message the user sends — **including their answers to your own questions** — must be captured verbatim immediately:
+
+1. **Read the current doc first** (below). Never alter words inside an existing quote.
+2. Call \`heyspex_update_capture\` with \`user_quote\` = verbatim text of this turn. The MCP wraps it as \`- **<ISO> · you:** "verbatim"\`.
+3. **If Core Idea is empty:** auto-write a 1-sentence Core Idea (≤${CAPTURE_CORE_SOFT_MAX} soft / ${CAPTURE_CORE_HARD_MAX} hard chars) + a brief Summary (≤${CAPTURE_SUMMARY_SOFT_WORDS} soft / ≤${CAPTURE_SUMMARY_HARD_WORDS} hard words, ≤${CAPTURE_SUMMARY_CHAR_HARD_MAX} chars) in the **same \`heyspex_update_capture\` call** — pass \`core_idea\` + \`summary\` alongside \`user_quote\`. **No confirmation gate — just write them.**
+4. Reply: \`Connected with ${spec_id} — captured.\`
+
+### Beat 2 — Ground = Expand (auto, confirm-free)
+
+Grounding and expanding are **the same act** — do not treat them as separate steps. Ground the idea fast and light against the codebase, existing plans, and roadmap, peer tone (push back, be honest), and the moment you do, that grounding output IS the Expanded Concept:
+
+- Surface related [[wikilinks]], tensions, fit with current work — in chat, as always.
+- **Immediately** call \`heyspex_update_capture\` with \`agent_expansion\` = that same grounding, written to the \`## Expanded Concept\` section. **No offer, no "want me to expand?" question, no waiting for a yes.** This happens automatically, every time, for any idea given.
+- Deep verification needed? **Flag it for research** — never chase it inline (promote itself stays gated below).
+- **Grounding-time sufficiency gate:** every \`heyspex_update_capture\` response carries a \`sufficiency\` verdict — the same scorer \`heyspex_promote_capture\` runs. While it does **not** pass, present **iterate** plus **enhance to readiness** (elicit the listed missing elements — \`example\` / \`done_when\` / a considered \`kind\` — from the user and write them in this same pass); do **not** present "promote to research" as a live choice. Once it **passes**, show the enhanced capture and ask if the owner is satisfied with it; only after that yes do the two choices become **promote to research** (or promote-to-diagnose for \`kind: bug-fix\`) or **iterate**. Never present "do you want to expand" as a choice — it already happened.
+- **Open-the-doc offer (agent captures only):** if \`heyspex_update_capture\` returned \`offer_open_viewer\` (first materialization of an agent-opened capture), print its \`prompt\` in the same reply. On \`yes\` / \`open\` / \`show\`, run \`node bin/hs.mjs view docs <spec_id>\` immediately — never auto-open, never nag on later iterates. Companion/extension captures auto-open elsewhere; agent captures must ask.
+
+### Beat 3 — Promote to research (the only exit, gated)
+
+Research is the **only** downstream action from a capture. Never offer epics, tasks, or plans.
+
+- **Confirm-before-offer:** only offer promote once the sufficiency verdict passes (Beat 2 gate). While failing, elicit and write the missing elements instead — the promote-time gate would bounce the call anyway (it remains as defense-in-depth).
+- **Confirm-before-spend:** once passing, show the enhanced capture and ask if the owner is satisfied with it, then offer once: *"Ready to promote to research?"* A promote call is spent only after that yes.
+- Use \`heyspex_promote_capture\` (or console Promote button). For \`kind: bug-fix\`: \`heyspex_promote_capture_to_diagnose\` instead.
+- Do **not** create a \`type: research\` file until the user confirms.
+- An **explicit owner instruction** to promote anyway always wins — pass the elicited fields first when possible; \`force_promote: true\` is reserved for the owner's deliberate override, never a workaround for the gate.
+
+### Sufficiency (grounding-time gate — current verdict)
+
+${sufficiencySection}
+
+### Hard prohibitions
+
+- **Never** offer to file epics, tasks, or implementation plans — **at any point**.
+- **Never** create \`type: research\` without beat 3 confirmation.
+- **Never** ask the user whether to expand — Ground=Expand auto-writes \`agent_expansion\` every time; expand is never a separate, user-gated beat.
+- **Never** auto-open a browser / solo window for an agent-originated capture — offer once (\`yes\`/\`open\`/\`show\`) and only then run \`hs view docs <id>\`.
+- **Never** alter words inside a quote in Notes (format-wrapping is fine; word substitution is not).
+- Never add Executive Summary / Findings / Sources to the capture file.
+
+---
+
+## Core Idea (current)
+
+${core_idea || '_Empty — first capture from the user._'}
+
+---
+
+## Summary (brief — ≤${CAPTURE_SUMMARY_HARD_WORDS} words / ${CAPTURE_SUMMARY_CHAR_HARD_MAX} chars)
+
+${summarySection}
+
+---
+
+## Notes (existing — append, do not replace; never alter words inside quotes)
+
+${notesBlock}
+
+---
+
+## Expanded Concept (opt-in deep dive)
+
+${expandedSection}
+`;
+}
+
+const RESEARCH_SECTION_RE =
+  /^##\s*(Executive Summary|Findings|Sources)\b/im;
+
+function rejectResearchSections(text, field) {
+  if (!text || !RESEARCH_SECTION_RE.test(String(text))) return null;
+  return {
+    error: 'RESEARCH_SECTION_FORBIDDEN',
+    message: `${field} must not include research sections (Executive Summary, Findings, Sources). Keep captures concise; promote to research in console when ready.`,
+  };
+}
+
+/**
+ * The complete, named set of top-level arguments `heyspex_update_capture`
+ * accepts. Mirrors the tool's `inputSchema.properties` keys in cli.mjs — kept
+ * as a standalone list (not derived from the schema) because the schema's
+ * `additionalProperties: false` is never validated at runtime by any layer
+ * (client/server/transport); the only real enforcement is this explicit,
+ * in-code allowlist checked at the handler's first hop —
+ * [[additionalproperties-false-in-an-mcp]].
+ */
+export const UPDATE_CAPTURE_ACCEPTED_ARGS = [
+  'spec_id',
+  'core_idea',
+  'summary',
+  'concept',
+  'user_quote',
+  'agent_note',
+  'agent_expansion',
+  'example',
+  'user_stories',
+  'kind',
+  'done_when',
+  'jtbd',
+];
+
+/**
+ * Pure verdict on a `heyspex_update_capture` argument bag: refuses an
+ * unrecognized/misspelled key BY NAME instead of letting it silently vanish
+ * into a hand-built payload (the exact failure mode
+ * [[additionalproperties-false-in-an-mcp]] documents — a declared
+ * `additionalProperties: false` inputSchema is decoration, nothing enforces it
+ * at runtime). Call this at the handler's first hop, before any session
+ * resolution or buffer-patch building.
+ */
+export function updateCaptureArgsVerdict(args = {}) {
+  const unknown = Object.keys(args).filter((k) => !UPDATE_CAPTURE_ACCEPTED_ARGS.includes(k));
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      error: {
+        error: 'UNKNOWN_FIELD',
+        message: `heyspex_update_capture does not accept: ${unknown.join(', ')}. NOTHING WAS WRITTEN — re-send using only the accepted arguments.`,
+        field: unknown[0],
+        unknown_fields: unknown,
+        accepted_fields: UPDATE_CAPTURE_ACCEPTED_ARGS,
+      },
+    };
+  }
+  return { ok: true };
+}
+
+export function executeUpdateCapture(vaultRoot, parseFrontmatter, args = {}, deps = {}) {
+  let specPath = null;
+  let autoCreated = false;
+  let continuationOf = null;
+
+  if (args.spec_id) {
+    specPath = findCaptureSpecFile(vaultRoot, args.spec_id);
+    if (!specPath) {
+      return { error: 'SPEC_NOT_FOUND', message: `Capture ${args.spec_id} not found` };
+    }
+  } else {
+    const ensured = ensureActiveCapturePin(vaultRoot, parseFrontmatter, deps.loadSpec, {
+      allocateRandomVaultId: deps.allocateRandomVaultId,
+      occupiedCaptureIds: deps.occupiedCaptureIds,
+      pinReason: 'Auto-created via heyspex_update_capture',
+      claim: deps.claim ?? null,
+    });
+    if (ensured.error) {
+      return { error: ensured.error, message: ensured.message };
+    }
+    autoCreated = ensured.auto_created === true;
+    continuationOf = ensured.continuation_of ?? null;
+    specPath = ensured.resolved.spec_path;
+  }
+
+  const fullPath = join(vaultRoot, specPath);
+  if (!existsSync(fullPath)) {
+    return { error: 'CAPTURE_FILE_MISSING', message: specPath };
+  }
+
+  // `summary` is the canonical input; `concept` is the deprecated alias (HS-EPIC-OED2).
+  const summaryArg = args.summary ?? args.concept;
+
+  for (const [field, value] of [
+    ['core_idea', args.core_idea],
+    ['user_quote', args.user_quote],
+    ['agent_note', args.agent_note],
+    ['summary', summaryArg],
+    ['example', args.example],
+    ['done_when', args.done_when],
+    ['jtbd', args.jtbd],
+  ]) {
+    const blocked = rejectResearchSections(value, field);
+    if (blocked) return blocked;
+  }
+
+  const content = readFileSync(fullPath, 'utf-8');
+  const { frontmatter, body } = parseFrontmatter(content);
+  let core = extractCaptureCoreFromBody(body);
+  let notes = extractCaptureNotesFromBody(body);
+  let summary = extractCaptureSummaryFromBody(body);
+  let example = extractCaptureExampleFromBody(body);
+  let doneWhen = extractCaptureDoneWhenFromBody(body);
+  let jtbd = extractCaptureJtbdFromBody(body);
+  const iso = new Date().toISOString();
+
+  // Track whether this update writes to any of the "expansion" surfaces —
+  // core_idea / summary / agent_expansion. When true, capture_status flips
+  // raw → expanded after persistence. Note-only and quote-only writes do NOT
+  // flip the field — those layers can be appended in the raw single-textarea
+  // flow without promoting the capture out of raw state.
+  let didExpand = false;
+
+  if (args.user_quote && String(args.user_quote).trim()) {
+    const entry = formatUserNoteEntry(iso, 'you', String(args.user_quote));
+    notes = appendCaptureNote(notes, entry);
+  }
+
+  if (args.agent_note && String(args.agent_note).trim()) {
+    const entry = formatUserNoteEntry(iso, 'agent', String(args.agent_note));
+    notes = appendCaptureNote(notes, entry);
+  }
+
+  if (args.core_idea !== undefined && String(args.core_idea).trim()) {
+    const nextCore = String(args.core_idea).trim();
+    const check = validateCaptureCore(nextCore);
+    if (!check.ok) return { error: 'CORE_TOO_LONG', message: check.error };
+    core = nextCore;
+    didExpand = true;
+  }
+
+  let summaryWarning;
+  if (summaryArg !== undefined && String(summaryArg).trim()) {
+    const nextSummary = String(summaryArg).trim();
+    const check = validateSummaryLength(nextSummary);
+    if (!check.ok) return { error: 'SUMMARY_TOO_LONG', message: check.error };
+    if (check.warning) summaryWarning = check.warning;
+    summary = nextSummary;
+    didExpand = true;
+  }
+
+  let agentExpansion = extractAgentExpansionFromBody(body);
+  if (args.agent_expansion !== undefined && String(args.agent_expansion).trim()) {
+    const blocked = rejectResearchSections(args.agent_expansion, 'agent_expansion');
+    if (blocked) return blocked;
+    agentExpansion = String(args.agent_expansion).trim();
+    didExpand = true;
+  }
+
+  if (args.example !== undefined && String(args.example).trim()) {
+    example = String(args.example).trim();
+    didExpand = true;
+  }
+
+  let userStories = extractCaptureUserStoriesFromBody(body);
+  if (args.user_stories !== undefined && String(args.user_stories).trim()) {
+    userStories = String(args.user_stories).trim();
+    didExpand = true;
+  }
+
+  // `done_when` — the schema has promised this arg since the HS-NR43 gate
+  // remediation pointed at it, but it was silently dropped until
+  // [[HS-AYCX-T9T6-TASK-grounding-time-sufficiency-check]] wired it through.
+  if (args.done_when !== undefined && String(args.done_when).trim()) {
+    doneWhen = String(args.done_when).trim();
+    didExpand = true;
+  }
+
+  // `jtbd` — authored by the /hs-capture enhancement pass, persisted across
+  // updates like `example`/`user_stories`/`done_when`
+  // ([[HS-TIE7-PR20-TASK-jtbd-job-to-be-done-field-on-captures]]).
+  if (args.jtbd !== undefined && String(args.jtbd).trim()) {
+    jtbd = String(args.jtbd).trim();
+    didExpand = true;
+  }
+
+  // HS-RZQO elicitation: user-confirmed kind re-classification. Only canonical
+  // agent-settable values are accepted (spec-import is importer-stamped, never
+  // agent-set); an unknown value is ignored, never a throw.
+  const AGENT_SETTABLE_KINDS = ['idea', 'bug-fix', 'clip', 'reference', 'question'];
+  let kindUpdate = null;
+  if (args.kind !== undefined && AGENT_SETTABLE_KINDS.includes(String(args.kind).trim())) {
+    kindUpdate = String(args.kind).trim();
+  }
+
+  // Preserve any existing `## Source Material` across the rebuild (MCP args don't
+  // carry source material, but it must survive an update — it used to be dropped).
+  const sourceMaterial = extractSourceMaterialFromBody(body);
+  const newBody = buildCaptureBody(core, notes, summary, agentExpansion, sourceMaterial, example, userStories, doneWhen, jtbd);
+  const updated = new Date().toISOString().slice(0, 10);
+  const fm = { ...frontmatter, updated };
+  // SV2K: assert type: capture going forward; legacy type: idea is tolerated until E2.
+  if (fm.type === 'idea') fm.type = 'capture';
+  if (!fm.kind) fm.kind = 'idea';
+  if (kindUpdate) fm.kind = kindUpdate;
+  // P2WA: flip capture_status to 'expanded' on any write to core/summary/expansion.
+  // Backstop: if the body already has Core Idea content (e.g. from a prior
+  // session writing only notes), surface that to the field. Never demote.
+  if (didExpand || core.trim().length > 0) {
+    fm.capture_status = 'expanded';
+  } else if (fm.capture_status !== 'expanded' && fm.capture_status !== 'raw') {
+    fm.capture_status = 'raw';
+  }
+  if (core.trim()) {
+    const firstLine = core.split('\n').map((l) => l.trim()).find(Boolean);
+    if (firstLine) fm.name = firstLine.replace(/^[-*>\s"]+|["]+$/g, '').slice(0, 80);
+  }
+
+  writeFileSync(fullPath, stringifyCaptureSpec(fm, newBody), 'utf8');
+
+  // Real content just landed → drop the empty-scaffold fuse so this capture is
+  // no longer treated as an abandonable zombie. Runs regardless of whether a
+  // claim refresh follows (a content write without a claim must still defuse).
+  const hasContent =
+    core.trim() !== '' ||
+    notes.trim() !== '' ||
+    summary.trim() !== '' ||
+    example.trim() !== '' ||
+    doneWhen.trim() !== '' ||
+    String(agentExpansion ?? '').trim() !== '';
+  if (hasContent) {
+    clearCaptureFocusExpiry(vaultRoot);
+  }
+
+  if (deps.claim) {
+    updateCaptureFocusClaim(vaultRoot, deps.claim);
+  }
+
+  const result = {
+    success: true,
+    spec_id: fm.id,
+    spec_path: specPath,
+    core_idea: core,
+    notes_length: notes.length,
+    auto_created: autoCreated,
+    message: autoCreated
+      ? 'Fresh capture auto-created. Core and notes stay in sync for /hs-capture.'
+      : 'Capture file updated. Core and notes stay in sync for /hs-capture.',
+  };
+  if (continuationOf) {
+    // HS-KFB2: this fresh capture continues a recently-promoted idea's
+    // lineage (stamped `continues:` + a body note by createFreshCaptureSpec).
+    // Surface it so the calling agent can suggest — never auto-apply — that
+    // this content might belong appended to the research doc instead.
+    result.continuation_of = continuationOf;
+    result.continuation_note = `This capture was auto-created as a continuation of a recently-promoted idea (${continuationOf}). Consider telling the user this looks like a follow-on to that idea, and offering to append it to ${continuationOf} instead of (or in addition to) this new capture.`;
+  }
+  if (args.core_idea) {
+    const check = validateCaptureCore(core);
+    if (check.warning) result.warning = check.warning;
+  }
+  if (summaryWarning) {
+    result.summary_warning = summaryWarning;
+    // Back-compat: older callers read `concept_warning`.
+    result.concept_warning = summaryWarning;
+  }
+  // Grounding-time sufficiency ([[HS-AYCX-T9T6-TASK-grounding-time-sufficiency-check]]):
+  // score the state just written with the same scorer the promote gate uses, so
+  // the agent elicits missing elements in this pass instead of bouncing at
+  // promote time. Read-only — never blocks the update or triggers a promote.
+  result.sufficiency = computeCaptureSufficiency(fm, newBody);
+  return result;
+}
+
+/**
+ * Auto-create a fresh capture spec when no capture is pinned. Returns
+ * { spec_id, spec_path } using POSIX-style spec_path for the focus YAML.
+ */
+/** Strip an existing `[[...]]` wrapper (promoted_to is stored pre-wrapped) so a
+ *  wikilink target can be re-wrapped exactly once, regardless of whether the
+ *  caller passed a bare id or an already-bracketed link. */
+function unwrapWikilink(s) {
+  const trimmed = String(s ?? '').trim();
+  const m = trimmed.match(/^\[\[(.+)\]\]$/);
+  return m ? m[1] : trimmed;
+}
+
+export function createFreshCaptureSpec(vaultRoot, allocateRandomVaultId, occupiedCaptureIds, lineage = null) {
+  // Era-3 file-key-first ([[naming-v3-7-rulings-hs-namespace-kept]]): the
+  // FAMILY token still comes from the legacy allocator's `HS-<family>-CAP`
+  // draw (parentless capture — no family to inherit); `id:` keys onto the
+  // file key alone.
+  const allocatedFamilyId = allocateRandomVaultId('capture', occupiedCaptureIds);
+  const familyKey = parseSpecId(allocatedFamilyId)?.familyKey ?? mintFamilyKey(vaultRoot);
+  // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+  // and (V3) the anchor for `id:` itself.
+  const fileKey = mintFileKey(vaultRoot);
+  const newId = `HS-${fileKey}`;
+  const today = new Date().toISOString().slice(0, 10);
+  const slug = `idea-${today}`;
+  const filename = `${newId}-${familyKey}-CAP-${slug}.md`;
+  const dir = join(vaultRoot, 'specs', 'captures');
+  mkdirSync(dir, { recursive: true });
+  const iso = new Date().toISOString();
+  const frontmatter = {
+    id: newId,
+    file_id: fileKey,
+    family: familyKey,
+    name: `Capture ${today}`,
+    type: 'capture',
+    kind: 'idea',
+    status: 'open',
+    owner: 'pwher',
+    created: iso,
+    updated: iso,
+    tags: ['idea', 'capture'],
+    promoted_to: null,
+    capture_status: 'raw',
+    // HS-KFB2: lineage carry-over — a same-session follow-on to a recently-
+    // promoted idea is no longer a disconnected orphan; it links back to the
+    // idea it continues (the research it was promoted into, and the retired
+    // source capture) so the vault stays traceable even though this is still a
+    // fresh capture object (the promoted source capture rejects new writes —
+    // see the diagnose's interim-remediation note).
+    ...(lineage?.promotedTo ? { continues: `[[${unwrapWikilink(lineage.promotedTo)}]]` } : {}),
+  };
+  const body = lineage?.promotedTo
+    ? CAPTURE_BODY_TEMPLATE.replace(
+        /^# Core Idea\n/,
+        `# Core Idea\n\n> Continuation of a recently-promoted idea — see [[${unwrapWikilink(lineage.promotedTo)}]]` +
+          (lineage.retiredCaptureBasename
+            ? ` (originally [[${unwrapWikilink(lineage.retiredCaptureBasename)}]]).`
+            : '.') +
+          '\n',
+      )
+    : CAPTURE_BODY_TEMPLATE;
+  writeFileSync(join(dir, filename), stringifyCaptureSpec(frontmatter, body), 'utf8');
+  return {
+    spec_id: newId,
+    spec_path: `specs/captures/${filename}`,
+    ...(lineage?.promotedTo ? { continuation_of: unwrapWikilink(lineage.promotedTo) } : {}),
+  };
+}
+
+export function executePinCapture(vaultRoot, parseFrontmatter, loadSpec, args = {}) {
+  const specId = args.spec_id;
+  if (!specId) {
+    return { error: 'MISSING_SPEC_ID', message: 'spec_id is required' };
+  }
+  const specPath = findCaptureSpecFile(vaultRoot, specId);
+  if (!specPath) {
+    return { error: 'SPEC_NOT_FOUND', message: `Capture ${specId} not found` };
+  }
+  const spec = loadSpec(vaultRoot, specPath);
+  const fmType = spec?.frontmatter?.type;
+  if (!spec || (fmType !== 'capture' && fmType !== 'idea')) {
+    return { error: 'NOT_A_CAPTURE', message: `${specId} is not type: capture` };
+  }
+  // Mirror the capture's real kind into the pin (spec-import / bug-fix / … not a
+  // hardcoded idea) — [[capture-guardrails]] §Capture-on-deck pin.
+  const pinnedKind = spec.frontmatter?.kind;
+  writeCaptureFocus(vaultRoot, specPath, args.reason || 'Pinned via MCP', null, {
+    kind: typeof pinnedKind === 'string' ? pinnedKind : undefined,
+  });
+  return {
+    success: true,
+    spec_id: specId,
+    spec_path: specPath,
+    message: `Capture ${specId} is now on deck for /hs-capture`,
+  };
+}