heyspex 0.1.0

package/vendor/heyspex-mcp/verify-reproduction.mjs

@@ -0,0 +1,314 @@
+/**
+ * `heyspex_verify_reproduction` — record a reproduction re-run on a diagnose, and
+ * close it when the run comes back clean.
+ *
+ * Criterion 7 of [[HS-ALBV-BFIX-EPIC-breakdown-stage-accepts-a-diagnose]], built in
+ * [[HS-09W1]]: a bug write-up that has been broken down closes when its REPRODUCTION
+ * stops reproducing — not when its last child task closes. Every one of the seven
+ * prior console read-path attempts closed clean while the bug stayed live, which is
+ * exactly what a child-rollup close rewards.
+ *
+ * This is also the first route a diagnose has ever had to `closed` at all. A diagnose
+ * is standalone — it has no parent in the milestone → epic → task chain — so
+ * `cascadeCloseReviewPending` in the console's status engine never reaches it (that
+ * cascade only walks milestone → epic and epic → task). Measured 2026-08-22: 211
+ * diagnoses parked at `in_review` / `review_pending` with nothing in the system that
+ * would ever move them. Recording a clean re-run here is what moves one.
+ *
+ * The status flip goes through `PATCH /api/specs/:id/status`, never a hand-edited
+ * `status:` — the status API owns coercion, rollup, and spec events ([[HS-DIAG-DOSH]]),
+ * and the reproduction gate lives inside it, so a clean record is what unlocks the
+ * close rather than this module deciding on its own.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  appendChangeLogRow,
+  bumpUpdated,
+  commitWrites,
+  getFrontmatterBlock,
+  getScalarField,
+  isoNow,
+  parseListFieldBasenames,
+  setScalarField,
+  todayDate,
+} from './promotion-helpers.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+
+/** The two verdicts a re-run can produce. Authored by whoever ran it, never inferred. */
+export const REPRODUCTION_VERDICTS = ['no_longer_reproduces', 'still_reproduces'];
+
+/**
+ * Statuses from which a clean re-run closes the diagnose.
+ *
+ * Build-complete only. An `open` / `in_progress` diagnose has not been built yet, and
+ * a re-run that happens to pass on it proves the bug was never reproduced in the first
+ * place, not that a fix landed — that one still goes through the normal build→review
+ * hand-off. The verdict is recorded either way.
+ */
+export const CLOSEABLE_FROM_STATUSES = new Set(['in_review', 'review_pending']);
+
+/**
+ * Evidence floor. A verdict with no account of what was run is a green light wired to
+ * nothing — the same failure mode a vacuous checks-manifest row is refused for
+ * ([[checks-manifest-authoring]]). 30 characters is short enough for "ran the repro
+ * steps in §Reproduction against localhost:3000, clean" and long enough to refuse "ok".
+ */
+export const EVIDENCE_MIN_LENGTH = 30;
+
+/** Mirror of the console's `REPRODUCTION_RERUN_FIELDS` (`@/lib/diagnose-spawned`). */
+export const REPRODUCTION_RERUN_FIELDS = {
+  at: 'reproduction_rerun_at',
+  by: 'reproduction_rerun_by',
+  result: 'reproduction_rerun_result',
+  evidence: 'reproduction_rerun_evidence',
+};
+
+/** Mirror of the console's `SPAWNED_WORK_FIELDS`. */
+export const SPAWNED_WORK_FIELDS = ['spawned_epics', 'spawned_tasks'];
+
+/**
+ * Resolve a diagnose reference to a file under `specs/diagnoses/`.
+ *
+ * Resolution-first, like every other vault resolver here: exact basename, then
+ * frontmatter `id:` / `file_id:`, then an unambiguous id-prefix match. No id-shape
+ * pattern match — an era-3 file key carries no `DIAG` label
+ * ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]).
+ */
+export function resolveDiagnoseRef(vaultRoot, rawRef) {
+  const ref =
+    typeof rawRef === 'string'
+      ? rawRef
+          .trim()
+          .replace(/^\[\[|\]\]$/g, '')
+          .replace(/^['"]|['"]$/g, '')
+          .replace(/\.md$/i, '')
+          .trim()
+      : '';
+  if (!ref) return { error: 'INVALID_ARGS', message: 'spec_id is required' };
+
+  const dir = join(vaultRoot, 'specs', 'diagnoses');
+  const notFound = {
+    error: 'DIAGNOSE_NOT_FOUND',
+    message: `diagnose ${rawRef} not found under specs/diagnoses/ (tried exact basename, frontmatter id:, and id-prefix match)`,
+  };
+  if (!existsSync(dir)) return notFound;
+
+  const load = (file) => {
+    const absPath = join(dir, file);
+    return {
+      basename: file.replace(/\.md$/i, ''),
+      absPath,
+      relPath: join('specs', 'diagnoses', file),
+      raw: readFileSync(absPath, 'utf8'),
+    };
+  };
+
+  if (existsSync(join(dir, `${ref}.md`))) return { record: load(`${ref}.md`) };
+
+  const files = readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+
+  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: load(idHits[0]) };
+  if (idHits.length > 1) {
+    return {
+      error: 'DIAGNOSE_ID_AMBIGUOUS',
+      message: `spec_id ${rawRef} matches the frontmatter id of ${idHits.length} files under specs/diagnoses/ — pass the full basename instead`,
+      candidates: idHits.map((f) => f.replace(/\.md$/i, '')),
+    };
+  }
+
+  const prefixHits = files.filter((f) => f.startsWith(`${ref}-`));
+  if (prefixHits.length === 1) return { record: load(prefixHits[0]) };
+  if (prefixHits.length > 1) {
+    return {
+      error: 'DIAGNOSE_ID_AMBIGUOUS',
+      message: `spec_id ${rawRef} is a prefix of ${prefixHits.length} files under specs/diagnoses/ — pass the full basename instead`,
+      candidates: prefixHits.map((f) => f.replace(/\.md$/i, '')),
+    };
+  }
+
+  return notFound;
+}
+
+/** Every spec this diagnose spawned — the link fields, never a parent edge. */
+export function spawnedWorkRefs(block) {
+  const out = [];
+  for (const field of SPAWNED_WORK_FIELDS) {
+    const list = parseListFieldBasenames(block, field);
+    if (Array.isArray(list)) out.push(...list);
+  }
+  return out;
+}
+
+/**
+ * Stage the frontmatter mutation for one recorded re-run.
+ *
+ * `setScalarField` REPLACES an existing line, so a second re-run overwrites the first
+ * rather than leaving two verdicts in one file for a reader to pick between. The
+ * history of re-runs lives in the change log, where it is append-only and dated.
+ */
+export function buildVerifiedContent(raw, { result, evidence, by, now, today }) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) throw new Error('diagnose has no frontmatter — cannot record a reproduction re-run');
+  let block = fm.block;
+  block = setScalarField(block, REPRODUCTION_RERUN_FIELDS.at, `"${now}"`);
+  block = setScalarField(block, REPRODUCTION_RERUN_FIELDS.by, yamlScalar(by));
+  block = setScalarField(block, REPRODUCTION_RERUN_FIELDS.result, result);
+  block = setScalarField(block, REPRODUCTION_RERUN_FIELDS.evidence, yamlScalar(evidence));
+  block = bumpUpdated(block, now);
+
+  const verdict =
+    result === 'no_longer_reproduces'
+      ? 'Reproduction re-run: NO LONGER REPRODUCES.'
+      : 'Reproduction re-run: STILL REPRODUCES.';
+  const body = appendChangeLogRow(fm.body, today, by, `${verdict} ${evidence}`);
+  return `${fm.open}${block}${fm.close}${body}`;
+}
+
+/**
+ * @param {{
+ *   vaultRoot: string,
+ *   consoleFetch: Function,
+ *   args?: Record<string, unknown>,
+ *   clock?: () => string,
+ *   agent?: string,
+ * }} ctx
+ */
+export async function executeVerifyReproduction({
+  vaultRoot,
+  consoleFetch,
+  args = {},
+  clock = isoNow,
+  agent = 'agent',
+}) {
+  const result = typeof args.result === 'string' ? args.result.trim().toLowerCase() : '';
+  if (!REPRODUCTION_VERDICTS.includes(result)) {
+    return {
+      error: 'INVALID_ARGS',
+      message: `result must be one of: ${REPRODUCTION_VERDICTS.join(' | ')}`,
+    };
+  }
+  const evidence = typeof args.evidence === 'string' ? args.evidence.trim() : '';
+  if (evidence.length < EVIDENCE_MIN_LENGTH) {
+    return {
+      error: 'EVIDENCE_REQUIRED',
+      message:
+        `evidence must be at least ${EVIDENCE_MIN_LENGTH} characters describing what you re-ran ` +
+        'and what happened. A verdict with no account of the run is a green light wired to nothing.',
+    };
+  }
+
+  const resolved = resolveDiagnoseRef(vaultRoot, args.spec_id);
+  if (resolved.error) return resolved;
+  const diagnose = resolved.record;
+
+  const fm = getFrontmatterBlock(diagnose.raw);
+  if (!fm) {
+    return {
+      error: 'DIAGNOSE_FRONTMATTER_MISSING',
+      message: `${diagnose.basename} has no frontmatter — cannot record a reproduction re-run`,
+    };
+  }
+  const type = (getScalarField(fm.block, 'type') ?? '').trim().toLowerCase();
+  if (type && type !== 'diagnose') {
+    return {
+      error: 'NOT_A_DIAGNOSE',
+      message: `${diagnose.basename} is \`type: ${type}\` — a reproduction re-run is recorded on a diagnose`,
+      resolved_type: type,
+    };
+  }
+
+  const specId = getScalarField(fm.block, 'id') ?? diagnose.basename;
+  const statusBefore = (getScalarField(fm.block, 'status') ?? 'open').trim().toLowerCase();
+  const spawned = spawnedWorkRefs(fm.block);
+
+  const now = clock();
+  const today = todayDate();
+  const by = typeof args.by === 'string' && args.by.trim() ? args.by.trim() : agent;
+
+  const content = buildVerifiedContent(diagnose.raw, { result, evidence, by, now, today });
+  const commit = commitWrites([{ kind: 'update', absPath: diagnose.absPath, content }]);
+  if (!commit.ok) {
+    return {
+      error: 'WRITE_FAILED',
+      message: commit.error?.message ?? 'unknown write failure',
+    };
+  }
+
+  const recorded = {
+    spec_id: specId,
+    basename: diagnose.basename,
+    path: diagnose.relPath,
+    result,
+    evidence,
+    by,
+    at: now,
+    spawned_work: spawned,
+    status_before: statusBefore,
+  };
+
+  // A run that still reproduces records and closes nothing — the diagnose is left
+  // exactly as it was, and its Resolution row stays open.
+  if (result !== 'no_longer_reproduces') {
+    return {
+      ...recorded,
+      closed: false,
+      close_skipped: 'still_reproduces',
+      message:
+        'Verdict recorded. The bug still reproduces, so nothing was closed — the write-up stays open.',
+    };
+  }
+
+  if (!CLOSEABLE_FROM_STATUSES.has(statusBefore)) {
+    return {
+      ...recorded,
+      closed: false,
+      close_skipped: 'not_build_complete',
+      message:
+        `Verdict recorded. \`${specId}\` is \`status: ${statusBefore}\`, not build-complete, so it was ` +
+        'not closed — hand it off with `heyspex_submit_for_review` first, then the recorded clean run closes it.',
+    };
+  }
+
+  const res = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}/status`, {
+    method: 'PATCH',
+    // `close_reason`, snake_case — the route's body contract. A camelCase key is
+    // silently ignored, so the close would land with no reason recorded.
+    body: { status: 'closed', close_reason: `Reproduction re-run ${now}: no longer reproduces.` },
+  });
+  if (!res?.ok) {
+    return {
+      ...recorded,
+      closed: false,
+      close_skipped: 'status_api_refused',
+      status: res?.status,
+      console_response: res?.body,
+      message:
+        'Verdict recorded on disk, but the status API did not close the spec. The record stands — ' +
+        're-run the close once the reason in `console_response` is cleared.',
+    };
+  }
+
+  return {
+    ...recorded,
+    closed: true,
+    status_after: res.body?.spec?.status ?? 'closed',
+    message: `Reproduction no longer reproduces — \`${specId}\` closed via the status API.`,
+  };
+}

