heyspex 0.1.0

package/vendor/heyspex-mcp/breakdown-ladder.mjs

@@ -0,0 +1,309 @@
+/**
+ * Ground first, then size — the two decisions the breakdown stage makes before it
+ * writes anything ([[HS-EYJ3]] of [[HS-ALBV]]).
+ *
+ * **Ground before sizing.** Epic §Scope: "Step one searches for an open milestone or
+ * epic already covering the area — not 'how big is this'." The worked case is
+ * [[HS-WZ62-JJIP-DIAG-console-loads-the-whole-vault-as-one-5]]: it reads
+ * milestone-sized, and both the milestone AND the epic that own it already existed,
+ * open and untouched since 2026-05-31, while seven separate fixes landed nearby and
+ * missed it. Sizing first is what produced those seven.
+ *
+ * **Count fixes, not length.** The size test counts things that can be verified
+ * separately, taken from what survives the write-up's own `## Fix` section. One fix
+ * means no breakdown at all — claim the write-up and fix it, exactly as today. "AI
+ * deciding the size" is explicitly out of scope for the epic: the count is authored
+ * by whoever ran the investigation, and this module only reads what they wrote.
+ *
+ * PURE + DETERMINISTIC. Lexical matching only, no AI, no network. Same posture as
+ * the scheduler: a human-reviewable rule, not a score
+ * ([[HS-8CD6-KF00-RES-unified-quality-signals-triage-as-the-on]]).
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getFrontmatterBlock, getScalarField } from './promotion-helpers.mjs';
+
+/**
+ * Statuses a candidate must NOT be in to count as covering the area. Mirrors the
+ * scheduler's claim-terminal set: attaching new work to a closed or cancelled
+ * container is how a "match" becomes a dead end.
+ */
+export const COVERAGE_ELIGIBLE_STATUSES = new Set(['open', 'in_progress']);
+
+/**
+ * Words that carry no subject. Without this the overlap scan matches every spec in
+ * the vault on "the", "console", "a" and ranks noise at the top, which reads as a
+ * confident answer and is worse than reporting nothing.
+ */
+const STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'for', 'from', 'has', 'have',
+  'in', 'into', 'is', 'it', 'its', 'not', 'of', 'on', 'one', 'or', 'that', 'the', 'their',
+  'then', 'there', 'these', 'they', 'this', 'to', 'was', 'were', 'when', 'which', 'while',
+  'with', 'without', 'all', 'any', 'can', 'cannot', 'no', 'only', 'out', 'over', 'so',
+  'than', 'up', 'via', 'we', 'what', 'why', 'you', 'your', 'hs', 'spec', 'specs',
+]);
+
+/** Lowercased alphanumeric terms of length ≥ 3 that are not stopwords. */
+export function terms(text) {
+  if (typeof text !== 'string') return [];
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+
+function frontmatterOf(raw) {
+  return getFrontmatterBlock(raw)?.block ?? '';
+}
+
+function listField(block, field) {
+  // Tags are a block list of bare scalars (not wikilinks), so parse them directly.
+  const headRe = new RegExp(`^${field}:[ \\t]*\\r?\\n`, 'm');
+  const head = block.match(headRe);
+  if (!head) {
+    const inline = getScalarField(block, field);
+    if (!inline || inline === '[]') return [];
+    return inline
+      .replace(/^\[|\]$/g, '')
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+  const rest = block.slice(head.index + head[0].length).split(/\r?\n/);
+  const out = [];
+  for (const line of rest) {
+    const m = line.match(/^[ \t]+-[ \t]*(.*)$/);
+    if (!m) break;
+    const v = m[1].trim().replace(/^['"]|['"]$/g, '');
+    if (v) out.push(v);
+  }
+  return out;
+}
+
+/** The searchable text of one spec: its name, its tags, and its summary. */
+function subjectText(block, fallbackName) {
+  return [
+    getScalarField(block, 'name') ?? fallbackName ?? '',
+    listField(block, 'tags').join(' '),
+    getScalarField(block, 'summary') ?? '',
+  ].join(' ');
+}
+
+function scanDir(vaultRoot, dirParts, type) {
+  const dir = join(vaultRoot, ...dirParts);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.toLowerCase().endsWith('.md')) continue;
+    let raw;
+    try {
+      raw = readFileSync(join(dir, file), 'utf8');
+    } catch {
+      continue;
+    }
+    const block = frontmatterOf(raw);
+    if (!block) continue;
+    const status = (getScalarField(block, 'status') ?? 'open').trim().toLowerCase();
+    if (!COVERAGE_ELIGIBLE_STATUSES.has(status)) continue;
+    if ((getScalarField(block, 'archived') ?? '').trim().toLowerCase() === 'true') continue;
+    if ((getScalarField(block, 'canonical') ?? '').trim().toLowerCase() === 'false') continue;
+    const basename = file.replace(/\.md$/i, '');
+    out.push({
+      type,
+      id: getScalarField(block, 'id') ?? basename,
+      basename,
+      name: getScalarField(block, 'name') ?? basename,
+      status,
+      milestone: getScalarField(block, 'milestone') ?? null,
+      terms: new Set(terms(subjectText(block, basename))),
+    });
+  }
+  return out;
+}
+
+/**
+ * What already covers this area?
+ *
+ * Returns `{ milestones, epics }`, each ranked by how many of the source's own
+ * subject terms they share, and each hit NAMING the matched terms so a human can
+ * judge the match rather than trusting a number. Ties break on basename so the
+ * result is deterministic across runs.
+ *
+ * A hit needs at least `minOverlap` shared terms (default 2). One shared word is a
+ * coincidence at vault scale, and a coincidence presented as coverage is what would
+ * attach a bug fix to the wrong epic.
+ */
+export function scanExistingCoverage(vaultRoot, source, opts = {}) {
+  const minOverlap = Number.isFinite(opts.minOverlap) ? opts.minOverlap : 2;
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 5;
+
+  const block = frontmatterOf(source?.raw ?? '');
+  const sourceTerms = new Set(terms(subjectText(block, source?.basename)));
+  if (sourceTerms.size === 0) return { milestones: [], epics: [], source_terms: [] };
+
+  const rank = (candidates) =>
+    candidates
+      .map((c) => {
+        const matched = [...sourceTerms].filter((t) => c.terms.has(t)).sort();
+        return {
+          type: c.type,
+          id: c.id,
+          basename: c.basename,
+          name: c.name,
+          status: c.status,
+          milestone: c.milestone,
+          matched_terms: matched,
+          overlap: matched.length,
+        };
+      })
+      .filter((c) => c.overlap >= minOverlap)
+      .sort((a, b) => b.overlap - a.overlap || a.basename.localeCompare(b.basename))
+      .slice(0, limit);
+
+  return {
+    source_terms: [...sourceTerms].sort(),
+    milestones: rank(scanDir(vaultRoot, ['specs', 'milestones'], 'milestone')),
+    epics: rank(scanDir(vaultRoot, ['specs', 'epics'], 'epic')),
+  };
+}
+
+/**
+ * Extract the source's own `## Fix` section, verbatim. Returns `''` when there is
+ * none — a write-up with no Fix section has not been investigated far enough to be
+ * broken down, and the ladder says so rather than guessing.
+ */
+export function fixSection(raw) {
+  const body = getFrontmatterBlock(raw)?.body ?? raw ?? '';
+  // No `m` flag on purpose: with it, `$` matches every LINE end, so the lazy capture
+  // terminates on the first newline and the section always comes back empty.
+  const m = body.match(/(?:^|\n)##[ \t]+Fix[^\n]*\n([\s\S]*?)(?=\n##[ \t]|$)/i);
+  return m ? m[1] : '';
+}
+
+/**
+ * The separately-verifiable fixes the write-up itself lists.
+ *
+ * Three spellings are counted, because all three are in the vault today and which
+ * one a write-up used says nothing about how many fixes it has:
+ *   - numbered list items (`1.`, `2)`)
+ *   - checklist items (`- [ ]`, `* [x]`)
+ *   - `###` sub-headings inside the Fix section
+ *
+ * Whichever spelling the section actually uses wins, in that order — a section with
+ * sub-headings AND a numbered list under each would otherwise count the same fix
+ * twice. Plain bullets are NOT counted: they are how a Fix section carries notes,
+ * and counting them turned prose into a milestone in the shape this epic exists to
+ * prevent.
+ */
+export function countFixes(raw) {
+  const section = fixSection(raw);
+  if (!section.trim()) return { fixes: [], style: 'none' };
+
+  const lines = section.split(/\r?\n/);
+  const grab = (re) =>
+    lines
+      .map((l) => l.match(re))
+      .filter(Boolean)
+      .map((m) => m[1].trim())
+      .filter(Boolean);
+
+  const subheadings = grab(/^###+[ \t]+(.*)$/);
+  if (subheadings.length > 0) return { fixes: subheadings, style: 'subheading' };
+
+  const checklist = grab(/^[ \t]*[-*][ \t]*\[[ xX]\][ \t]*(.*)$/);
+  if (checklist.length > 0) return { fixes: checklist, style: 'checklist' };
+
+  const numbered = grab(/^[ \t]*\d+[.)][ \t]+(.*)$/);
+  if (numbered.length > 0) return { fixes: numbered, style: 'numbered' };
+
+  return { fixes: [], style: 'prose' };
+}
+
+/**
+ * The sizing ladder.
+ *
+ * Three rungs, decided by the FIX COUNT and the coverage scan — never by body
+ * length, word count, or a model:
+ *
+ *   1 fix                          → `no_breakdown`  (claim the write-up and fix it)
+ *   2+ fixes, coverage found       → `epic`          (attach downward — tasks under
+ *                                                     the epic, or a new epic under
+ *                                                     the milestone)
+ *   2+ fixes, no coverage at all   → `milestone`     (owner confirms before filing)
+ *
+ * `measure_first` outranks all three: when the write-up's own conclusion is that the
+ * cause is not yet known, the only thing filed is the measurement.
+ */
+export function applyLadder({ raw, coverage, causeKnown = true }) {
+  const { fixes, style } = countFixes(raw);
+  const hasMilestone = (coverage?.milestones?.length ?? 0) > 0;
+  const hasEpic = (coverage?.epics?.length ?? 0) > 0;
+
+  const base = {
+    fix_count: fixes.length,
+    fixes,
+    fix_style: style,
+    counted_from: "the write-up's own ## Fix section",
+    coverage_found: { milestone: hasMilestone, epic: hasEpic },
+  };
+
+  if (!causeKnown) {
+    return {
+      ...base,
+      rung: 'measure_first',
+      reason:
+        "The write-up's own conclusion is that the cause is not yet known. File only the measurement; nothing else is broken down until it lands.",
+    };
+  }
+
+  if (fixes.length === 0) {
+    return {
+      ...base,
+      rung: 'no_fixes_listed',
+      reason:
+        'The `## Fix` section lists no separately-verifiable fixes (numbered items, checklist items, or ### sub-headings). Write the fixes the investigation found, then re-run — the count is authored, never inferred.',
+    };
+  }
+
+  if (fixes.length === 1) {
+    return {
+      ...base,
+      rung: 'no_breakdown',
+      reason: `One fix (${fixes[0]}) — claim the write-up and fix it directly, exactly as today. No breakdown.`,
+    };
+  }
+
+  if (hasEpic || hasMilestone) {
+    return {
+      ...base,
+      rung: 'epic',
+      reason: `${fixes.length} separately-verifiable fixes, and open ${hasEpic ? 'epic' : 'milestone'} coverage already exists — place the work under what is already there rather than minting a milestone.`,
+    };
+  }
+
+  return {
+    ...base,
+    rung: 'milestone',
+    reason: `${fixes.length} separately-verifiable fixes and no open milestone or epic covers this area — a new milestone is proposed, and the owner confirms before anything is filed.`,
+  };
+}
+
+/**
+ * Does the write-up conclude the cause is not yet known?
+ *
+ * Read from the write-up's OWN `## Root cause` section — the measure-first hold is
+ * the author's conclusion, not a guess about how confident their prose sounds. An
+ * empty or missing Root cause section is NOT taken as unknown: plenty of one-fix
+ * write-ups leave it empty, and holding those would stall the common path.
+ */
+export function causeIsKnown(raw) {
+  const body = getFrontmatterBlock(raw)?.body ?? raw ?? '';
+  const m = body.match(/(?:^|\n)##[ \t]+Root cause[^\n]*\n([\s\S]*?)(?=\n##[ \t]|$)/i);
+  const section = (m ? m[1] : '').trim();
+  if (!section) return true;
+  return !/\b(not yet known|cause is unknown|unknown cause|cause unknown|needs? measurement|measure first|not established)\b/i.test(
+    section,
+  );
+}

package/vendor/heyspex-mcp/breakdown-source.mjs

@@ -0,0 +1,236 @@
+/**
+ * The breakdown stage's INPUT side — one door, two kinds of document.
+ *
+ * [[HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose]] §Scope: "One stage, two
+ * inputs. Breakdown accepts a research doc or a bug write-up. Not a second parallel
+ * tool." A capture promotes to one or the other, so both sit at the same point in
+ * the line; the stage that already turns a research doc into a milestone and epics
+ * takes a second input type rather than getting a twin built beside it.
+ *
+ * This module is the half that finds and identifies the document. It was extracted
+ * verbatim from `promote-research.mjs`'s private `resolveResearchRef` /
+ * `findResearchByIdLocal` — the research path now calls in here, so the two inputs
+ * cannot drift apart on how a reference resolves.
+ *
+ * RESOLUTION-FIRST, then a type gate. No id-shape pattern-match is applied to the
+ * caller's string: a real vault id may be a bare era-3 file key (`HS-X5FH`) that
+ * carries no `RES` / `DIAG` label at all, and rejecting on shape made every research
+ * doc unpromotable once ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]).
+ * The "what kind of document is this?" question is answered by the resolved FILE's
+ * own `type:` frontmatter.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getFrontmatterBlock, getScalarField } from './promotion-helpers.mjs';
+
+/**
+ * The kinds of document the breakdown stage accepts, and the folder each lives in.
+ *
+ * Adding a row here is the whole cost of a third input kind — the resolver, the
+ * type gate, and every error message read from this table.
+ */
+export const BREAKDOWN_SOURCE_KINDS = {
+  research: { dir: ['specs', 'research'], label: 'research doc' },
+  diagnose: { dir: ['specs', 'diagnoses'], label: 'bug write-up' },
+};
+
+/**
+ * Normalize a caller-supplied reference to a bare id/basename: trims, drops
+ * surrounding quotes, unwraps a `[[wikilink]]`, strips a trailing `.md`. Returns
+ * `null` for anything that normalizes to empty.
+ */
+export function normalizeSourceRef(raw) {
+  if (typeof raw !== 'string') return null;
+  let value = raw.trim().replace(/^['"]|['"]$/g, '').trim();
+  const wikilink = value.match(/^\[\[([^\]]+)\]\]$/);
+  if (wikilink) value = wikilink[1].trim();
+  value = value.replace(/\.md$/i, '').trim();
+  return value || null;
+}
+
+/**
+ * Pure matching logic for resolution step 2 (case-insensitive exact basename) —
+ * extracted so the ambiguity path can be unit-tested without two real on-disk files
+ * whose names differ only by case, which case-insensitive filesystems (Windows,
+ * default macOS) cannot actually hold as distinct files.
+ */
+export function matchCaseInsensitiveExact(files, ref) {
+  const lowered = `${ref.toLowerCase()}.md`;
+  return files.filter((f) => f.toLowerCase() === lowered);
+}
+
+function loadRecord(vaultRoot, kind, file) {
+  const dirParts = BREAKDOWN_SOURCE_KINDS[kind].dir;
+  const absPath = join(vaultRoot, ...dirParts, file);
+  return {
+    kind,
+    basename: file.replace(/\.md$/i, ''),
+    absPath,
+    relPath: join(...dirParts, file),
+    raw: readFileSync(absPath, 'utf8'),
+  };
+}
+
+/**
+ * Resolve a reference within ONE kind's folder. Four steps, first hit wins:
+ *
+ *   1. exact basename
+ *   2. case-insensitive exact basename
+ *   3. frontmatter `id:` / `file_id:`
+ *   4. unambiguous id-prefix
+ *
+ * Returns `{ record }`, `{ ambiguous: [...] }`, or `{ miss: true }`. Ambiguity is
+ * reported rather than resolved — silently picking one of two candidates is how a
+ * breakdown lands against the wrong document.
+ */
+function resolveWithinKind(vaultRoot, kind, ref) {
+  const dir = join(vaultRoot, ...BREAKDOWN_SOURCE_KINDS[kind].dir);
+  if (!existsSync(dir)) return { miss: true };
+
+  if (existsSync(join(dir, `${ref}.md`))) {
+    return { record: loadRecord(vaultRoot, kind, `${ref}.md`) };
+  }
+
+  const files = readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+
+  const ciExact = matchCaseInsensitiveExact(files, ref);
+  if (ciExact.length === 1) return { record: loadRecord(vaultRoot, kind, ciExact[0]) };
+  if (ciExact.length > 1) {
+    return { ambiguous: ciExact.map((f) => f.replace(/\.md$/i, '')), step: 'case-insensitive basename' };
+  }
+
+  const idHits = [];
+  for (const file of files) {
+    let raw;
+    try {
+      raw = readFileSync(join(dir, file), 'utf8');
+    } catch {
+      continue;
+    }
+    const block = getFrontmatterBlock(raw)?.block;
+    if (!block) continue;
+    if (getScalarField(block, 'id') === ref || getScalarField(block, 'file_id') === ref) {
+      idHits.push(file);
+    }
+  }
+  if (idHits.length === 1) return { record: loadRecord(vaultRoot, kind, idHits[0]) };
+  if (idHits.length > 1) {
+    return { ambiguous: idHits.map((f) => f.replace(/\.md$/i, '')), step: 'frontmatter id' };
+  }
+
+  const prefixHits = files.filter((f) => f.startsWith(`${ref}-`));
+  if (prefixHits.length === 1) return { record: loadRecord(vaultRoot, kind, prefixHits[0]) };
+  if (prefixHits.length > 1) {
+    return { ambiguous: prefixHits.map((f) => f.replace(/\.md$/i, '')), step: 'id prefix' };
+  }
+
+  return { miss: true };
+}
+
+/**
+ * Resolve a reference to a breakdown source document.
+ *
+ * @param {string} vaultRoot
+ * @param {string} rawRef            id, basename, `[[wikilink]]`, or `<basename>.md`
+ * @param {{ kinds?: string[] }} [opts]  which kinds to search; defaults to both.
+ *
+ * On success returns `{ record }` where `record.kind` is read from the FILE's own
+ * `type:` frontmatter (falling back to the folder it was found in when the file
+ * declares no `type:` at all — warn-don't-repair,
+ * [[HS-DEC-vault-frontmatter-warn-dont-repair-on-read]]).
+ *
+ * A file that declares a `type:` the caller did not ask for is a TYPE MISMATCH, not
+ * a miss: telling the caller "not found" about a file that plainly exists sends them
+ * looking for a typo that isn't there.
+ */
+export function resolveBreakdownSource(vaultRoot, rawRef, opts = {}) {
+  const kinds = Array.isArray(opts.kinds) && opts.kinds.length > 0
+    ? opts.kinds.filter((k) => k in BREAKDOWN_SOURCE_KINDS)
+    : Object.keys(BREAKDOWN_SOURCE_KINDS);
+
+  const ref = normalizeSourceRef(rawRef);
+  if (!ref) {
+    return { error: 'INVALID_ARGS', message: 'a source id or basename is required' };
+  }
+
+  // Search EVERY known kind's folder, not only the requested ones. A reference that
+  // resolves in a folder the caller did not ask for is the type-mismatch case, and
+  // reporting it as such is the difference between "you passed a diagnose to the
+  // research path" and a bare "not found".
+  const hits = [];
+  const ambiguities = [];
+  for (const kind of Object.keys(BREAKDOWN_SOURCE_KINDS)) {
+    const found = resolveWithinKind(vaultRoot, kind, ref);
+    if (found.record) hits.push(found.record);
+    else if (found.ambiguous) ambiguities.push({ kind, ...found });
+  }
+
+  if (hits.length > 1) {
+    return {
+      error: 'SOURCE_ID_AMBIGUOUS',
+      message: `${rawRef} resolves to ${hits.length} documents across ${hits.map((h) => h.kind).join(' + ')} — pass the full basename instead`,
+      candidates: hits.map((h) => h.basename),
+    };
+  }
+
+  if (hits.length === 0) {
+    if (ambiguities.length > 0) {
+      const first = ambiguities[0];
+      return {
+        error: 'SOURCE_ID_AMBIGUOUS',
+        message: `${rawRef} matches ${first.ambiguous.length} files under ${BREAKDOWN_SOURCE_KINDS[first.kind].dir.join('/')}/ by ${first.step} — pass the exact basename or the frontmatter id: instead`,
+        candidates: first.ambiguous,
+      };
+    }
+    return {
+      error: 'SOURCE_NOT_FOUND',
+      message: `${rawRef} not found under ${kinds.map((k) => BREAKDOWN_SOURCE_KINDS[k].dir.join('/') + '/').join(' or ')} (tried exact basename, case-insensitive basename, frontmatter id:, and id-prefix match)`,
+      searched_kinds: kinds,
+    };
+  }
+
+  const record = hits[0];
+  const block = getFrontmatterBlock(record.raw)?.block ?? '';
+  const declared = (getScalarField(block, 'type') ?? '').trim().toLowerCase();
+
+  // The file's own `type:` wins; an undeclared type falls back to the folder.
+  if (declared) {
+    if (!(declared in BREAKDOWN_SOURCE_KINDS)) {
+      return {
+        error: 'SOURCE_TYPE_MISMATCH',
+        message: `${rawRef} resolved to ${record.relPath}, which is \`type: ${declared}\` — the breakdown stage accepts a research doc or a bug write-up`,
+        resolved_basename: record.basename,
+        resolved_type: declared,
+      };
+    }
+    record.kind = declared;
+  }
+
+  if (!kinds.includes(record.kind)) {
+    return {
+      error: 'SOURCE_TYPE_MISMATCH',
+      message: `${rawRef} resolved to ${record.relPath}, a ${BREAKDOWN_SOURCE_KINDS[record.kind].label} — this call expects ${kinds.map((k) => BREAKDOWN_SOURCE_KINDS[k].label).join(' or ')}`,
+      resolved_basename: record.basename,
+      resolved_type: record.kind,
+    };
+  }
+
+  return { record };
+}
+
+/**
+ * Frontmatter fields every breakdown source carries, lifted once so callers do not
+ * each re-parse the block.
+ */
+export function readSourceFrontmatter(record) {
+  const block = getFrontmatterBlock(record.raw)?.block ?? '';
+  return {
+    id: getScalarField(block, 'id') ?? record.basename,
+    name: getScalarField(block, 'name') ?? '',
+    family: getScalarField(block, 'family') ?? null,
+    status: getScalarField(block, 'status') ?? null,
+    type: getScalarField(block, 'type') ?? null,
+  };
+}