heyspex 0.1.0

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

@@ -0,0 +1,524 @@
+/**
+ * Placement descends, and everything spawned names a milestone ([[HS-FLGU]] of
+ * [[HS-ALBV]]).
+ *
+ * Epic §Scope: "Placement goes down, never up. Matching epic gets tasks. Matching
+ * milestone with no fitting epic gets a new epic. Only when neither exists does it
+ * mint a milestone with epic stubs, and that case asks the owner first." And:
+ * "Milestone required on everything spawned, no exemption. … carving an exemption is
+ * the only way stray epics could appear."
+ *
+ * Two things this module refuses to do, both load-bearing:
+ *
+ *  - **It never parents anything to the bug write-up.** An epic parented to a bug
+ *    report does not render on the roadmap at all. Spawned specs point UP at their
+ *    milestone/epic and BACK at the write-up via `derived_from:` — a link, not a
+ *    parent edge. The diagnose's own `parent:` keeps its existing job of grouping
+ *    small bugs under one epic and is never touched here.
+ *  - **It never writes an epic without a resolvable milestone.** The check runs
+ *    before any file is written, and no argument or environment variable relaxes it.
+ *
+ * Every write is STAGED and committed through `commitWrites`, including the parent's
+ * `epics:` / `children:` mirror — so a failure at any step rolls the whole set back
+ * and no half-placed breakdown is left on disk.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { collectOccupiedKeysEitherKind, allocateFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { listVaultPillars, resolvePillar } from './promote-research.mjs';
+import {
+  appendChangeLogRow,
+  appendToListField,
+  bumpUpdated,
+  commitWrites,
+  deriveSlug,
+  getFrontmatterBlock,
+  getScalarField,
+  isoNow,
+  todayDate,
+} from './promotion-helpers.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+
+const FAMILY_KEY_SHAPE_RE = /^[A-Z0-9]{4,}$/;
+
+/** The family key spawned specs inherit from the bug write-up they came from. */
+export function inheritedFamilyKey(sourceFrontmatter, sourceBasename) {
+  const candidates = [
+    sourceFrontmatter?.family,
+    parseSpecId(sourceFrontmatter?.id)?.familyKey,
+    parseSpecId(sourceBasename)?.familyKey,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && FAMILY_KEY_SHAPE_RE.test(c)) return c;
+  }
+  return null;
+}
+
+function readSpecFile(vaultRoot, dirParts, basename) {
+  const absPath = join(vaultRoot, ...dirParts, `${basename}.md`);
+  if (!existsSync(absPath)) return null;
+  const raw = readFileSync(absPath, 'utf8');
+  return { basename, absPath, relPath: join(...dirParts, `${basename}.md`), raw };
+}
+
+/**
+ * Stage an append onto a parent's list field (`epics:` on a milestone, `children:`
+ * on an epic) — the bidirectional mirror that keeps `milestone.epics ⇔ epic.milestone`
+ * and `epic.children ⇔ task.parent` honest.
+ *
+ * Returns a staged write rather than performing one, so the mirror rolls back with
+ * everything else. `promote-research.mjs` does this append POST-commit, which leaves
+ * a window where the files exist and the parent does not list them.
+ */
+function stageParentAppend(record, field, childBasenames, now) {
+  const fm = getFrontmatterBlock(record.raw);
+  if (!fm) {
+    return { error: 'PARENT_FRONTMATTER_MISSING', message: `${record.basename} has no frontmatter` };
+  }
+  let block = fm.block;
+  let changed = false;
+  for (const child of childBasenames) {
+    const next = appendToListField(block, field, child);
+    block = next.block;
+    changed = changed || next.changed;
+  }
+  if (!changed) return { write: null };
+  block = bumpUpdated(block, now);
+  return { write: { kind: 'update', absPath: record.absPath, content: `${fm.open}${block}${fm.close}${fm.body}` } };
+}
+
+function buildTaskContent({ id, fileKey, familyKey, name, parentBasename, sourceBasename, summary, now, today, fix }) {
+  return `---
+id: ${id}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: task
+status: open
+kind: feature
+effort: 3
+owner: pwher
+parent: "[[${parentBasename}]]"
+derived_from: "[[${sourceBasename}]]"
+tags:
+  - bug-fix
+summary: ${yamlScalar(summary)}
+created: "${now}"
+updated: "${now}"
+---
+
+# ${name}
+
+One of the separately-verifiable fixes listed in the bug write-up [[${sourceBasename}]] — that write-up is the record of the investigation and the source of this task, NOT its parent. It closes when its own reproduction stops reproducing, not when this task closes.
+
+## Acceptance criteria
+
+1. ${fix}
+2. The reproduction step in [[${sourceBasename}]] that this fix addresses no longer reproduces.
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-diagnose (agent) | Spawned from bug write-up [[${sourceBasename}]] under [[${parentBasename}]]. |
+`;
+}
+
+function buildEpicContent({ id, fileKey, familyKey, name, milestoneBasename, sourceBasename, pillarValue, summary, fixes, now, today }) {
+  const criteria = fixes.map((f, i) => `${i + 1}. ${f}`).join('\n');
+  return `---
+id: ${id}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: epic
+kind: foundation
+effort: 3
+requires_user_testing: false
+status: open
+owner: pwher
+parent: "[[${milestoneBasename}]]"
+milestone: "[[${milestoneBasename}]]"
+pillar: ${pillarValue}
+derived_from: "[[${sourceBasename}]]"
+depends_on: []
+tags:
+  - epic
+  - bug-fix
+children: []
+related:
+  - "[[${sourceBasename}]]"
+summary: ${yamlScalar(summary)}
+created: "${now}"
+updated: "${now}"
+---
+
+# ${name}
+
+Spawned by the breakdown of bug write-up [[${sourceBasename}]], which lists ${fixes.length} separately-verifiable fixes. The write-up is the SOURCE of this epic, never its parent — an epic parented to a bug report does not render on the roadmap. The write-up closes when its reproduction stops reproducing, not when this epic closes.
+
+## Intended outcome
+
+**User-visible outcome of this epic:** _What changes for the user when these fixes ship?_
+
+**Moves (↑ link):** _Which outcome of [[${milestoneBasename}]] does it move, and by what mechanism?_
+
+## Acceptance criteria
+
+${criteria}
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-diagnose (agent) | Spawned from bug write-up [[${sourceBasename}]] under milestone [[${milestoneBasename}]]. |
+`;
+}
+
+function buildMilestoneContent({ id, fileKey, familyKey, name, sourceBasename, pillarValue, summary, now, today }) {
+  return `---
+id: ${id}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: milestone
+status: open
+owner: pwher
+${pillarValue ? `pillar: ${pillarValue}\n` : ''}created: "${now}"
+updated: "${now}"
+target_date: ""
+tags:
+  - milestone
+  - bug-fix
+epics: []
+informed_by:
+  - "[[${sourceBasename}]]"
+related: []
+summary: ${yamlScalar(summary)}
+---
+
+# ${name}
+
+Minted by the breakdown of bug write-up [[${sourceBasename}]] after grounding found no open milestone or epic covering this area. Replace this prose with the real milestone framing — why these fixes ship together.
+
+## Intended outcome
+
+**Outcome at the milestone altitude:** _What outcome does this milestone deliver?_
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-diagnose (agent) | Created from bug write-up [[${sourceBasename}]] (owner-confirmed). |
+`;
+}
+
+/**
+ * The milestone an epic will name. Returns `{ basename }` or an error.
+ *
+ * The check is RESOLUTION, not presence: a `milestone:` wikilink pointing at a file
+ * that is not on disk is exactly the stray-epic shape the epic's "no exemption" rule
+ * exists to prevent, and it reads as fine in frontmatter.
+ */
+export function requireResolvableMilestone(vaultRoot, milestoneRef) {
+  const basename = typeof milestoneRef === 'string'
+    ? milestoneRef.trim().replace(/^\[\[|\]\]$/g, '').replace(/^['"]|['"]$/g, '').replace(/\.md$/i, '')
+    : '';
+  if (!basename) {
+    return {
+      error: 'MILESTONE_REQUIRED',
+      message:
+        'Every epic this stage writes must name a milestone. No argument, flag, or environment variable relaxes this — an epic without one never appears on the roadmap.',
+    };
+  }
+  const record = readSpecFile(vaultRoot, ['specs', 'milestones'], basename);
+  if (!record) {
+    return {
+      error: 'MILESTONE_REQUIRED',
+      message: `milestone [[${basename}]] does not resolve to a file under specs/milestones/ — an epic naming a milestone that is not on disk is a stray epic with a plausible-looking frontmatter line.`,
+      unresolved: basename,
+    };
+  }
+  return { record, basename };
+}
+
+/**
+ * Execute the placement the ladder + coverage scan decided on.
+ *
+ * @returns `{ spawned, writes }` on success, or `{ error, message, ... }`. Nothing is
+ * written until every gate has passed; the commit itself rolls back as a unit.
+ */
+export function executeBreakdownWrites({ vaultRoot, source, sourceFrontmatter, ladder, placement, args = {}, deps = {} }) {
+  const now = (deps.clock ?? isoNow)();
+  const today = now.slice(0, 10);
+  const sourceBasename = source.basename;
+  const familyKey = inheritedFamilyKey(sourceFrontmatter, sourceBasename) ?? 'BFIX';
+  const occupied = collectOccupiedKeysEitherKind(vaultRoot);
+  const mintKey = () => {
+    const key = allocateFileKey(occupied, { randomUnit: deps.randomUnit });
+    occupied.add(key);
+    return key;
+  };
+  const fixes = ladder.fixes ?? [];
+  const title = sourceFrontmatter.name || sourceBasename;
+
+  // Already broken down? Re-running mints fresh ids and would leave two sets of work
+  // for one investigation, with the on-deck queue and the Resolution row pointing at
+  // the newer half. Mirrors the research path's `RESEARCH_ALREADY_PROMOTED` guard.
+  const existingSpawn = getFrontmatterBlock(source.raw)?.block ?? '';
+  const alreadySpawned = ['spawned_epics', 'spawned_tasks'].flatMap((f) => {
+    const m = existingSpawn.match(new RegExp(`^${f}:[ \\t]*\\r?\\n((?:[ \\t]+-[^\\n]*\\r?\\n?)+)`, 'm'));
+    if (!m) return [];
+    return [...m[1].matchAll(/-[ \t]*["']?\[\[([^\]]+)\]\]["']?/g)].map((x) => x[1]);
+  });
+  if (alreadySpawned.length > 0 && args.force !== true) {
+    return {
+      error: 'DIAGNOSE_ALREADY_BROKEN_DOWN',
+      message: `${sourceBasename} has already been broken down into ${alreadySpawned.join(', ')}. Breaking it down again mints a second set of work for one investigation. Work the existing specs, or pass \`force: true\` if the first breakdown was wrong and has been cleaned up.`,
+      spawned_work: alreadySpawned,
+    };
+  }
+
+  const writes = [];
+  const spawned = { milestone: null, epics: [], tasks: [] };
+
+  const stageTasksUnder = (epicRecord, fixList) => {
+    const taskSpecs = fixList.map((fix) => {
+      const fileKey = mintKey();
+      const name = fix.replace(/[.]$/, '').slice(0, 80);
+      const basename = `HS-${fileKey}-${familyKey}-TASK-${deriveSlug(name)}`;
+      return {
+        id: `HS-${fileKey}`,
+        fileKey,
+        basename,
+        name,
+        fix,
+        absPath: join(vaultRoot, 'specs', 'tasks', `${basename}.md`),
+        relPath: join('specs', 'tasks', `${basename}.md`),
+      };
+    });
+    for (const t of taskSpecs) {
+      writes.push({
+        kind: 'create',
+        absPath: t.absPath,
+        content: buildTaskContent({
+          id: t.id,
+          fileKey: t.fileKey,
+          familyKey,
+          name: t.name,
+          parentBasename: epicRecord.basename,
+          sourceBasename,
+          summary: `One of the ${fixes.length} separately-verifiable fixes the bug write-up "${title}" lists. ${t.fix}`,
+          now,
+          today,
+          fix: t.fix,
+        }),
+      });
+    }
+    const mirror = stageParentAppend(epicRecord, 'children', taskSpecs.map((t) => t.basename), now);
+    if (mirror.error) return mirror;
+    if (mirror.write) writes.push(mirror.write);
+    spawned.tasks = taskSpecs.map((t) => ({ id: t.id, basename: t.basename, path: t.relPath }));
+    return {};
+  };
+
+  // ── tasks under a matching epic ───────────────────────────────────────────
+  if (placement.placement === 'tasks_under_epic') {
+    const epicRecord = readSpecFile(vaultRoot, ['specs', 'epics'], placement.attach_to);
+    if (!epicRecord) {
+      return { error: 'EPIC_NOT_FOUND', message: `${placement.attach_to} did not resolve under specs/epics/` };
+    }
+    // The target epic is not written here, but tasks placed under an epic that
+    // floats outside the roadmap are just as invisible as a stray epic would be.
+    const epicBlock = getFrontmatterBlock(epicRecord.raw)?.block ?? '';
+    const check = requireResolvableMilestone(vaultRoot, getScalarField(epicBlock, 'milestone'));
+    if (check.error) {
+      return {
+        ...check,
+        message: `target epic ${epicRecord.basename}: ${check.message}`,
+      };
+    }
+    const staged = stageTasksUnder(epicRecord, fixes);
+    if (staged.error) return staged;
+  }
+
+  // ── one new epic under a matching milestone ──────────────────────────────
+  else if (placement.placement === 'epic_under_milestone') {
+    const check = requireResolvableMilestone(vaultRoot, placement.attach_to);
+    if (check.error) return check;
+    const milestoneRecord = check.record;
+    const milestoneBlock = getFrontmatterBlock(milestoneRecord.raw)?.block ?? '';
+    const pillarRef = args.pillar ?? getScalarField(milestoneBlock, 'pillar');
+    const pillar = resolvePillar(vaultRoot, pillarRef);
+    if (!pillar.ok) {
+      return {
+        error: 'pillar_required',
+        message: pillarRef
+          ? `pillar \`${pillarRef}\` does not resolve under specs/pillars/ — pass a resolvable \`pillar\``
+          : `milestone ${milestoneRecord.basename} declares no \`pillar:\` — pass one as \`pillar\``,
+        existing_pillars: listVaultPillars(vaultRoot),
+      };
+    }
+    const fileKey = mintKey();
+    const name = title;
+    const basename = `HS-${fileKey}-${familyKey}-EPIC-${deriveSlug(name)}`;
+    writes.push({
+      kind: 'create',
+      absPath: join(vaultRoot, 'specs', 'epics', `${basename}.md`),
+      content: buildEpicContent({
+        id: `HS-${fileKey}`,
+        fileKey,
+        familyKey,
+        name,
+        milestoneBasename: milestoneRecord.basename,
+        sourceBasename,
+        pillarValue: pillar.frontmatterValue,
+        summary: `The ${fixes.length} separately-verifiable fixes the bug write-up "${title}" lists, gathered as one epic under an existing milestone.`,
+        fixes,
+        now,
+        today,
+      }),
+    });
+    const mirror = stageParentAppend(milestoneRecord, 'epics', [basename], now);
+    if (mirror.error) return mirror;
+    if (mirror.write) writes.push(mirror.write);
+    spawned.epics = [{ id: `HS-${fileKey}`, basename, path: join('specs', 'epics', `${basename}.md`) }];
+  }
+
+  // ── a new milestone (owner-confirmed) with one epic under it ─────────────
+  else if (placement.placement === 'new_milestone') {
+    if (args.confirm_new_milestone !== true) {
+      return {
+        error: 'OWNER_CONFIRMATION_REQUIRED',
+        message:
+          'Minting a milestone is the last rung and asks the owner first. Nothing was written. Re-run with `confirm_new_milestone: true` once the owner has agreed to the proposed milestone.',
+        proposed_milestone: title,
+      };
+    }
+    const pillar = resolvePillar(vaultRoot, args.pillar);
+    if (!pillar.ok) {
+      return {
+        error: 'pillar_required',
+        message:
+          'A new milestone mints a new epic under it, and every epic requires a resolvable `pillar:` — pass one.',
+        existing_pillars: listVaultPillars(vaultRoot),
+      };
+    }
+    const milestoneKey = mintKey();
+    const milestoneBasename = `HS-${milestoneKey}-${familyKey}-MIL-${deriveSlug(title)}`;
+    writes.push({
+      kind: 'create',
+      absPath: join(vaultRoot, 'specs', 'milestones', `${milestoneBasename}.md`),
+      content: buildMilestoneContent({
+        id: `HS-${milestoneKey}`,
+        fileKey: milestoneKey,
+        familyKey,
+        name: title,
+        sourceBasename,
+        pillarValue: pillar.frontmatterValue,
+        summary: `Minted from the bug write-up "${title}" after grounding found no open milestone or epic covering this area.`,
+        now,
+        today,
+      }),
+    });
+
+    const epicKey = mintKey();
+    const epicBasename = `HS-${epicKey}-${familyKey}-EPIC-${deriveSlug(title)}`;
+    writes.push({
+      kind: 'create',
+      absPath: join(vaultRoot, 'specs', 'epics', `${epicBasename}.md`),
+      content: buildEpicContent({
+        id: `HS-${epicKey}`,
+        fileKey: epicKey,
+        familyKey,
+        name: title,
+        milestoneBasename,
+        sourceBasename,
+        pillarValue: pillar.frontmatterValue,
+        summary: `The ${fixes.length} separately-verifiable fixes the bug write-up "${title}" lists.`,
+        fixes,
+        now,
+        today,
+      }),
+    });
+    spawned.milestone = { id: `HS-${milestoneKey}`, basename: milestoneBasename };
+    spawned.epics = [{ id: `HS-${epicKey}`, basename: epicBasename, path: join('specs', 'epics', `${epicBasename}.md`) }];
+    // The milestone is created with `epics: []` and mirrored in the same commit, so
+    // the pair is never observable half-linked.
+    const pending = { ...writes[0] };
+    const mirrored = stageParentAppend(
+      { basename: milestoneBasename, absPath: pending.absPath, raw: pending.content },
+      'epics',
+      [epicBasename],
+      now,
+    );
+    if (mirrored.error) return mirrored;
+    if (mirrored.write) writes[0] = { kind: 'create', absPath: pending.absPath, content: mirrored.write.content };
+  }
+
+  // ── measure first ────────────────────────────────────────────────────────
+  else if (placement.placement === 'measure_first') {
+    const epicRef = args.measurement_parent_epic ?? placement.attach_to;
+    const epicRecord = epicRef ? readSpecFile(vaultRoot, ['specs', 'epics'], epicRef) : null;
+    if (!epicRecord) {
+      return {
+        error: 'MEASUREMENT_NEEDS_PARENT',
+        message:
+          'The write-up concludes the cause is not yet known, so the only thing filed is the measurement — but a task needs an epic to live under and grounding found no epic covering this area. Name one with `measurement_parent_epic`. No epic and no milestone is minted on this path.',
+      };
+    }
+    const measurement = `Measure what is actually happening in "${title}" before any fix is designed`;
+    const staged = stageTasksUnder(epicRecord, [measurement]);
+    if (staged.error) return staged;
+  } else {
+    return { error: 'UNKNOWN_PLACEMENT', message: `placement ${placement.placement} is not a shape this stage writes` };
+  }
+
+  // ── The write-up itself: LINKS to what it spawned, and a change-log row. ──
+  //
+  // `spawned_epics:` / `spawned_tasks:` mirror the shape the research path already
+  // uses (`research.spawned_epics` ⇔ `epic.derived_from`), so the console's pipeline
+  // graph and the vault validator already understand them. What is NOT written, in
+  // any code path, is the diagnose's `parent:` — that field keeps its existing job of
+  // grouping several small bugs under one epic, and an epic parented to a bug report
+  // would not render on the roadmap at all.
+  //
+  // `appendToListField` is idempotent per entry, so a re-run of the same breakdown
+  // extends the list rather than duplicating what is already in it.
+  const sourceFm = getFrontmatterBlock(source.raw);
+  if (sourceFm) {
+    const spawnedNames = [
+      ...(spawned.milestone ? [spawned.milestone.basename] : []),
+      ...spawned.epics.map((e) => e.basename),
+      ...spawned.tasks.map((t) => t.basename),
+    ];
+    let block = sourceFm.block;
+    for (const e of spawned.epics) block = appendToListField(block, 'spawned_epics', e.basename).block;
+    for (const t of spawned.tasks) block = appendToListField(block, 'spawned_tasks', t.basename).block;
+    block = bumpUpdated(block, now);
+    const body = appendChangeLogRow(
+      sourceFm.body,
+      today,
+      'promote-diagnose (agent)',
+      `Broken down (${ladder.rung}, ${ladder.fix_count} fix(es)): spawned ${spawnedNames.map((n) => `[[${n}]]`).join(', ')}. Links, not parenting — this write-up is the source, never the parent, and it closes on its own reproduction.`,
+    );
+    writes.push({
+      kind: 'update',
+      absPath: source.absPath,
+      content: `${sourceFm.open}${block}${sourceFm.close}${body}`,
+    });
+  }
+
+  const commit = (deps.commitWrites ?? commitWrites)(writes);
+  if (!commit.ok) {
+    return {
+      error: 'WRITE_FAILED',
+      message: commit.error?.message ?? 'unknown write failure',
+      rollback_error: commit.error?.rollbackError,
+    };
+  }
+
+  return { spawned, writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })) };
+}

package/vendor/heyspex-mcp/brief-observability.mjs

@@ -0,0 +1,67 @@
+/**
+ * Brief-synthesis observability ([[HS-TASK-68NO]] / [[HS-EPIC-DXBR]] §8).
+ *
+ * Records which synthesis tier each derived execution brief was served at and
+ * exposes the **degraded-mode rate** — the share of briefs served below the
+ * 'derived' tier ('minimal' + 'skip'). A rising degraded rate is the early
+ * warning that specs are thinning or the parser regressed: degradation becomes
+ * visible instead of failing quietly.
+ *
+ * In-memory counters (process-lifetime) are the queryable signal; each synthesis
+ * also emits one structured log line so the tier + running rate are observable
+ * in the MCP host's stderr stream. The classifier itself lives in
+ * alignment-gate.mjs (`classifyBriefTier`) and stays pure; this module owns the
+ * stateful counter + log formatting.
+ */
+
+import { DEGRADED_BRIEF_TIERS } from './alignment-gate.mjs';
+
+const KNOWN_TIERS = ['override', 'derived', 'minimal', 'skip'];
+
+function emptyCounts() {
+  const c = {};
+  for (const t of KNOWN_TIERS) c[t] = 0;
+  return c;
+}
+
+// Module-level counters — reset only on process restart (or explicitly in tests).
+const counts = emptyCounts();
+
+/** Increment the counter for `tier`. Unknown tiers are ignored (defensive). */
+export function recordBriefTier(tier) {
+  if (Object.prototype.hasOwnProperty.call(counts, tier)) {
+    counts[tier] += 1;
+  }
+  return getBriefTierStats();
+}
+
+/**
+ * `{ counts, total, degraded, degradedRate }`. `degradedRate` is the share of
+ * briefs served below 'derived' (0 when nothing recorded yet). Pure read.
+ */
+export function getBriefTierStats() {
+  const total = KNOWN_TIERS.reduce((n, t) => n + counts[t], 0);
+  const degraded = DEGRADED_BRIEF_TIERS.reduce((n, t) => n + (counts[t] || 0), 0);
+  return {
+    counts: { ...counts },
+    total,
+    degraded,
+    degradedRate: total > 0 ? degraded / total : 0,
+  };
+}
+
+/** Test-only: zero the counters so suites stay hermetic. */
+export function resetBriefTierStats() {
+  for (const t of KNOWN_TIERS) counts[t] = 0;
+}
+
+/**
+ * Pure formatter for the per-synthesis structured log line. Includes the tier,
+ * spec id, and the running degraded-mode rate + sample size so the signal is
+ * visible inline in the log stream (not just via getBriefTierStats).
+ */
+export function formatBriefTierLog({ tier, id, stats }) {
+  const s = stats || getBriefTierStats();
+  const rate = s.degradedRate.toFixed(3);
+  return `[heyspex-mcp brief] tier=${tier} id=${id || 'unknown'} degraded_rate=${rate} n=${s.total}`;
+}