package/vendor/heyspex-mcp/why-now.mjs

@@ -0,0 +1,64 @@
+/**
+ * "Why now" one-line legibility builder — vendor mirror of
+ * spex-console/src/lib/scheduler/why-now.ts ([[HS-TASK-WYNW]] / [[HS-RES-7J97]]).
+ * Keep in lockstep with the console module (heart/star always appear when flagged).
+ */
+
+export const HEART_REASON_SENTINEL = 'user marked very important (heart)';
+export const STAR_REASON_SENTINEL = 'user marked priority (star)';
+export const TESTING_CLUSTER_REASON_SENTINEL = 'grouped with adjacent testing-flagged specs';
+
+const MAX_CLAUSES = 3;
+const SMALL_EFFORT_MAX = 2;
+const HIGH_CRITICALITY_MIN = 3;
+/** Mirrors console AGING_THRESHOLD_DAYS. */
+export const AGING_THRESHOLD_DAYS = 14;
+
+function hasReason(trace, sentinel) {
+  return Array.isArray(trace?.reasons) && trace.reasons.includes(sentinel);
+}
+
+function collectStageClauses(trace, ctx) {
+  const out = [];
+  if (trace.topologicalLayer === 0) out.push('no open blockers');
+  if (trace.tier === 'infra') out.push('infra work first');
+  else if (trace.tier === 'foundation') out.push('foundation work first');
+  if (trace.criticality >= HIGH_CRITICALITY_MIN) out.push('blocks the most');
+  else if (trace.criticality > 0) out.push(`blocking ${trace.criticality} downstream`);
+  if (trace.agedDays >= AGING_THRESHOLD_DAYS) out.push(`waiting ${trace.agedDays}d`);
+  if (trace.effort <= SMALL_EFFORT_MAX) out.push('smallest effort');
+  if (hasReason(trace, TESTING_CLUSTER_REASON_SENTINEL)) out.push('groups with other testing work');
+  if (ctx.hysteresisHeld) out.push('kept its slot (anti-churn)');
+  return out;
+}
+
+/**
+ * @param {object} trace ExplanationTrace from buildExplanation / computeOrder
+ * @param {{ pinned?: boolean, pinnedBehindPrereqsCount?: number, hysteresisHeld?: boolean }} [ctx]
+ */
+export function buildWhyNow(trace, ctx = {}) {
+  const clauses = [];
+  if (ctx.pinned) {
+    clauses.push('pinned by you');
+    const behind = ctx.pinnedBehindPrereqsCount ?? 0;
+    if (behind > 0) clauses.push(`behind ${behind} open prereq${behind === 1 ? '' : 's'}`);
+  }
+  const wmClause = hasReason(trace, HEART_REASON_SENTINEL)
+    ? "you ❤️'d it"
+    : hasReason(trace, STAR_REASON_SENTINEL)
+      ? "you ⭐'d it"
+      : null;
+  if (wmClause) clauses.push(wmClause);
+
+  const inProgress = trace.status === 'in_progress';
+  const footer = inProgress ? 'already in progress' : null;
+  const stageClauses = collectStageClauses(trace, ctx);
+  const reserveForFooter = footer ? 1 : 0;
+  const slotsForStages = Math.max(0, MAX_CLAUSES - clauses.length - reserveForFooter);
+  for (let i = 0; i < stageClauses.length && i < slotsForStages; i++) {
+    clauses.push(stageClauses[i]);
+  }
+  if (footer) clauses.push(footer);
+  if (clauses.length === 0) return 'default deterministic order';
+  return clauses.join(' · ');
+}

