heyspex 0.1.0

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

@@ -0,0 +1,1280 @@
+/**
+ * /hs-promote-capture MCP tool — capture(s) → research promotion with
+ * AI-assisted outline. Spec: [[HS-TASK-WQCE]] of [[HS-EPIC-M2J3]].
+ *
+ * Symmetric to [[HS-TASK-QQHP]] (/hs-promote-research) but at the lower edge
+ * of the lifecycle: one or more `HS-CAP-*` captures get aggregated into a
+ * single `HS-RES-*` research doc, with bidirectional linkage wired both ways.
+ *
+ * Two-phase flow driven by presence/absence of `accepted_outline`:
+ *
+ *   Phase 1 (review): caller invokes with `target_research: "NEW"` and no
+ *     `accepted_outline`. Returns capture summaries to the calling agent, which
+ *     authors the outline and shows it to the human for confirmation. No file writes.
+ *
+ *   Phase 2 (execute): caller invokes again with `accepted_outline` populated
+ *     (or directly with an existing `target_research: "HS-RES-XXX"`). Tool
+ *     performs the transactional write set:
+ *       - create-or-update the research file (sources_captures appended)
+ *       - mutate each capture's `informs_research:` (idempotent append)
+ *       - set `promoted_to:` on each capture ONLY when it was previously
+ *         unset/null (binary first-promotion semantics per
+ *         [[entity-model]] §capture)
+ *       - append change-log rows on the research + each capture
+ *     and rolls back anything written if a later step fails.
+ *
+ * Closed-research target is NOT a hard error (unlike QQHP, where closed
+ * research refuses re-promotion). Per spec §5, the tool warns
+ * (`warning: "TARGET_RESEARCH_CLOSED"`) and allows the append; the audit
+ * trail in the research's change-log records the post-close addition.
+ *
+ * Linkage written per [[HS-TASK-YJX6]]:
+ *   research.sources_captures : appended with each capture wikilink
+ *   capture.informs_research  : appended with the research wikilink
+ *   capture.promoted_to       : set to research wikilink on FIRST promotion
+ *
+ * All writes are staged then committed via the shared `commitWrites`
+ * helper from [[./promotion-helpers.mjs]]; any failure rolls back the prior
+ * writes (created files deleted, mutated files restored from snapshot).
+ */
+
+import {
+  readFileSync,
+  existsSync,
+  readdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+// Sufficiency gate at promotion ([[HS-0CFX-TASK]] / [[HS-3EFV-EPIC]]) — the same
+// dev-factory scorer the Phase-1 entry gate uses (cross-import precedented by
+// fleet-readiness.mjs in cli.mjs; deliberately NOT a third mirror copy).
+import { scoreSufficiency } from '../../dev-factory/lib/sufficiency-score.mjs';
+// Already-expanded bypass ([[HS-55YM-DIAG]]) — reuses the existing
+// capture-focus.mjs deep-dive reader rather than a third regex copy.
+import { extractCaptureExpandedConceptFromBody } from './capture-focus.mjs';
+import {
+  mintFileKey,
+  mintFamilyKey,
+  parseSpecId,
+  familyOf,
+  bareFileKeyOf,
+  lookupFileKeyOf,
+  shortLookupIdOf,
+} from './spec-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { suggestResearchType } from './research-type-suggest.mjs';
+import { buildDiagnoseSkeletonSections } from './diagnose-skeleton.mjs';
+// HS-QOBQ: re-check kind at promote time — a capture wrongly filed as `idea`
+// (the default) whose body actually reads as a bug report should be re-kinded
+// before promoting, not silently routed to research (capture-guardrails
+// §"Which exit?"). Same lexical guess the intent classifier suggests at
+// capture time, so both call sites agree.
+import { checkCaptureKindMismatch } from './capture-kind-suggest.mjs';
+import {
+  isoNow,
+  todayDate,
+  deriveSlug,
+  findFileByPrefix,
+  getFrontmatterBlock,
+  getScalarField,
+  parseListFieldBasenames,
+  setScalarField,
+  appendToListField,
+  bumpUpdated,
+  appendChangeLogRow,
+  commitWrites,
+} from './promotion-helpers.mjs';
+// Reuse the exact same placeholder-count logic RESEARCH_STILL_STUB uses to
+// refuse `heyspex_promote_research` on a stub research doc — proactively
+// surfaced here at creation/extension time instead of only reactively at
+// the downstream refusal ([[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]]).
+import { findUnresolvedResearchPlaceholders } from './promote-research.mjs';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dual-read id classification ([[HS-MIL-KY1F]] family-first migration).
+//
+// The vault now mints family-first ids (`HS-<familyKey>-<TYPE>`, e.g.
+// `HS-IY9V-CAP`) but legacy specs may still carry the type-first ordering
+// (`HS-CAP-IY9V`). We classify an id/basename by its parsed **type label**
+// rather than a fixed-ordering regex, so both orderings resolve. See
+// vendor/heyspex-mcp/spec-id-lib.mjs (`parseSpecId`).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** True when `id` (either ordering) parses to a spec with the given type label. */
+function hasTypeLabel(id, label) {
+  const p = parseSpecId(id);
+  return !!p && p.typeLabel === label;
+}
+
+const isCaptureId = (id) => hasTypeLabel(id, 'CAP');
+const isResearchId = (id) => hasTypeLabel(id, 'RES');
+const isMilestoneId = (id) => hasTypeLabel(id, 'MIL');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Family inheritance (capture → research), owner ruling 2026-07-12
+// ([[family-id-is-inherited-capture-research]] / [[HS-3JUN-DIAG-HZ8T]]),
+// rewritten for the V3 shared-surname model
+// ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]],
+// [[naming-v3-7-rulings-hs-namespace-kept]]).
+//
+// Research promoted from a capture INHERITS the FIRST/primary source
+// capture's family key — UNCONDITIONALLY, no fallback. Under era-3 minting,
+// `id:` keys onto the per-file file key alone (`HS-<fileKey>`), not the
+// family key, so two research docs sharing one family can never collide on
+// `id:` — the disambiguation problem `FAMILY_INHERITANCE_FALLBACK` guarded
+// against ([[HS-3JUN-DIAG-HZ8T]]) no longer exists. See
+// vault-id-assignment-protocol §Family inheritance ("`FAMILY_INHERITANCE_
+// FALLBACK` is removed, not documented as a case").
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The family key of a promotion source: explicit `frontmatter.family` when
+ * present and well-formed, else the positional family key parsed from `id`,
+ * else the positional key parsed from the BASENAME — the same "explicit wins,
+ * else positional" precedence as {@link familyOf} (which this delegates to).
+ * Returns null when none is derivable.
+ *
+ * The basename argument is load-bearing under era-3 naming: a minted `id:` is
+ * the bare file key (`HS-6VT0`), which parseSpecId cannot read a family out
+ * of — the family rides in the basename (`HS-6VT0-84HC-CAP-<slug>`). Passing
+ * only the id silently fell through to mintFamilyKey and broke the owner's
+ * unconditional-inheritance ruling ([[family-id-is-inherited-capture-research]]).
+ * Callers inherit the result directly — no candidate-vs-occupied collision
+ * check is needed (see block comment above).
+ */
+function inheritedFamilyKey(sourceId, sourceFrontmatter, sourceBasename) {
+  return familyOf({ id: sourceId, basename: sourceBasename, frontmatter: sourceFrontmatter });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `research_type` — the declared purpose of a research doc, required by
+// [[entity-model]] §research / `schemas/heyspex-frontmatter.schema.json`
+// ([[HS-120I-TASK-implement-research-type-field-end-to-end]]). Written here on
+// every NEW research doc this tool creates — never blank.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const RESEARCH_TYPE_VALUES = [
+  'new-feature',
+  'enhancement',
+  'diagnose',
+  'code-audit',
+  'reference',
+];
+export const DEFAULT_RESEARCH_TYPE = 'reference';
+
+/**
+ * Resolve the `research_type` to write for a newly created research doc.
+ * Precedence: an explicit `accepted_outline.research_type` (human-confirmed)
+ * wins; otherwise a `suggestedType` — computed by
+ * [[HS-MVC1-EPIC-deterministic-type-assist-suggest-resear]]'s
+ * `suggestResearchType()` from the source capture's `kind` (see
+ * `runExecutePhase` below) — is used when present; falls back to
+ * {@link DEFAULT_RESEARCH_TYPE}. Never returns a blank/invalid value.
+ * @param {unknown} providedValue
+ * @param {unknown} [suggestedType] — kind-derived suggestion (HS-MVC1).
+ * @returns {string}
+ */
+export function resolveResearchType(providedValue, suggestedType = null) {
+  if (typeof providedValue === 'string' && RESEARCH_TYPE_VALUES.includes(providedValue)) {
+    return providedValue;
+  }
+  if (typeof suggestedType === 'string' && RESEARCH_TYPE_VALUES.includes(suggestedType)) {
+    return suggestedType;
+  }
+  return DEFAULT_RESEARCH_TYPE;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `scope` — how broad a search context this research was run at, per
+// [[entity-model]] §research / `schemas/heyspex-frontmatter.schema.json`
+// ([[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]). NOT
+// required (consistency fix only — no grace window, unlike `research_type`).
+// Written here with the same enum + same default as `heyspex_save_research`
+// and `heyspex_complete_research`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const RESEARCH_SCOPE_VALUES = ['internal', 'codebase', 'external', 'all'];
+export const DEFAULT_RESEARCH_SCOPE = 'internal';
+
+/**
+ * Resolve the `scope` to write for a newly created research doc. Falls back
+ * to {@link DEFAULT_RESEARCH_SCOPE} for a missing/invalid value.
+ * @param {unknown} providedValue
+ * @returns {string}
+ */
+export function resolveResearchScope(providedValue) {
+  if (typeof providedValue === 'string' && RESEARCH_SCOPE_VALUES.includes(providedValue)) {
+    return providedValue;
+  }
+  return DEFAULT_RESEARCH_SCOPE;
+}
+
+/**
+ * Canonical family-first bare id (`HS-<familyKey>-<TYPE>`) for an id/basename of
+ * EITHER ordering, gated to a single type label — or null. Feeds
+ * {@link collectOccupiedResearchIds}/{@link collectOccupiedDiagnoseIds}
+ * (dual-read occupancy sets, kept for their own test coverage — no longer
+ * consulted for era-3 minting, which keys `id:` on the vault-wide-unique file
+ * key instead of a per-kind family+type bucket).
+ */
+function canonicalIdOfType(value, label) {
+  const p = parseSpecId(value);
+  if (!p || p.typeLabel !== label) return null;
+  return `HS-${p.familyKey}-${p.typeLabel}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File loaders
+// ─────────────────────────────────────────────────────────────────────────────
+
+function findCaptureByIdLocal(vaultRoot, captureId) {
+  const dir = join(vaultRoot, 'specs', 'captures');
+  if (!existsSync(dir)) return null;
+  const direct = findFileByPrefix(dir, captureId);
+  if (direct) {
+    const basename = direct.replace(/\.md$/, '');
+    const absPath = join(dir, direct);
+    return {
+      basename,
+      absPath,
+      relPath: join('specs', 'captures', direct),
+      raw: readFileSync(absPath, 'utf8'),
+    };
+  }
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const raw = readFileSync(join(dir, file), 'utf8');
+    const idMatch = raw.match(/^id:\s*(\S+)/m);
+    if (idMatch) {
+      const id = idMatch[1].replace(/^['"]|['"]$/g, '');
+      if (id === captureId) {
+        const basename = file.replace(/\.md$/, '');
+        return {
+          basename,
+          absPath: join(dir, file),
+          relPath: join('specs', 'captures', file),
+          raw,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function findResearchByIdLocal(vaultRoot, researchId) {
+  const dir = join(vaultRoot, 'specs', 'research');
+  if (!existsSync(dir)) return null;
+  const direct = findFileByPrefix(dir, researchId);
+  const tryFile = (file) => {
+    const basename = file.replace(/\.md$/, '');
+    const absPath = join(dir, file);
+    return {
+      basename,
+      absPath,
+      relPath: join('specs', 'research', file),
+      raw: readFileSync(absPath, 'utf8'),
+    };
+  };
+  if (direct) return tryFile(direct);
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const raw = readFileSync(join(dir, file), 'utf8');
+    const idMatch = raw.match(/^id:\s*(\S+)/m);
+    if (idMatch) {
+      const id = idMatch[1].replace(/^['"]|['"]$/g, '');
+      if (id === researchId) {
+        const basename = file.replace(/\.md$/, '');
+        return {
+          basename,
+          absPath: join(dir, file),
+          relPath: join('specs', 'research', file),
+          raw,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function findResearchByBasename(vaultRoot, basename) {
+  const absPath = join(vaultRoot, 'specs', 'research', `${basename}.md`);
+  if (!existsSync(absPath)) return null;
+  return {
+    basename,
+    absPath,
+    relPath: join('specs', 'research', `${basename}.md`),
+    raw: readFileSync(absPath, 'utf8'),
+  };
+}
+
+function collectOccupiedResearchIds(vaultRoot) {
+  const occupied = new Set();
+  const dir = join(vaultRoot, 'specs', 'research');
+  if (!existsSync(dir)) return occupied;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const fromBasename = canonicalIdOfType(file.replace(/\.md$/, ''), 'RES');
+    if (fromBasename) occupied.add(fromBasename);
+    try {
+      const raw = readFileSync(join(dir, file), 'utf8');
+      const idMatch = raw.match(/^id:\s*(\S+)/m);
+      if (idMatch) {
+        const id = idMatch[1].replace(/^['"]|['"]$/g, '');
+        const fromId = canonicalIdOfType(id, 'RES');
+        if (fromId) occupied.add(fromId);
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return occupied;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Argument validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function validateInputShape(args) {
+  if (!args || typeof args !== 'object') {
+    return { error: 'INVALID_ARGS', message: 'args must be an object' };
+  }
+  if (!Array.isArray(args.capture_ids) || args.capture_ids.length === 0) {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'capture_ids must be a non-empty array',
+    };
+  }
+  for (const id of args.capture_ids) {
+    // Era-3 minted ids are the bare file key (`HS-<fileKey>`) — deliberately
+    // TYPE-LESS, so no label check is possible on the id itself. Any
+    // recognizable era-3 form (bare key, display long `HS-<fileKey>-<familyKey>`,
+    // full basename) is accepted via lookupFileKeyOf (owner ruling 2026-08-21:
+    // resolvers recognize every form the human might paste). The loader
+    // (findCaptureByIdLocal, scoped to specs/captures/) is what proves it
+    // names a capture, and misses fail as CAPTURE_NOT_FOUND.
+    if (typeof id !== 'string' || (!isCaptureId(id) && !lookupFileKeyOf(id))) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `capture_ids entry ${id} is not a capture id (expected HS-<key>-CAP, legacy HS-CAP-<key>, or an era-3 id/basename carrying the file key)`,
+      };
+    }
+  }
+  if (typeof args.target_research !== 'string' || !args.target_research.trim()) {
+    return { error: 'INVALID_ARGS', message: 'target_research is required' };
+  }
+  if (args.target_research === 'NEW') {
+    if (
+      typeof args.new_research_name !== 'string' ||
+      !args.new_research_name.trim()
+    ) {
+      return {
+        error: 'INVALID_ARGS',
+        message: 'new_research_name is required when target_research === "NEW"',
+      };
+    }
+  } else if (!isResearchId(args.target_research) && !lookupFileKeyOf(args.target_research)) {
+    // Any era-3 form accepted for the same reason as capture_ids above — the
+    // research loader (specs/research/ scoped) is the existence/type check
+    // ([[HS-DQ9H-8J7V-DIAG-promote-capture-cannot-target-era-3]]).
+    return {
+      error: 'INVALID_ARGS',
+      message: `target_research ${args.target_research} is not a research id (expected HS-<key>-RES, legacy HS-RES-<key>, or an era-3 id/basename carrying the file key) or the literal "NEW"`,
+    };
+  }
+  if (
+    args.enhances !== undefined &&
+    args.enhances !== null &&
+    args.enhances !== ''
+  ) {
+    if (typeof args.enhances !== 'string' || !isMilestoneId(args.enhances)) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `enhances ${args.enhances} must be a milestone id or basename (HS-<key>-MIL, or legacy HS-MIL-<key>)`,
+      };
+    }
+  }
+  if (args.accepted_outline !== undefined && args.accepted_outline !== null) {
+    if (typeof args.accepted_outline !== 'object') {
+      return {
+        error: 'INVALID_ARGS',
+        message: 'accepted_outline must be an object when provided',
+      };
+    }
+    if (
+      typeof args.accepted_outline.name !== 'string' ||
+      !args.accepted_outline.name.trim()
+    ) {
+      return {
+        error: 'INVALID_ARGS',
+        message: 'accepted_outline.name is required',
+      };
+    }
+    if (!Array.isArray(args.accepted_outline.outline)) {
+      return {
+        error: 'INVALID_ARGS',
+        message: 'accepted_outline.outline must be an array of section names',
+      };
+    }
+    if (
+      args.accepted_outline.research_type !== undefined &&
+      args.accepted_outline.research_type !== null &&
+      !RESEARCH_TYPE_VALUES.includes(args.accepted_outline.research_type)
+    ) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `accepted_outline.research_type ${JSON.stringify(args.accepted_outline.research_type)} must be one of: ${RESEARCH_TYPE_VALUES.join(', ')}`,
+      };
+    }
+    if (
+      args.accepted_outline.scope !== undefined &&
+      args.accepted_outline.scope !== null &&
+      !RESEARCH_SCOPE_VALUES.includes(args.accepted_outline.scope)
+    ) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `accepted_outline.scope ${JSON.stringify(args.accepted_outline.scope)} must be one of: ${RESEARCH_SCOPE_VALUES.join(', ')}`,
+      };
+    }
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 1: review (AI proposal)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runProposalPhase(args, ctx, _deps) {
+  const captureSummaries = ctx.captures.map((c) => {
+    const fm = getFrontmatterBlock(c.raw);
+    const name = fm ? getScalarField(fm.block, 'name') : null;
+    const tagsList = fm ? parseListFieldBasenames(fm.block, 'tags') : null;
+    const body = c.raw
+      .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '')
+      .slice(0, 4000);
+    // HS-QOBQ: re-check the stored kind against the content at the moment of
+    // promotion — the diagnose's own rule is "a capture mistakenly filed as
+    // the wrong kind is re-kinded before promoting, not promoted twice."
+    const kindCheck = checkCaptureKindMismatch(c.frontmatter?.kind, body);
+    return {
+      id: c.frontmatter?.id ?? c.basename,
+      name: name ?? c.basename,
+      body,
+      tags: Array.isArray(tagsList) ? tagsList : [],
+      kind: kindCheck.storedKind,
+      ...(kindCheck.mismatch ? { kind_suggestion: kindCheck.suggestedKind } : {}),
+    };
+  });
+
+  const mismatched = captureSummaries.filter((c) => c.kind_suggestion);
+
+  return {
+    phase: 'review',
+    capture_ids: ctx.captures.map((c) => c.frontmatter?.id ?? c.basename),
+    capture_basenames: ctx.captures.map((c) => c.basename),
+    target_research: 'NEW',
+    new_research_name: args.new_research_name,
+    proposed_outline: null,
+    capture_summaries: captureSummaries,
+    ai_proposal: {
+      ok: false,
+      reason: 'agent_authors_outline',
+      message:
+        'Outline authoring is delegated to the calling agent — no server-side AI call is made. The agent reads capture_summaries and proposes the outline directly.',
+    },
+    ...(mismatched.length > 0
+      ? {
+          warning: 'CAPTURE_KIND_MISMATCH',
+          kind_mismatch_message:
+            `${mismatched.length} capture${mismatched.length === 1 ? '' : 's'} read as a different kind than stored ` +
+            `(${mismatched.map((c) => `${c.id}: stored ${c.kind} → reads like ${c.kind_suggestion}`).join('; ')}). ` +
+            'Per capture-guardrails "Which exit?": a mismatched capture should be re-kinded before promoting, ' +
+            'not promoted twice — offer the reclassification (and, for bug-fix, the promote-to-diagnose exit ' +
+            'instead) to the user before authoring a research outline; call heyspex_update_capture with kind ' +
+            'ONLY on their yes ([[HS-5HYS]] elicitation — suggest, never auto-apply).',
+        }
+      : {}),
+    human_review_required: true,
+    next_call_hint:
+      'Author the outline from capture_summaries, show it to the user for confirmation, then call heyspex_promote_capture again with the same args plus `accepted_outline: { name, outline, tags, enhances_suggestion? }` to execute the writes.',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 2: execute (transactional writes)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildResearchStubContent(researchId, fileKey, familyKey, outline, captureBasenames, enhances, now, suggestedType = null, jtbdSeed = '') {
+  const today = now.slice(0, 10);
+  const tagsBlock =
+    outline.tags && outline.tags.length > 0
+      ? `tags:\n${outline.tags.map((t) => `  - "${t}"`).join('\n')}`
+      : 'tags: []';
+  const sourcesBlock =
+    captureBasenames.length === 0
+      ? 'sources_captures: []'
+      : `sources_captures:\n${captureBasenames
+          .map((b) => `  - "[[${b}]]"`)
+          .join('\n')}`;
+  // HS-MVC1: an explicit outline.research_type (human-confirmed) still wins;
+  // suggestedType (kind-derived, see runExecutePhase) fills in only when the
+  // outline left research_type unset — never overrides an explicit choice.
+  const researchType = resolveResearchType(outline.research_type, suggestedType);
+  const researchScope = resolveResearchScope(outline.scope);
+  const enhancesLine = enhances ? `enhances: "[[${enhances}]]"\n` : '';
+  // Drop any agent-authored "conclusion & intended outcome" heading from the
+  // outline — the stub always injects the canonical one below, so we avoid a
+  // duplicate section ([[HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h]]).
+  const sectionsBody = outline.outline
+    .filter(
+      (section) =>
+        !/^\s*(conclusion\b.*intended outcome|intended outcome|conclusion & intended outcome)\s*$/i.test(
+          section,
+        ),
+    )
+    .map((section) => `## ${section}\n\n_TBD — fill in this section._\n`)
+    .join('\n');
+  return `---
+id: ${researchId}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(outline.name)}
+type: research
+research_type: ${researchType}
+scope: ${researchScope}
+status: open
+priority: 2
+owner: pwher
+created: "${now}"
+updated: "${now}"
+${enhancesLine}${sourcesBlock}
+${tagsBlock}
+related: []
+---
+
+# ${outline.name}
+
+_Research stub created by /hs-promote-capture from ${captureBasenames.length} capture${captureBasenames.length === 1 ? '' : 's'}. Each section header below is a placeholder — fill in the body during the research pass._
+
+## Conclusion & intended outcome
+
+<!-- The root outcome that milestones/epics/tasks spawned from this research refine — translate, don't copy ([[HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h]]). -->
+**Conclusion (one line):** _Acting on this research, what is the conclusion?_
+
+**What acting on this achieves:** _What changes for the user or system if we act on it? This is the outcome lower levels re-derive at their own altitude._
+
+## JTBD (job-to-be-done)
+
+<!-- Validated or revised by research — per [[research-capture-protocol]]'s "JTBD (job-to-be-done) framing" §JTBD-questioning section. State plainly whether research confirms the captured job or revises it, and why. -->
+${
+  jtbdSeed
+    ? `**Job, as captured (pending research validation):**\n${jtbdSeed}`
+    : '**Job, as captured:** _TBD — the source capture had no interim JTBD block; state the job this research serves._'
+}
+
+**Validated or revised by research:** _TBD — once research runs, state plainly whether it confirms this job or revises it (and what changed, if revised)._
+
+${sectionsBody}
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-capture (agent) | Created from ${captureBasenames.length} capture${captureBasenames.length === 1 ? '' : 's'}: ${captureBasenames.map((b) => `[[${b}]]`).join(', ')}. |
+`;
+}
+
+function buildUpdatedResearchContent(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) {
+    throw new Error('research has no frontmatter — cannot promote captures into it');
+  }
+  let block = fm.block;
+  let changed = false;
+  for (const basename of params.captureBasenames) {
+    const next = appendToListField(block, 'sources_captures', basename);
+    if (next.changed) changed = true;
+    block = next.block;
+  }
+  if (!changed) {
+    return { content: raw, changed: false };
+  }
+  block = bumpUpdated(block, params.now);
+  const change = `Added ${params.captureBasenames.length} capture source${params.captureBasenames.length === 1 ? '' : 's'} via /hs-promote-capture: ${params.captureBasenames
+    .map((b) => `[[${b}]]`)
+    .join(', ')}.${params.warningClosed ? ' (target was status: closed — append recorded on closed research.)' : ''}`;
+  const newBody = appendChangeLogRow(fm.body, params.today, params.author, change);
+  return { content: `${fm.open}${block}${fm.close}${newBody}`, changed: true };
+}
+
+function buildUpdatedCaptureContent(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) {
+    throw new Error('capture has no frontmatter — cannot link informs_research');
+  }
+  let block = fm.block;
+  let changed = false;
+  let setPromotedTo = false;
+
+  // 1. informs_research — always append (idempotent).
+  const informsResult = appendToListField(block, 'informs_research', params.researchBasename);
+  if (informsResult.changed) changed = true;
+  block = informsResult.block;
+
+  // 2. promoted_to — set only when currently null/absent (FIRST-promotion semantics).
+  const currentPromoted = getScalarField(block, 'promoted_to');
+  const isUnset =
+    currentPromoted === null ||
+    currentPromoted === 'null' ||
+    currentPromoted === '' ||
+    currentPromoted === '~';
+  if (isUnset) {
+    block = setScalarField(block, 'promoted_to', `"[[${params.researchBasename}]]"`);
+    setPromotedTo = true;
+    changed = true;
+  }
+
+  if (!changed) {
+    return { content: raw, changed: false, setPromotedTo: false };
+  }
+
+  block = bumpUpdated(block, params.now);
+  const fragments = ['Linked to research'];
+  fragments.push(`[[${params.researchBasename}]]`);
+  if (setPromotedTo) fragments.push('(first promotion — promoted_to set)');
+  const change = `${fragments.join(' ')} via /hs-promote-capture.`;
+  const newBody = appendChangeLogRow(fm.body, params.today, params.author, change);
+  return {
+    content: `${fm.open}${block}${fm.close}${newBody}`,
+    changed: true,
+    setPromotedTo,
+  };
+}
+
+async function runExecutePhase(args, ctx, deps) {
+  const now = (deps?.clock ?? isoNow)();
+  const today = now.slice(0, 10);
+  const author = 'promote-capture (agent)';
+
+  // ── Resolve / allocate target research basename + path ────────────────────
+  let researchBasename;
+  let researchAbsPath;
+  let researchRelPath;
+  let researchCreated = false;
+  let researchId;
+  let researchFileKey = null;
+  let researchFamilyKey = null;
+  let warningClosed = false;
+  let outlineForCreate = null;
+
+  if (ctx.targetResolution.mode === 'new') {
+    // Family inheritance (owner ruling 2026-07-12, see block comment above
+    // inheritedFamilyKey): the FIRST/primary source capture's family key wins
+    // unconditionally when several captures are promoted together —
+    // deterministic, mirrors the HS-MVC1 research_type suggestion precedent
+    // (ctx.captures[0]) just below. No fallback: era-3 `id:` keys onto the
+    // file key alone, so a shared family can never collide.
+    const primaryCapture = ctx.captures[0] ?? null;
+    researchFamilyKey =
+      (primaryCapture
+        ? inheritedFamilyKey(
+            primaryCapture.frontmatter?.id ?? null,
+            primaryCapture.frontmatter,
+            primaryCapture.basename,
+          )
+        : null) ?? mintFamilyKey(ctx.vaultRoot, { randomUnit: deps?.randomUnit });
+    // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+    // and (V3) the anchor for `id:` itself ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]).
+    researchFileKey = mintFileKey(ctx.vaultRoot, { randomUnit: deps?.randomUnit });
+    researchId = `HS-${researchFileKey}`;
+    const outlineName = args.accepted_outline?.name ?? args.new_research_name;
+    const slug = deriveSlug(outlineName);
+    researchBasename = `${researchId}-${researchFamilyKey}-RES-${slug}`;
+    researchAbsPath = join(
+      ctx.vaultRoot,
+      'specs',
+      'research',
+      `${researchBasename}.md`,
+    );
+    researchRelPath = join('specs', 'research', `${researchBasename}.md`);
+    researchCreated = true;
+
+    // Sanity: accepted_outline is required to actually create the file.
+    if (!args.accepted_outline) {
+      return {
+        error: 'NO_ACCEPTED_OUTLINE',
+        message:
+          'target_research is "NEW" but no accepted_outline was provided. Call the proposal phase first (omit accepted_outline) and confirm with the human.',
+      };
+    }
+    const baseOutline = {
+      name: args.accepted_outline.name.trim(),
+      outline: Array.isArray(args.accepted_outline.outline)
+        ? args.accepted_outline.outline.filter(
+            (s) => typeof s === 'string' && s.trim(),
+          )
+        : [],
+      tags: Array.isArray(args.accepted_outline.tags)
+        ? args.accepted_outline.tags.filter(
+            (t) => typeof t === 'string' && t.trim(),
+          )
+        : [],
+      // Raw passthrough — resolved (default/validated/suggestion-filled) by
+      // buildResearchStubContent via resolveResearchType(). When left null
+      // here (no explicit human choice), buildResearchStubContent's second
+      // resolveResearchType() arg receives a kind-derived suggestion
+      // computed just below (HS-MVC1) instead of falling straight to the
+      // blanket DEFAULT_RESEARCH_TYPE.
+      research_type:
+        typeof args.accepted_outline.research_type === 'string'
+          ? args.accepted_outline.research_type
+          : null,
+      // Raw passthrough — resolved (default/validated) by buildResearchStubContent
+      // via resolveResearchScope(). NOT required — a consistency fix only
+      // ([[HS-NGD1-TASK-consolidate-and-fix-the-research-scope-field]]).
+      scope:
+        typeof args.accepted_outline.scope === 'string' ? args.accepted_outline.scope : null,
+    };
+    if (baseOutline.outline.length === 0) {
+      baseOutline.outline = ['Executive Summary', 'Sources'];
+    }
+    outlineForCreate = baseOutline;
+  } else {
+    const r = ctx.targetResolution.research;
+    researchBasename = r.basename;
+    researchAbsPath = r.absPath;
+    researchRelPath = r.relPath;
+    researchId =
+      getScalarField(getFrontmatterBlock(r.raw)?.block ?? '', 'id') ?? researchBasename;
+    const status = getScalarField(
+      getFrontmatterBlock(r.raw)?.block ?? '',
+      'status',
+    );
+    if (status === 'closed') warningClosed = true;
+  }
+
+  // ── Stage writes ──────────────────────────────────────────────────────────
+  const writes = [];
+
+  const captureBasenames = ctx.captures.map((c) => c.basename);
+
+  // Tracks the research doc's body content as it will exist after this call
+  // (freshly created, freshly extended, or unchanged) so the success response
+  // can proactively report whether it is still an unresolved outline stub —
+  // see the `findUnresolvedResearchPlaceholders` import above.
+  let finalResearchContent = null;
+
+  if (researchCreated) {
+    const enhancesBasename = resolveEnhancesBasename(args);
+    // HS-MVC1: derive a kind→research_type suggestion from the FIRST source
+    // capture (deterministic — most promotions are single-capture; when
+    // multiple captures with differing kinds are promoted together, the
+    // first one's kind wins rather than attempting to merge/reconcile).
+    // An explicit outline.research_type still overrides this inside
+    // buildResearchStubContent's resolveResearchType() call.
+    const suggestedType =
+      ctx.captures.length > 0 ? suggestResearchType(ctx.captures[0].frontmatter?.kind) : null;
+    // HS-M1MW: seed the stub's JTBD section from the primary capture's
+    // interim `JTBD (job-to-be-done):` leading block, when present.
+    const jtbdSeed =
+      ctx.captures.length > 0 ? extractCaptureJtbd(ctx.captures[0].raw) : '';
+    const newContent = buildResearchStubContent(
+      researchId,
+      researchFileKey,
+      researchFamilyKey,
+      outlineForCreate,
+      captureBasenames,
+      enhancesBasename,
+      now,
+      suggestedType,
+      jtbdSeed,
+    );
+    writes.push({ kind: 'create', absPath: researchAbsPath, content: newContent });
+    finalResearchContent = newContent;
+  } else {
+    const updated = buildUpdatedResearchContent(
+      ctx.targetResolution.research.raw,
+      {
+        captureBasenames,
+        warningClosed,
+        now,
+        today,
+        author,
+      },
+    );
+    if (updated.changed) {
+      writes.push({
+        kind: 'update',
+        absPath: researchAbsPath,
+        content: updated.content,
+      });
+    }
+    finalResearchContent = updated.changed ? updated.content : ctx.targetResolution.research.raw;
+  }
+
+  // Proactive stub warning ([[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]]):
+  // mirrors RESEARCH_STILL_STUB's own placeholder count/language, surfaced here
+  // at creation/extension time instead of only reactively when
+  // `heyspex_promote_research` later refuses. Non-fatal — the write still
+  // proceeds; this only informs the caller what to do next.
+  const unresolvedPlaceholderCount = finalResearchContent
+    ? findUnresolvedResearchPlaceholders(finalResearchContent)
+    : 0;
+  const researchStillStub = unresolvedPlaceholderCount > 0;
+  const stubNextStep = researchStillStub
+    ? `This research doc is an outline of section headings only (${unresolvedPlaceholderCount} ` +
+      'unresolved "_TBD — fill in this section._" placeholder(s)) — not authored findings yet. ' +
+      'Run the /hs-res method against it (SpexCrawl gather via the Companion + DeepSeek synthesis) ' +
+      'before calling heyspex_promote_research; do NOT author the research yourself in the main ' +
+      'session — that skips the routed research seats.'
+    : undefined;
+
+  // Capture mutations.
+  const capturePromotionResults = [];
+  for (const c of ctx.captures) {
+    const updated = buildUpdatedCaptureContent(c.raw, {
+      researchBasename,
+      now,
+      today,
+      author,
+    });
+    capturePromotionResults.push({
+      capture_id: c.frontmatter?.id ?? c.basename,
+      capture_basename: c.basename,
+      informs_research_added: updated.changed,
+      promoted_to_set: updated.setPromotedTo,
+    });
+    if (updated.changed) {
+      writes.push({
+        kind: 'update',
+        absPath: c.absPath,
+        content: updated.content,
+      });
+    }
+  }
+
+  if (writes.length === 0) {
+    // Idempotent no-op: research already references every input capture and
+    // each capture already references the research. Surface this clearly.
+    return {
+      phase: 'executed',
+      research_id: researchId,
+      research_basename: researchBasename,
+      research_path: researchRelPath,
+      research_created: false,
+      captures: capturePromotionResults,
+      writes: [],
+      warning: warningClosed ? 'TARGET_RESEARCH_CLOSED' : undefined,
+      no_op: true,
+      human_review_required: false,
+      research_still_stub: researchStillStub,
+      unresolved_placeholder_count: unresolvedPlaceholderCount,
+      next_step: stubNextStep,
+    };
+  }
+
+  // ── Commit ────────────────────────────────────────────────────────────────
+  const commitResult = commitWrites(writes);
+  if (!commitResult.ok) {
+    return {
+      error: 'WRITE_FAILED',
+      message: commitResult.error?.message ?? 'unknown write failure',
+      rollback_error: commitResult.error?.rollbackError,
+    };
+  }
+
+  return {
+    phase: 'executed',
+    research_id: researchId,
+    research_basename: researchBasename,
+    research_path: researchRelPath,
+    research_created: researchCreated,
+    captures: capturePromotionResults,
+    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    // TARGET_RESEARCH_CLOSED only occurs on the existing-research branch
+    // (researchCreated === false). Family inheritance on the NEW-research
+    // branch no longer has a fallback case to warn about (era-3 minting —
+    // see the block comment above inheritedFamilyKey).
+    warning: warningClosed ? 'TARGET_RESEARCH_CLOSED' : undefined,
+    human_review_required: false,
+    // Proactive stub signal — same placeholder count RESEARCH_STILL_STUB would
+    // later refuse on, surfaced here instead of only reactively. See
+    // [[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]].
+    research_still_stub: researchStillStub,
+    unresolved_placeholder_count: unresolvedPlaceholderCount,
+    next_step: stubNextStep,
+  };
+}
+
+function resolveEnhancesBasename(args) {
+  if (!args.enhances) return null;
+  // Pass through a milestone id/basename of either ordering (validated upstream
+  // by isMilestoneId). A bare id relies on the caller supplying a real existing
+  // milestone basename when they need the link to survive the vault validator.
+  return args.enhances;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function executePromoteCapture(vaultRoot, args = {}, deps = {}) {
+  const validationError = validateInputShape(args);
+  if (validationError) return validationError;
+
+  // 1. Load every input capture; fail on first miss. Ids collapse to the
+  // short stored form first (display long `HS-XV4W-HV6H` → `HS-XV4W`) so the
+  // basename-prefix and frontmatter-id matches inside the loader hit for any
+  // pasted form — legacy `HS-CAP-*` ids pass through unchanged.
+  const captures = [];
+  for (const rawCaptureId of args.capture_ids) {
+    const captureId = shortLookupIdOf(rawCaptureId) ?? rawCaptureId;
+    const capture = findCaptureByIdLocal(vaultRoot, captureId);
+    if (!capture) {
+      return {
+        error: 'CAPTURE_NOT_FOUND',
+        message: `capture ${captureId} not found under specs/captures/`,
+      };
+    }
+    capture.frontmatter = {};
+    const fm = getFrontmatterBlock(capture.raw);
+    if (fm) {
+      capture.frontmatter.id = getScalarField(fm.block, 'id') ?? captureId;
+      capture.frontmatter.name = getScalarField(fm.block, 'name') ?? '';
+      // `family:` feeds the capture→research family-inheritance ruling
+      // ([[family-id-is-inherited-capture-research]]) — explicit frontmatter
+      // wins over the positional basename read inside inheritedFamilyKey.
+      capture.frontmatter.family = getScalarField(fm.block, 'family') ?? null;
+      // `kind:` drives the HS-MVC1 research_type suggestion below — read
+      // raw (unvalidated); an unrecognized/missing value safely falls back
+      // to the default inside suggestResearchType().
+      capture.frontmatter.kind = getScalarField(fm.block, 'kind') ?? null;
+    }
+    captures.push(capture);
+  }
+
+  // 1b. Sufficiency gate ([[HS-0CFX-TASK]]): an insufficient capture does not
+  // silently become research — the caller gets the missing elements as specific
+  // asks (elicit, improve the capture, re-promote), or overrides deliberately
+  // with `force_promote: true` (recorded in the response). Deterministic lexical
+  // scorer; injectable for tests via deps.scoreSufficiencyFn.
+  if (args.force_promote !== true) {
+    const scoreFn = deps.scoreSufficiencyFn ?? scoreSufficiency;
+    const insufficient = [];
+    for (const capture of captures) {
+      const fm = getFrontmatterBlock(capture.raw);
+      const body = fm ? fm.body : capture.raw;
+      // Already-expanded bypass ([[HS-55YM-DIAG]]): the gate's pre-expand,
+      // pipeline-entry rationale ([[HS-KNIF-TASK-BN60]] — catch weak,
+      // source-only input before an UNATTENDED pipeline expands it) does not
+      // apply once a human/agent has already grounded/expanded the capture —
+      // `## Expanded Concept` populated means real, reviewed content already
+      // exists, so re-blocking promotion here is not meaningful. Skip scoring
+      // entirely (no force_promote needed). Mirrored in
+      // spex-console/src/lib/capture-vault.ts's gateCapturePromotion — no
+      // drift between the two gate call sites.
+      if (extractCaptureExpandedConceptFromBody(body).trim().length > 0) {
+        continue;
+      }
+      const doc = {
+        frontmatter: { kind: capture.frontmatter?.kind ?? undefined },
+        body,
+      };
+      let suff;
+      try {
+        suff = scoreFn(doc);
+      } catch {
+        suff = { pass: false, score: 0, missing: ['*scorer-error*'] };
+      }
+      if (!suff?.pass) {
+        insufficient.push({
+          capture_id: capture.frontmatter?.id ?? 'unknown',
+          score: suff?.score ?? 0,
+          missing: suff?.missing ?? [],
+        });
+      }
+    }
+    if (insufficient.length > 0) {
+      return {
+        error: 'CAPTURE_INSUFFICIENT',
+        message:
+          'Promotion blocked: capture(s) below the sufficiency bar. Elicit the missing elements from the user (add them to the capture), then re-promote — or, if the human explicitly wants to proceed anyway, retry with force_promote: true.',
+        insufficient,
+        how_to_resolve:
+          'Missing element keys map to heyspex_update_capture arguments (call it with the SAME spec_id, then re-promote): core-idea → core_idea, example → example (label real examples "Real example:"), done-criteria → done_when (a "## Done When" checklist), kind → kind (a non-default classification: bug-fix/clip/reference/question), user-stories → user_stories. Elicit each from the user before writing it — do not invent content to pass the gate.',
+      };
+    }
+  }
+
+  // 2. Resolve target research.
+  let targetResolution;
+  if (args.target_research === 'NEW') {
+    targetResolution = { mode: 'new' };
+  } else {
+    const research = findResearchByIdLocal(
+      vaultRoot,
+      shortLookupIdOf(args.target_research) ?? args.target_research,
+    );
+    if (!research) {
+      return {
+        error: 'RESEARCH_NOT_FOUND',
+        message: `target_research ${args.target_research} not found under specs/research/`,
+      };
+    }
+    targetResolution = { mode: 'existing', research };
+  }
+
+  const ctx = { vaultRoot, captures, targetResolution };
+
+  // 3. Phase split.
+  //    - target_research === "NEW" + no accepted_outline → run AI proposer (Phase 1).
+  //    - existing target_research → skip AI, go straight to execute.
+  //    - target_research === "NEW" + accepted_outline → execute.
+  const wantsProposal =
+    targetResolution.mode === 'new' && !args.accepted_outline;
+  if (wantsProposal) {
+    return runProposalPhase(args, ctx, deps);
+  }
+
+  return runExecutePhase(args, ctx, deps);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Capture → DIAGNOSE promotion ([[HS-MIL-BFIX]]). A bug-report capture becomes a
+// first-class `HS-DIAG-*` diagnose spec (the executable bug fix). 1:1 (one
+// capture → one diagnose), no AI outline — simpler than research aggregation.
+// Reuses the same promotion-helpers + transactional commitWrites.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VALID_DIAGNOSE_SEVERITIES = new Set(['error', 'warning', 'info']);
+
+function collectOccupiedDiagnoseIds(vaultRoot) {
+  const occupied = new Set();
+  const dir = join(vaultRoot, 'specs', 'diagnoses');
+  if (!existsSync(dir)) return occupied;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const fromBasename = canonicalIdOfType(file.replace(/\.md$/, ''), 'DIAG');
+    if (fromBasename) occupied.add(fromBasename);
+    try {
+      const raw = readFileSync(join(dir, file), 'utf8');
+      const idMatch = raw.match(/^id:\s*(\S+)/m);
+      if (idMatch) {
+        const id = idMatch[1].replace(/^['"]|['"]$/g, '');
+        const fromId = canonicalIdOfType(id, 'DIAG');
+        if (fromId) occupied.add(fromId);
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return occupied;
+}
+
+/** Pull the `# Core Idea` paragraph from a v2 capture body as the bug symptom. */
+function extractCaptureCoreIdea(raw) {
+  const fm = getFrontmatterBlock(raw);
+  const body = fm ? fm.body : raw;
+  const m = body.match(/#\s*Core Idea\s*\n+([\s\S]*?)(?=\n#{1,6}\s|$)/i);
+  if (!m) return '';
+  return m[1].trim();
+}
+
+/**
+ * Pull the interim `JTBD (job-to-be-done):` leading block from a capture's
+ * `## Expanded Concept` section ([[research-capture-protocol]] §"JTBD
+ * (job-to-be-done) framing" — interim home until [[HS-TIE7-PR20-TASK-jtbd-job-to-be-done-field-on-captures]]
+ * ships a dedicated field). Returns '' when no such block is present so
+ * callers can fall back to a placeholder prompt.
+ */
+function extractCaptureJtbd(raw) {
+  const fm = getFrontmatterBlock(raw);
+  const body = fm ? fm.body : raw;
+  const section = body.match(/##\s*Expanded Concept\s*\n+([\s\S]*?)(?=\n#{1,6}\s|$)/i);
+  if (!section) return '';
+  const m = section[1].match(/JTBD\s*\(job-to-be-done\):\s*\n+((?:\s*-[^\n]*\n?)+)/i);
+  if (!m) return '';
+  return m[1].trim();
+}
+
+function buildDiagnoseContent(diagnoseId, fileKey, familyKey, name, severity, captureBasename, coreIdea, now) {
+  const today = now.slice(0, 10);
+  const symptom = coreIdea
+    ? coreIdea
+    : '_Describe the observed bug (promoted from the source capture below)._';
+  return `---
+id: ${diagnoseId}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: diagnose
+status: open
+severity: ${severity}
+owner: pwher
+created: "${now}"
+updated: "${now}"
+promoted_from: "[[${captureBasename}]]"
+tags:
+  - "bug-fix"
+related:
+  - "[[${captureBasename}]]"
+---
+
+# ${name}
+
+## Symptom
+
+${symptom}
+
+## Reproduction
+
+_TBD — steps to reproduce._
+
+${buildDiagnoseSkeletonSections()}
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-capture (agent) | Created from capture [[${captureBasename}]] via /hs-promote-capture (diagnose). |
+`;
+}
+
+/** Capture mutation for diagnose promotion: set promoted_to (first) + informs_diagnose. */
+function buildUpdatedCaptureContentForDiagnose(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) {
+    throw new Error('capture has no frontmatter — cannot link informs_diagnose');
+  }
+  let block = fm.block;
+  let changed = false;
+  let setPromotedTo = false;
+
+  const informsResult = appendToListField(block, 'informs_diagnose', params.diagnoseBasename);
+  if (informsResult.changed) changed = true;
+  block = informsResult.block;
+
+  const currentPromoted = getScalarField(block, 'promoted_to');
+  const isUnset =
+    currentPromoted === null ||
+    currentPromoted === 'null' ||
+    currentPromoted === '' ||
+    currentPromoted === '~';
+  if (isUnset) {
+    block = setScalarField(block, 'promoted_to', `"[[${params.diagnoseBasename}]]"`);
+    setPromotedTo = true;
+    changed = true;
+  }
+
+  if (!changed) return { content: raw, changed: false, setPromotedTo: false };
+
+  block = bumpUpdated(block, params.now);
+  const fragments = ['Promoted to diagnose', `[[${params.diagnoseBasename}]]`];
+  if (setPromotedTo) fragments.push('(first promotion — promoted_to set)');
+  const change = `${fragments.join(' ')} via /hs-promote-capture.`;
+  const newBody = appendChangeLogRow(fm.body, params.today, params.author, change);
+  return { content: `${fm.open}${block}${fm.close}${newBody}`, changed: true, setPromotedTo };
+}
+
+/**
+ * Promote a single capture into a new `HS-DIAG-*` diagnose spec. Single-phase
+ * (no AI outline): the capture's Core Idea seeds the Symptom; the rest is a
+ * fill-in skeleton. Bidirectional linkage: diagnose.promoted_from ⇔
+ * capture.promoted_to / informs_diagnose.
+ */
+export async function executePromoteCaptureToDiagnose(vaultRoot, args = {}, deps = {}) {
+  // Same any-form id tolerance as executePromoteCapture (owner ruling
+  // 2026-08-21): collapse a display/basename form to the stored short id.
+  const rawCaptureId = args.capture_id;
+  if (typeof rawCaptureId !== 'string' || (!isCaptureId(rawCaptureId) && !lookupFileKeyOf(rawCaptureId))) {
+    return { error: 'INVALID_CAPTURE_ID', message: 'capture_id must be a capture id (HS-<key>-CAP, legacy HS-CAP-<key>, or an era-3 id/basename carrying the file key)' };
+  }
+  const captureId = isCaptureId(rawCaptureId) ? rawCaptureId : (shortLookupIdOf(rawCaptureId) ?? rawCaptureId);
+  const severityRaw = typeof args.severity === 'string' ? args.severity.trim().toLowerCase() : 'warning';
+  const severity = VALID_DIAGNOSE_SEVERITIES.has(severityRaw) ? severityRaw : 'warning';
+
+  const capture = findCaptureByIdLocal(vaultRoot, captureId);
+  if (!capture) {
+    return { error: 'CAPTURE_NOT_FOUND', message: `capture ${captureId} not found under specs/captures/` };
+  }
+
+  const captureFm = getFrontmatterBlock(capture.raw);
+  const captureName = captureFm ? (getScalarField(captureFm.block, 'name') ?? '') : '';
+  const name = (typeof args.name === 'string' && args.name.trim())
+    ? args.name.trim()
+    : (captureName || `Bug from ${captureId}`).replace(/^Capture\s+/i, '');
+
+  const now = (deps?.clock ?? isoNow)();
+  const today = now.slice(0, 10);
+  const coreIdea = extractCaptureCoreIdea(capture.raw);
+
+  // A capture→diagnose promotion has no documented family-inheritance hop
+  // (unlike capture→research) — mints a fresh family, same as any other
+  // parentless spec.
+  const familyKey = mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit });
+  // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+  // and (V3) the anchor for `id:` itself.
+  const fileKey = mintFileKey(vaultRoot, { randomUnit: deps?.randomUnit });
+  const diagnoseId = `HS-${fileKey}`;
+  const slug = deriveSlug(name);
+  const diagnoseBasename = `${diagnoseId}-${familyKey}-DIAG-${slug}`;
+  const diagnoseRelPath = `specs/diagnoses/${diagnoseBasename}.md`;
+  const diagnoseAbsPath = join(vaultRoot, 'specs', 'diagnoses', `${diagnoseBasename}.md`);
+
+  const writes = [];
+  writes.push({
+    kind: 'create',
+    absPath: diagnoseAbsPath,
+    content: buildDiagnoseContent(diagnoseId, fileKey, familyKey, name, severity, capture.basename, coreIdea, now),
+  });
+
+  const captureUpdate = buildUpdatedCaptureContentForDiagnose(capture.raw, {
+    diagnoseBasename,
+    now,
+    today,
+    author: 'promote-capture (agent)',
+  });
+  if (captureUpdate.changed) {
+    writes.push({ kind: 'update', absPath: capture.absPath, content: captureUpdate.content });
+  }
+
+  const commitResult = commitWrites(writes);
+  if (!commitResult.ok) {
+    return {
+      error: 'WRITE_FAILED',
+      message: commitResult.error?.message ?? 'unknown write failure',
+      rollback_error: commitResult.error?.rollbackError,
+    };
+  }
+
+  return {
+    phase: 'executed',
+    diagnose_id: diagnoseId,
+    diagnose_basename: diagnoseBasename,
+    diagnose_path: diagnoseRelPath,
+    diagnose_created: true,
+    severity,
+    capture: {
+      capture_id: captureId,
+      capture_basename: capture.basename,
+      informs_diagnose_added: captureUpdate.changed,
+      promoted_to_set: captureUpdate.setPromotedTo,
+    },
+    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    human_review_required: false,
+  };
+}
+
+export const __testables = {
+  validateInputShape,
+  findCaptureByIdLocal,
+  findResearchByIdLocal,
+  findResearchByBasename,
+  collectOccupiedResearchIds,
+  collectOccupiedDiagnoseIds,
+  extractCaptureCoreIdea,
+  buildDiagnoseContent,
+  buildResearchStubContent,
+  buildUpdatedResearchContent,
+  buildUpdatedCaptureContent,
+  resolveEnhancesBasename,
+  resolveResearchType,
+  inheritedFamilyKey,
+};