heyspex 0.1.0

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

@@ -0,0 +1,187 @@
+/**
+ * `heyspex_promote_diagnose` — the breakdown stage, entered from a bug write-up.
+ *
+ * [[HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose]]: "Breakdown accepts a
+ * research doc or a bug write-up. Not a second parallel tool." So this module is
+ * deliberately thin — it is the diagnose-shaped FRONT DOOR onto machinery that is
+ * shared with the research path:
+ *
+ *   - finding + identifying the source   → `breakdown-source.mjs`   ([[HS-K1TR]])
+ *   - grounding + the fix-count ladder   → `breakdown-ladder.mjs`   ([[HS-EYJ3]])
+ *   - placement + the writes             → this module + `promotion-helpers.mjs` ([[HS-FLGU]])
+ *   - links, never parenting             → ([[HS-ZTZG]])
+ *
+ * The one thing NOT shared with the research path is the sizing input: a research doc
+ * is sized by an AI stub proposer, a bug write-up is sized by counting the
+ * separately-verifiable fixes its own `## Fix` section already lists. "AI deciding
+ * the size" is explicitly out of scope for the epic — the count is authored by
+ * whoever ran the investigation.
+ *
+ * ORDER MATTERS. Grounding runs BEFORE sizing, and its result is reported in both
+ * phases. Sizing first is what produced seven near-miss fixes next to a milestone
+ * and an epic that had been sitting open the whole time
+ * ([[HS-WZ62-JJIP-DIAG-console-loads-the-whole-vault-as-one-5]]).
+ */
+
+import { readSourceFrontmatter, resolveBreakdownSource } from './breakdown-source.mjs';
+import { applyLadder, causeIsKnown, scanExistingCoverage } from './breakdown-ladder.mjs';
+import { executeBreakdownWrites } from './breakdown-writer.mjs';
+
+/** Rungs that produce no work at all — the stage reports and writes nothing. */
+const NO_SPAWN_RUNGS = new Set(['no_breakdown', 'no_fixes_listed']);
+
+/**
+ * Render the "attach, don't mint" recommendation from the coverage scan.
+ *
+ * Placement goes DOWN, never up (epic §Scope): a matching epic gets tasks, a matching
+ * milestone with no fitting epic gets a new epic, and only when neither exists is a
+ * milestone proposed — which asks the owner first.
+ */
+export function recommendPlacement(coverage) {
+  const epic = coverage?.epics?.[0];
+  const milestone = coverage?.milestones?.[0];
+  if (epic) {
+    return {
+      placement: 'tasks_under_epic',
+      attach_to: epic.basename,
+      recommendation: `Attach to the existing open epic [[${epic.basename}]] (matched on ${epic.matched_terms.join(', ')}) — file the fixes as TASKS under it. Do not mint a new epic or milestone.`,
+      owner_confirmation_required: false,
+    };
+  }
+  if (milestone) {
+    return {
+      placement: 'epic_under_milestone',
+      attach_to: milestone.basename,
+      recommendation: `Attach to the existing open milestone [[${milestone.basename}]] (matched on ${milestone.matched_terms.join(', ')}) — file ONE new epic under it. Do not mint a new milestone.`,
+      owner_confirmation_required: false,
+    };
+  }
+  return {
+    placement: 'new_milestone',
+    attach_to: null,
+    recommendation:
+      'No open milestone or epic covers this area, so a new milestone is proposed. This is the only rung that mints one, and the owner confirms before anything is filed.',
+    owner_confirmation_required: true,
+  };
+}
+
+/**
+ * @param {{ vaultRoot: string, args?: Record<string, unknown>, deps?: Record<string, unknown> }} ctx
+ */
+export async function executePromoteDiagnose({ vaultRoot, args = {}, deps = {} }) {
+  const ref = args.diagnose_id ?? args.source_id ?? args.spec_id;
+  const resolved = resolveBreakdownSource(vaultRoot, ref, { kinds: ['diagnose'] });
+  if (resolved.error) {
+    // `INVALID_ARGS` from the shared resolver names no field — say which one.
+    if (resolved.error === 'INVALID_ARGS') {
+      return { error: 'INVALID_ARGS', message: 'diagnose_id is required' };
+    }
+    return resolved;
+  }
+
+  const source = resolved.record;
+  const frontmatter = readSourceFrontmatter(source);
+
+  // ── Step one: GROUND. What already covers this area? ──────────────────────
+  const coverage = scanExistingCoverage(vaultRoot, source);
+
+  // ── Step two: SIZE. Count the fixes the write-up itself lists. ────────────
+  const ladder = applyLadder({
+    raw: source.raw,
+    coverage,
+    causeKnown: causeIsKnown(source.raw),
+  });
+
+  const base = {
+    source_kind: source.kind,
+    source_id: frontmatter.id,
+    source_basename: source.basename,
+    source_path: source.relPath,
+    source_title: frontmatter.name,
+    source_status: frontmatter.status,
+    existing_coverage: coverage,
+    ladder,
+  };
+
+  if (NO_SPAWN_RUNGS.has(ladder.rung)) {
+    return {
+      ...base,
+      phase: 'no_breakdown',
+      spawns: [],
+      human_review_required: false,
+      message: ladder.reason,
+    };
+  }
+
+  if (ladder.rung === 'measure_first') {
+    // The hold still gets grounding: the measurement task needs an epic to live
+    // under, and the coverage scan is where that epic comes from.
+    const measurePlacement = {
+      placement: 'measure_first',
+      attach_to: coverage.epics?.[0]?.basename ?? null,
+      recommendation: ladder.reason,
+      owner_confirmation_required: false,
+    };
+    if (args.accepted !== true) {
+      return {
+        ...base,
+        phase: 'measure_first',
+        placement: measurePlacement,
+        human_review_required: true,
+        message: ladder.reason,
+      };
+    }
+    const measured = executeBreakdownWrites({
+      vaultRoot,
+      source,
+      sourceFrontmatter: frontmatter,
+      ladder,
+      placement: measurePlacement,
+      args,
+      deps,
+    });
+    if (measured.error) return { ...base, placement: measurePlacement, ...measured };
+    return {
+      ...base,
+      phase: 'executed',
+      placement: measurePlacement,
+      spawns: measured.spawned,
+      writes: measured.writes,
+      human_review_required: false,
+      message: ladder.reason,
+    };
+  }
+
+  const placement = recommendPlacement(coverage);
+
+  if (args.accepted !== true) {
+    return {
+      ...base,
+      phase: 'review',
+      placement,
+      human_review_required: true,
+      next_call_hint:
+        'Review the existing coverage and the ladder result above, then call again with `accepted: true` (plus `confirm_new_milestone: true` when the placement is new_milestone) to execute the writes.',
+    };
+  }
+
+  const written = executeBreakdownWrites({
+    vaultRoot,
+    source,
+    sourceFrontmatter: frontmatter,
+    ladder,
+    placement,
+    args,
+    deps,
+  });
+  if (written.error) return { ...base, placement, ...written };
+
+  return {
+    ...base,
+    phase: 'executed',
+    placement,
+    spawns: written.spawned,
+    writes: written.writes,
+    human_review_required: false,
+  };
+}