package/vendor/heyspex-mcp/yaml-scalar.mjs

@@ -0,0 +1,34 @@
+/**
+ * Dependency-free YAML scalar quoter for the MCP frontmatter writers.
+ *
+ * The MCP runtime deliberately avoids loading js-yaml (startup cost — see the
+ * note in plan-push.mjs and HS-REV-006B), so hand-built frontmatter needs a
+ * correct, library-free quoting rule. The prior per-writer rule only quoted a
+ * value if it *contained* `:` or `"`, which let values that START with a
+ * backtick or a double-quote (and other YAML indicators) through unquoted —
+ * the exact corruption that silently dropped specs from the index.
+ *
+ * Strategy: emit the bare string only when it matches a conservative
+ * "plainly safe" pattern; otherwise emit `JSON.stringify(...)`. A JSON
+ * double-quoted string is always a valid YAML double-quoted scalar, so this is
+ * round-trip safe for any input. This is the seed of the single canonical
+ * serializer recommended by [[HS-RES-COOA-deterministic-frontmatter-integrity]].
+ */
+
+/**
+ * Bare-safe iff: starts with an alphanumeric and contains only word chars,
+ * spaces, dots, slashes, or hyphens. That charset excludes every YAML
+ * indicator (`: # ` " ' & * ! | > % @ , [ ] { }` and leading `-`/space), so
+ * the value cannot be misread as structure. Everything else is JSON-quoted.
+ */
+const BARE_SAFE = /^[A-Za-z0-9][\w ./-]*$/;
+
+/**
+ * @param {unknown} value
+ * @returns {string} a YAML-safe scalar representation of `value`.
+ */
+export function yamlScalar(value) {
+  const s = String(value);
+  if (BARE_SAFE.test(s)) return s;
+  return JSON.stringify(s);
+}