package/vendor/heyspex-mcp/promote-research-to-diagnose.mjs

@@ -0,0 +1,338 @@
+/**
+ * `heyspex_promote_research_to_diagnose` MCP tool — research → diagnose
+ * intake edge ([[HS-MSHY-TASK-research-diagnose-link-send-bugs-to-the]] of
+ * [[HS-MSHY-EPIC-research-to-diagnose-link-send-bugs-foun]]).
+ *
+ * Symmetric to `heyspex_promote_capture_to_diagnose` (promote-capture.mjs)
+ * but sourced from a research investigation instead of a bug-report capture:
+ * a research doc that surfaced a bug is promoted into a new first-class
+ * `HS-DIAG-*` diagnose spec (specs/diagnoses/) — reusing the existing
+ * diagnose machinery, no new infrastructure. Single-phase (no AI outline):
+ * the research's `## Executive Summary` (falling back to the research
+ * `name:`) seeds the diagnose `## Symptom`; Reproduction/Root cause/Fix/
+ * Acceptance criteria are fill-in skeletons, same shape as the capture path.
+ *
+ * Bidirectional linkage (mirrors `spawned_epics` ⇔ `epic.derived_from` per
+ * [[entity-model]] §Provenance edges):
+ *   research.produces_diagnose : appended with the new diagnose wikilink (1:N)
+ *   diagnose.derived_from      : set to the source research wikilink (single)
+ *
+ * Duplicate-promotion guard: unlike a capture (which is single-shot and
+ * discarded after use), a research doc is evergreen and may surface several
+ * *different* bugs over its life — so the guard is keyed on (research_id,
+ * diagnose name/slug), not on "has this research ever produced a diagnose."
+ * Re-running with the same research_id + name that already produced a
+ * diagnose from this exact research is rejected as
+ * `DIAGNOSE_ALREADY_PROMOTED` (idempotent no-op — no new file written),
+ * matching the "no duplicate epic spawn" spirit of
+ * `RESEARCH_ALREADY_PROMOTED` in promote-research.mjs.
+ *
+ * All writes commit transactionally via the shared `commitWrites` helper
+ * from `./promotion-helpers.mjs`; any failure rolls back.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
+import { familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { buildDiagnoseSkeletonSections } from './diagnose-skeleton.mjs';
+import {
+  isoNow,
+  deriveSlug,
+  findFileByPrefix,
+  getFrontmatterBlock,
+  getScalarField,
+  parseListFieldBasenames,
+  appendToListField,
+  bumpUpdated,
+  appendChangeLogRow,
+  commitWrites,
+} from './promotion-helpers.mjs';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dual-read id classification ([[HS-MIL-KY1F]] family-first migration) —
+// mirrors promote-capture.mjs / split-research.mjs; each promotion module
+// keeps its own small local copy rather than sharing across modules.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function hasTypeLabel(id, label) {
+  const p = parseSpecId(id);
+  return !!p && p.typeLabel === label;
+}
+
+const isResearchId = (id) => hasTypeLabel(id, 'RES');
+
+function canonicalIdOfType(value, label) {
+  const p = parseSpecId(value);
+  if (!p || p.typeLabel !== label) return null;
+  return `HS-${p.familyKey}-${p.typeLabel}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File loaders
+// ─────────────────────────────────────────────────────────────────────────────
+
+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) return tryFile(file);
+    }
+  }
+  return null;
+}
+
+function findDiagnoseByBasename(vaultRoot, basename) {
+  const absPath = join(vaultRoot, 'specs', 'diagnoses', `${basename}.md`);
+  if (!existsSync(absPath)) return null;
+  return {
+    basename,
+    absPath,
+    relPath: join('specs', 'diagnoses', `${basename}.md`),
+    raw: readFileSync(absPath, 'utf8'),
+  };
+}
+
+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 `## Executive Summary` section from a research body as the bug symptom. */
+function extractResearchExecutiveSummary(raw) {
+  const fm = getFrontmatterBlock(raw);
+  const body = fm ? fm.body : raw;
+  const m = body.match(/##\s*Executive Summary\s*\n+([\s\S]*?)(?=\n#{1,6}\s|$)/i);
+  if (!m) return '';
+  return m[1].trim();
+}
+
+const VALID_DIAGNOSE_SEVERITIES = new Set(['error', 'warning', 'info']);
+
+function buildDiagnoseContent(diagnoseId, fileKey, familyKey, name, severity, researchBasename, symptomSeed, now) {
+  const today = now.slice(0, 10);
+  const symptom = symptomSeed
+    ? symptomSeed
+    : '_Describe the observed bug (promoted from the source research below)._';
+  return `---
+id: ${diagnoseId}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: diagnose
+status: open
+severity: ${severity}
+owner: pwher
+created: "${now}"
+updated: "${now}"
+derived_from: "[[${researchBasename}]]"
+tags:
+  - "bug-fix"
+related:
+  - "[[${researchBasename}]]"
+---
+
+# ${name}
+
+## Symptom
+
+${symptom}
+
+## Reproduction
+
+_TBD — steps to reproduce._
+
+${buildDiagnoseSkeletonSections()}
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-research-to-diagnose (agent) | Created from research [[${researchBasename}]] via heyspex_promote_research_to_diagnose. |
+`;
+}
+
+/** Research mutation: append produces_diagnose (idempotent) + change-log row. */
+function buildUpdatedResearchContent(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) {
+    throw new Error('research has no frontmatter — cannot link produces_diagnose');
+  }
+  let block = fm.block;
+  const result = appendToListField(block, 'produces_diagnose', params.diagnoseBasename);
+  if (!result.changed) return { content: raw, changed: false };
+  block = result.block;
+  block = bumpUpdated(block, params.now);
+  const change = `Promoted to diagnose [[${params.diagnoseBasename}]] via heyspex_promote_research_to_diagnose.`;
+  const newBody = appendChangeLogRow(fm.body, params.today, params.author, change);
+  return { content: `${fm.open}${block}${fm.close}${newBody}`, changed: true };
+}
+
+/**
+ * Promote a research investigation into a new `HS-DIAG-*` diagnose spec.
+ * Single-phase (no AI outline): the research's Executive Summary seeds the
+ * Symptom; the rest is a fill-in skeleton. Bidirectional linkage:
+ * research.produces_diagnose ⇔ diagnose.derived_from.
+ */
+export async function executePromoteResearchToDiagnose(vaultRoot, args = {}, deps = {}) {
+  const researchId = args.research_id;
+  if (typeof researchId !== 'string' || !isResearchId(researchId)) {
+    return { error: 'INVALID_RESEARCH_ID', message: 'research_id must be a research id (HS-<key>-RES, or legacy HS-RES-<key>)' };
+  }
+  const severityRaw = typeof args.severity === 'string' ? args.severity.trim().toLowerCase() : 'warning';
+  const severity = VALID_DIAGNOSE_SEVERITIES.has(severityRaw) ? severityRaw : 'warning';
+
+  const research = findResearchByIdLocal(vaultRoot, researchId);
+  if (!research) {
+    return { error: 'RESEARCH_NOT_FOUND', message: `research ${researchId} not found under specs/research/` };
+  }
+
+  const researchFm = getFrontmatterBlock(research.raw);
+  if (!researchFm) {
+    return { error: 'RESEARCH_FRONTMATTER_MISSING', message: 'research has no frontmatter' };
+  }
+  const researchName = getScalarField(researchFm.block, 'name') ?? '';
+  const name = (typeof args.name === 'string' && args.name.trim())
+    ? args.name.trim()
+    : (researchName || `Bug from ${researchId}`);
+  const slug = deriveSlug(name);
+
+  // Duplicate-promotion guard: same research + same diagnose name/slug that
+  // was already produced from THIS research is rejected, not re-created.
+  // (A research doc may legitimately spawn several *different* diagnoses
+  // over its evergreen life — the guard is per-name, not "any diagnose ever".)
+  const existingProduced = parseListFieldBasenames(researchFm.block, 'produces_diagnose') ?? [];
+  for (const diagBasename of existingProduced) {
+    if (!diagBasename.endsWith(`-${slug}`)) continue;
+    const existingDiagnose = findDiagnoseByBasename(vaultRoot, diagBasename);
+    if (!existingDiagnose) continue;
+    const existingDiagnoseFm = getFrontmatterBlock(existingDiagnose.raw);
+    const derivedFrom = existingDiagnoseFm ? getScalarField(existingDiagnoseFm.block, 'derived_from') : null;
+    const derivedFromBasename = derivedFrom ? derivedFrom.replace(/^\[\[|\]\]$/g, '') : null;
+    if (derivedFromBasename === research.basename) {
+      return {
+        error: 'DIAGNOSE_ALREADY_PROMOTED',
+        message: `research ${researchId} already produced [[${diagBasename}]] for a diagnose named "${name}" — re-running would create a duplicate. Use a different name for a genuinely new bug, or edit the existing diagnose directly.`,
+        existing_diagnose_basename: diagBasename,
+        existing_diagnose_path: existingDiagnose.relPath,
+      };
+    }
+  }
+
+  const now = (deps?.clock ?? isoNow)();
+  const today = now.slice(0, 10);
+  const symptomSeed = extractResearchExecutiveSummary(research.raw);
+
+  // Era-3 family inheritance ([[naming-v3-7-rulings-hs-namespace-kept]]): the
+  // diagnose inherits the SOURCE RESEARCH DOC's family (familyOf: explicit
+  // `family:` frontmatter wins, else positional from id/basename). The legacy
+  // allocator's `HS-<family>-DIAG` draw is only the defensive fallback family
+  // source; `id:` keys onto the file key alone.
+  const researchFmId = getScalarField(researchFm.block, 'id')?.replace(/^['"]|['"]$/g, '') ?? null;
+  const researchFamilyValue = getScalarField(researchFm.block, 'family')?.replace(/^['"]|['"]$/g, '') ?? null;
+  const familyKey =
+    familyOf({
+      id: researchFmId,
+      basename: research.basename,
+      frontmatter: { family: researchFamilyValue },
+    }) ??
+    parseSpecId(
+      allocateRandomVaultId('diagnose', collectOccupiedDiagnoseIds(vaultRoot), { randomUnit: deps?.randomUnit }),
+    )?.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 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, research.basename, symptomSeed, now),
+  });
+
+  const researchUpdate = buildUpdatedResearchContent(research.raw, {
+    diagnoseBasename,
+    now,
+    today,
+    author: 'promote-research-to-diagnose (agent)',
+  });
+  if (researchUpdate.changed) {
+    writes.push({ kind: 'update', absPath: research.absPath, content: researchUpdate.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,
+    research: {
+      research_id: researchId,
+      research_basename: research.basename,
+      produces_diagnose_added: researchUpdate.changed,
+    },
+    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    human_review_required: false,
+  };
+}
+
+export const __testables = {
+  findResearchByIdLocal,
+  findDiagnoseByBasename,
+  collectOccupiedDiagnoseIds,
+  extractResearchExecutiveSummary,
+  buildDiagnoseContent,
+  buildUpdatedResearchContent,
+  isResearchId,
+};