heyspex 0.1.0

package/vendor/heyspex-mcp/spec-id-lib.mjs

@@ -0,0 +1,790 @@
+/**
+ * Shared spec-id helpers for vendor/heyspex-mcp/.
+ *
+ * `extractSpecSuffix` is the canonical pairing logic between parent specs and
+ * their `HS-REV-<suffix>-*.md` review companions. Same regex as
+ * `spex-console/src/lib/vault.ts:155-158` — keep them in sync if the supported
+ * type list ever changes. See [[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]].
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Extract the family key (the shared random code) from a spec id, in EITHER
+ * ordering — dual-read via `parseSpecId` ([[HS-EPIC-DLE3]] / [[HS-EPIC-6SNQ]]).
+ *
+ *   HS-TASK-SK1L  → "SK1L"   (type-first, legacy)
+ *   HS-SK1L-TASK  → "SK1L"   (family-first, canonical)
+ *   HS-SK1L-REV-… → "SK1L"
+ *
+ * Returns null if the id is not a two-token HS spec id (e.g. a bare family token
+ * or a slug-only memory id).
+ */
+export function extractSpecSuffix(id) {
+  return parseSpecId(id)?.familyKey?.toUpperCase() ?? null;
+}
+
+/**
+ * Locate the `HS-REV-<suffix>-*.md` review companion for a parent spec id.
+ *
+ * Returns the vault-relative path (forward slashes) or null if no companion
+ * exists in `specs/reviews/`. Prefers matching by the review doc's `parent:` or
+ * `target:` frontmatter field (unambiguous for shared-suffix families); falls back
+ * to suffix matching for docs that predate the `parent:` field convention.
+ */
+export function findReviewDocForSpec(vaultRoot, parentSpecId) {
+  const reviewsDir = join(vaultRoot, 'specs', 'reviews');
+  if (!existsSync(reviewsDir)) return null;
+  let files;
+  try {
+    files = readdirSync(reviewsDir);
+  } catch {
+    return null;
+  }
+
+  // Canonical id of the parent, ordering-independent (dual-read). We normalize to
+  // one ordering so a type-first parent id and a family-first review link compare
+  // equal. See [[HS-EPIC-DLE3]] AC#4 — review pairing keys on the family key.
+  const canonicalSpecId = (value) => {
+    const p = parseSpecId(value);
+    return p ? `HS-${p.familyKey}-${p.typeLabel}`.toUpperCase() : null;
+  };
+  const parentIdUpper = canonicalSpecId(parentSpecId);
+
+  if (parentIdUpper) {
+    // First: match by parent: or target: frontmatter field (unambiguous for shared-key families)
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      try {
+        const content = readFileSync(join(reviewsDir, file), 'utf8');
+        const m = content.match(/^(?:parent|target):\s*['"]?\[\[([^\]]+)\]\]['"]?/m);
+        if (m && canonicalSpecId(m[1]) === parentIdUpper) {
+          return `specs/reviews/${file}`;
+        }
+      } catch {
+        // skip unreadable files
+      }
+    }
+  }
+
+  // Fallback: family-key match (for review docs without a parent: or target: field),
+  // in either ordering — a review file is HS-REV-<key>-… or HS-<key>-REV-….
+  const suffix = extractSpecSuffix(parentSpecId);
+  if (!suffix) return null;
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const parts = parseSpecId(file.replace(/\.md$/i, ''));
+    if (parts && parts.typeLabel === 'REV' && parts.familyKey.toUpperCase() === suffix) {
+      return `specs/reviews/${file}`;
+    }
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dual-read identifier anatomy ([[HS-EPIC-6SNQ-dual-read-resolver-grace-period-for-pipe]],
+// Phase 1 of [[HS-MIL-KY1F-pipeline-first-spec-identifier-format-mi]]).
+//
+// During the migration grace window the vault holds spec basenames in ONE of two
+// orderings at a time, while callers (wikilinks, MCP spec_id args, the CLI) may
+// pass either. These helpers parse a spec id/basename into its three canonical
+// atoms — **family key** (the shared feature handle), **type label** (TASK/EPIC/…,
+// a human disambiguator), and **title slug** — and flip between the two orderings:
+//
+//   type-first   (legacy):  HS-<TYPE>-<familyKey>[-<titleSlug>]   e.g. HS-TASK-P2TR-foo
+//   family-first (new):     HS-<familyKey>-<TYPE>[-<titleSlug>]   e.g. HS-P2TR-TASK-foo
+//
+// Routing/entity type is always read from `type:` frontmatter, never inferred from
+// the filename token (see vault-id-assignment-protocol §Identifier terminology and
+// format). These helpers exist only so a resolver can find the file regardless of
+// which ordering the on-disk basename currently uses.
+//
+// Mirror: spex-console/src/lib/vault-id.ts (`alternateOrderingBasename` +
+// `KNOWN_TYPE_LABELS`). Keep the two type-label sets in sync.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Shape of a minted per-file FILE KEY (owner ruling 2026-07-10): 4+ uppercase
+ * alphanumerics with AT LEAST ONE LETTER, sitting between the type label and
+ * the title slug — `HS-<familyKey>-<TYPE>-<fileKey>-<titleSlug>.md`. All-digit
+ * keys are never minted and never parsed as file keys (a year-like slug token
+ * such as `2026` must not read as one). Legacy files carry no file key.
+ * Mirror: spex-console/src/lib/vault-id.ts `FILE_KEY_RE`.
+ */
+export const FILE_KEY_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
+
+/**
+ * File key carried by a spec id/basename in EITHER ordering, or null for
+ * legacy no-file-key names. The file key is the first title-tail token when it
+ * matches FILE_KEY_RE — uppercase with a letter, which no lowercase title-slug
+ * token can be. Mirror: vault-id.ts `fileKeyFromBasename`.
+ */
+export function fileKeyFromBasename(input) {
+  const p = parseSpecId(input);
+  if (!p) return null;
+  if (p.era === 3) {
+    // File-key-first: the file key is the LEADING token, not derived from
+    // titleSlug (unlike era-1/era-2).
+    return p.fileKey && FILE_KEY_RE.test(p.fileKey) ? p.fileKey : null;
+  }
+  if (!p.titleSlug) return null;
+  const first = p.titleSlug.split('-', 1)[0];
+  return FILE_KEY_RE.test(first) ? first : null;
+}
+
+const FILE_KEY_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const FILE_KEY_LENGTH = 4;
+
+/**
+ * Every occupied file key across the vault, by walking `specs/**` BASENAMES
+ * (directory listings only — no file reads, so it is cheap enough to run per
+ * mint). Frontmatter `file_id:` is the SSOT, but every minted key is also in
+ * its filename, so basenames are a complete occupancy source.
+ *
+ * PRECISE by design: file keys only. Cross-namespace mint safety (a file key
+ * must never equal a family key — [[HS-SJOT-AEP1-DIAG]]) is enforced by
+ * UNIONING this with {@link collectOccupiedFamilyKeysFromVault} at every mint
+ * site (mintFileKey / mintFamilyKey / the direct allocateFileKey callers), so
+ * membership tests on this set stay namespace-accurate.
+ */
+export function collectOccupiedFileKeysFromVault(vaultRoot) {
+  const occupied = new Set();
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name === '.trash') continue;
+        walk(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const key = fileKeyFromBasename(entry.name.replace(/\.md$/i, ''));
+        if (key) occupied.add(key);
+      }
+    }
+  };
+  walk(join(vaultRoot, 'specs'));
+  return occupied;
+}
+
+/**
+ * Mint a per-file FILE KEY (owner ruling 2026-07-10): {@link FILE_KEY_LENGTH}
+ * chars, at least one letter (all-digit rejected — see FILE_KEY_RE), unique
+ * vault-wide against `occupied`. Auto-extends on exhaustion. Mirror:
+ * spex-console/src/lib/vault-id.ts `allocateFileKey`.
+ */
+export function allocateFileKey(occupied, options = {}) {
+  const charset = options.charset ?? FILE_KEY_CHARSET;
+  const randomUnit = options.randomUnit ?? (() => Math.random());
+  let length = options.minLength ?? FILE_KEY_LENGTH;
+
+  while (true) {
+    const maxAttempts = Math.min(charset.length ** length, 10_000);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      let key = '';
+      for (let i = 0; i < length; i++) {
+        const idx = Math.floor(randomUnit() * charset.length);
+        key += charset[Math.min(idx, charset.length - 1)];
+      }
+      if (!FILE_KEY_RE.test(key)) continue; // all-digit — never minted
+      // Never mint a key equal to a type label: era detection keys on
+      // closed-set type-label position, so a key like "TASK" or "EPIC" would
+      // silently reparse a basename into the wrong era ([[HS-SJOT-AEP1-DIAG]]).
+      if (KNOWN_TYPE_LABELS.has(key)) continue;
+      if (!occupied.has(key)) return key;
+    }
+    length++;
+  }
+}
+
+/**
+ * One-call mint for filing modules: walk the vault for occupied keys, then
+ * allocate. `randomUnit` is injectable for tests. Occupancy is the UNION of
+ * file keys AND family keys: era-3 ids are bare file keys, so a file key that
+ * equals any family key makes a bare `HS-XXXX` citation ambiguous between one
+ * file and a whole family ([[HS-SJOT-AEP1-DIAG]]).
+ */
+export function mintFileKey(vaultRoot, options = {}) {
+  return allocateFileKey(collectOccupiedKeysEitherKind(vaultRoot), options);
+}
+
+/**
+ * Every occupied family key across the vault, walking `specs/**` BASENAMES
+ * only (cheap directory listing, no file reads — mirrors
+ * {@link collectOccupiedFileKeysFromVault}). A basename encodes its family key
+ * positionally regardless of era ({@link parseSpecId}'s `familyKey`), so this
+ * is accurate even for era-3 file-key-first names. Used to mint a FRESH,
+ * not-already-meaningful-elsewhere family key for a parentless spec (V3
+ * shared-surname model — [[naming-v3-7-rulings-hs-namespace-kept]] /
+ * vault-id-assignment-protocol §Family inheritance): family keys are NOT
+ * required to be globally unique (any number of specs may legally share one),
+ * so this is a "pick something fresh" default, not a uniqueness gate. Mirror:
+ * spex-console/src/lib/vault-id.ts `collectOccupiedFamilyKeys`.
+ */
+export function collectOccupiedFamilyKeysFromVault(vaultRoot) {
+  const occupied = new Set();
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name === '.trash') continue;
+        walk(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const p = parseSpecId(entry.name.replace(/\.md$/i, ''));
+        if (p?.familyKey) occupied.add(p.familyKey.toUpperCase());
+      }
+    }
+  };
+  walk(join(vaultRoot, 'specs'));
+  return occupied;
+}
+
+/**
+ * Cross-namespace mint occupancy ([[HS-SJOT-AEP1-DIAG]]): the union of every
+ * occupied FILE key and FAMILY key. Era-3 ids are bare file keys, so a fresh
+ * key of EITHER kind that lands in the other namespace makes a bare `HS-XXXX`
+ * citation ambiguous between one file and a whole family. Every mint site
+ * allocates against this union; the two per-namespace collectors above stay
+ * precise for membership tests.
+ */
+export function collectOccupiedKeysEitherKind(vaultRoot) {
+  const occupied = collectOccupiedFileKeysFromVault(vaultRoot);
+  for (const k of collectOccupiedFamilyKeysFromVault(vaultRoot)) occupied.add(k);
+  return occupied;
+}
+
+/**
+ * Mint a fresh family key for a parentless spec: same shape/collision-check
+ * machinery as {@link allocateFileKey} (4 chars, at least one letter),
+ * checked against {@link collectOccupiedFamilyKeysFromVault} so a fresh mint
+ * doesn't accidentally collide with an existing unrelated family.
+ */
+export function mintFamilyKey(vaultRoot, options = {}) {
+  return allocateFileKey(collectOccupiedKeysEitherKind(vaultRoot), options);
+}
+
+/**
+ * Closed set of basename type labels. A token is the **type label** (not the
+ * family key) iff it is in this set. Family keys are random 4+ alphanumerics
+ * (or legacy 3-digit RES/IDEA / 4-digit EPIC sequences); type labels are a fixed
+ * vocabulary of all-caps words, so closed-set membership disambiguates ordering.
+ * Derived from the type tokens actually in use as basename prefixes across the
+ * vault, plus the memory/idea kinds for completeness.
+ */
+export const KNOWN_TYPE_LABELS = new Set([
+  'TASK', 'EPIC', 'MIL', 'ROADMAP', 'RES', 'CAP', 'IDEA', 'REV', 'FLOW',
+  'DIAG', 'AGENT', 'GCASE', 'BIZ', 'PILR', 'DOC', 'PROTO', 'CASE',
+  'DEC', 'LES', 'UIP', 'REF',
+]);
+
+/**
+ * Owner-ruled semantic family SURNAMES (Naming V3 Q3 rulings): BIZ for
+ * specs/business docs, PILR for pillar-anchored docs. They overlap
+ * KNOWN_TYPE_LABELS (both were legacy type labels), so {@link parseSpecId}
+ * needs them to disambiguate an era-3 `HS-<fileKey>-BIZ-<CAT>-<slug>` name
+ * from a legacy era-2 reading. Mirror: spex-console/src/lib/vault-id.ts.
+ */
+export const RULED_FAMILY_SURNAMES = new Set(['BIZ', 'PILR']);
+
+/**
+ * Type labels whose ids carry a RANDOM family key and are reordered by the
+ * family-first migration ([[HS-EPIC-MB2M]] scope; [[HS-EPIC-DLE3]]). ONLY these
+ * may be recomposed `HS-<familyKey>-<TYPE>`; slug/mnemonic kinds (PILR, DEC, LES,
+ * PROTO, DOC, ROADMAP, FLOW, BIZ, IDEA, …) carry free text in the second token, so
+ * reordering would corrupt them. Mirror of FAMILY_KEYED_TYPE_LABELS in
+ * spex-console/src/lib/vault-id.ts and MIGRATE_TYPES in migrate-ids-to-family-first.mjs.
+ */
+export const FAMILY_KEYED_TYPE_LABELS = new Set([
+  'TASK', 'EPIC', 'MIL', 'RES', 'CAP', 'DIAG', 'REV', 'AGENT', 'GCASE',
+]);
+
+/** True if `token` is a recognized type label (case-insensitive). */
+export function isTypeLabel(token) {
+  return KNOWN_TYPE_LABELS.has(String(token || '').toUpperCase());
+}
+
+/**
+ * Canonical family-first BARE id (`HS-<familyKey>-<TYPE>`) for an id/basename in
+ * EITHER ordering — ONLY for family-keyed kinds; null otherwise (so callers pass
+ * slug/mnemonic ids through unchanged) and null for unparseable input.
+ */
+export function toCanonicalFamilyFirstId(input) {
+  const p = parseSpecId(input);
+  if (!p || !FAMILY_KEYED_TYPE_LABELS.has(p.typeLabel)) return null;
+  // Routes through familyOf for the "family of this spec" derivation (V3 step
+  // 1). No frontmatter is available at this call site (string-only input), so
+  // this is behavior-preserving today; it becomes the real fallback path once
+  // a frontmatter-aware caller passes one through.
+  const familyKey = String(familyOf({ id: input }) ?? p.familyKey).toUpperCase();
+  return `HS-${familyKey}-${p.typeLabel}`;
+}
+
+/**
+ * Shape a valid EXPLICIT frontmatter `family` value must match: uppercase
+ * alphanumeric, 4+ chars — the same shape every family-key capture group in
+ * this repo's id regexes already requires. Not exported: callers that need
+ * "is this family-key-shaped" should go through {@link familyOf}.
+ */
+const FAMILY_KEY_SHAPE_RE = /^[A-Z0-9]{4,}$/;
+
+/**
+ * The family key of a spec: explicit `frontmatter.family` when present and
+ * well-formed, else the positional family key parsed from `id`/`basename`
+ * (`parseSpecId`). This is the ONE place family-key derivation should happen
+ * once a managed spec carries an explicit `family:` field — V3 migration step
+ * 1 ([[HS-8O69-EPIC-LKF9-relational-family-graph-authoring]],
+ * `dev-factory/handoffs/NAMING-V3-MIGRATION-BRIEF.md` §2.1). The positional
+ * fallback exists ONLY for specs not yet backfilled with `family:` and is
+ * slated for removal in step 4 — do not treat it as a permanent code path.
+ *
+ * - A malformed or empty explicit value (wrong shape, blank string) is NOT an
+ *   error: it silently falls back to positional parsing, exactly as if no
+ *   `family:` field were present at all.
+ * - `id` is preferred over `basename` for the positional fallback (the id is
+ *   the frontmatter-declared identity; a basename can lag a pending rename).
+ * - Returns null when nothing parses (no valid explicit field AND no
+ *   parseable `id`/`basename`).
+ *
+ * Mirror: `spex-console/src/lib/vault-id.ts` `familyOf` (TypeScript — keep the
+ * two in lockstep on any change here).
+ *
+ * @param {{ id?: string | null, basename?: string | null, frontmatter?: { family?: string | null } | null }} input
+ * @returns {string | null}
+ */
+export function familyOf(input) {
+  const explicit = input?.frontmatter?.family;
+  if (typeof explicit === 'string') {
+    const trimmed = explicit.trim();
+    if (FAMILY_KEY_SHAPE_RE.test(trimmed)) return trimmed;
+  }
+  if (input?.id) {
+    const fromId = parseSpecId(input.id);
+    if (fromId) return fromId.familyKey;
+  }
+  if (input?.basename) {
+    const fromBasename = parseSpecId(input.basename);
+    if (fromBasename) return fromBasename.familyKey;
+  }
+  return null;
+}
+
+/** Strip a trailing `.md` and surrounding whitespace from an id/basename/path. */
+function normalizeIdInput(input) {
+  return String(input || '')
+    .replace(/\.md$/i, '')
+    .trim();
+}
+
+/**
+ * Parse a spec id or basename into its canonical atoms.
+ *
+ * Returns `{ era, ordering, typeLabel, familyKey, fileKey, titleSlug, hs }` or
+ * `null` when the input is not a two-token HS spec id (e.g. a bare family token
+ * `HS-P2TR`, a bare type `HS-TASK`, or an unprefixed foundational doc like
+ * `entity-model`).
+ *
+ *   parseSpecId('HS-TASK-P2TR-foo')       → { era:1, ordering:'type-first',      typeLabel:'TASK', familyKey:'P2TR', fileKey:null, titleSlug:'foo' }
+ *   parseSpecId('HS-P2TR-TASK-foo')       → { era:2, ordering:'family-first',    typeLabel:'TASK', familyKey:'P2TR', fileKey:null, titleSlug:'foo' }
+ *   parseSpecId('HS-L6Y4-01D7-EPIC-foo')  → { era:3, ordering:'file-key-first',  typeLabel:'EPIC', familyKey:'01D7', fileKey:'L6Y4', titleSlug:'foo' }
+ *   parseSpecId('HS-TASK-P2TR')           → { …, titleSlug:'' }
+ *
+ * Tri-era rule ([[HS-8JXX-TASK-3BYT]]): the POSITION of the TYPE token after
+ * `HS-` identifies the era — position 1 = legacy type-first, position 2 =
+ * family-first (current), position 3 = new file-key-first. Position 3 is only
+ * tried when NEITHER position 1 nor position 2 matched, so an era-1/era-2
+ * basename is never reinterpreted as era-3 even if its slug's first word
+ * happens to collide with a type-label spelling.
+ *
+ * `typeLabel` / `familyKey` / `fileKey` are upper-cased (canonical). `titleSlug`
+ * preserves the input's casing. Matching accepts any case of the `HS-` prefix
+ * and type labels (pin paste / agent paste). When both of the first two tokens
+ * look like type labels the legacy type-first reading wins (defensive; should
+ * not occur with real ids).
+ */
+export function parseSpecId(input) {
+  const base = normalizeIdInput(input);
+  // Case-insensitive HS- prefix so pin/equality helpers accept pasted lowercase ids
+  // (e.g. isSpecPinnedToTop("HS-TASK-2WVZ", "hs-task-2wvz")). Mirror: vault-id.ts.
+  const m = base.match(/^HS-(.+)$/i);
+  if (!m) return null;
+  const tokens = m[1].split('-');
+  if (tokens.length < 2) return null;
+
+  const t1IsType = isTypeLabel(tokens[0]);
+  const t2IsType = isTypeLabel(tokens[1]);
+
+  if (t1IsType && !t2IsType) {
+    return {
+      era: 1,
+      ordering: 'type-first',
+      typeLabel: tokens[0].toUpperCase(),
+      familyKey: tokens[1].toUpperCase(),
+      fileKey: null,
+      titleSlug: tokens.slice(2).join('-'),
+      hs: 'HS',
+    };
+  }
+  if (t2IsType && !t1IsType) {
+    // Ruled family SURNAMES (owner Q3 rulings: BIZ for specs/business, PILR for
+    // pillar-anchored docs) sit in the FAMILY slot of era-3 names
+    // (HS-<fileKey>-BIZ-<CAT>-<slug>) while also living in KNOWN_TYPE_LABELS as
+    // legacy type labels. No real era-2 name ever carried BIZ/PILR in position
+    // 2 (era-2 business was HS-BIZ-<CAT>-<slug>, type-first), so when the
+    // leading token is file-key-shaped and a third token exists, the era-3
+    // surname reading is the correct one.
+    if (
+      RULED_FAMILY_SURNAMES.has(tokens[1].toUpperCase()) &&
+      FILE_KEY_RE.test(tokens[0].toUpperCase()) &&
+      tokens.length > 2
+    ) {
+      return {
+        era: 3,
+        ordering: 'file-key-first',
+        typeLabel: tokens[2].toUpperCase(),
+        familyKey: tokens[1].toUpperCase(),
+        fileKey: tokens[0].toUpperCase(),
+        titleSlug: tokens.slice(3).join('-'),
+        hs: 'HS',
+      };
+    }
+    return {
+      era: 2,
+      ordering: 'family-first',
+      typeLabel: tokens[1].toUpperCase(),
+      familyKey: tokens[0].toUpperCase(),
+      fileKey: null,
+      titleSlug: tokens.slice(2).join('-'),
+      hs: 'HS',
+    };
+  }
+  if (t1IsType && t2IsType) {
+    // Ambiguous (both reserved words) — treat as legacy type-first.
+    return {
+      era: 1,
+      ordering: 'type-first',
+      typeLabel: tokens[0].toUpperCase(),
+      familyKey: tokens[1].toUpperCase(),
+      fileKey: null,
+      titleSlug: tokens.slice(2).join('-'),
+      hs: 'HS',
+    };
+  }
+
+  // Neither of the first two tokens is a type label — try position 3
+  // (file-key-first era: HS-<fileKey>-<familyKey>-<TYPE>-<slug>).
+  if (tokens.length > 2 && isTypeLabel(tokens[2])) {
+    return {
+      era: 3,
+      ordering: 'file-key-first',
+      typeLabel: tokens[2].toUpperCase(),
+      familyKey: tokens[1].toUpperCase(),
+      fileKey: tokens[0].toUpperCase(),
+      titleSlug: tokens.slice(3).join('-'),
+      hs: 'HS',
+    };
+  }
+
+  return null;
+}
+
+function rebuildBasename(parts, ordering) {
+  const tail = parts.titleSlug ? `-${parts.titleSlug}` : '';
+  const middle =
+    ordering === 'family-first'
+      ? `${parts.familyKey}-${parts.typeLabel}`
+      : `${parts.typeLabel}-${parts.familyKey}`;
+  return `${parts.hs}-${middle}${tail}`;
+}
+
+/** Canonicalize any spec id/basename to the legacy **type-first** ordering. */
+export function toTypeFirstBasename(input) {
+  const parts = parseSpecId(input);
+  return parts ? rebuildBasename(parts, 'type-first') : null;
+}
+
+/** Canonicalize any spec id/basename to the new **family-first** ordering. */
+export function toFamilyFirstBasename(input) {
+  const parts = parseSpecId(input);
+  return parts ? rebuildBasename(parts, 'family-first') : null;
+}
+
+/**
+ * Given a spec id/basename in one ordering, return the SAME id/basename in the
+ * opposite ordering — or `null` when the input is unparseable or the flip would
+ * be a no-op (case-insensitively). This is the single primitive a dual-read
+ * resolver needs: try the input as-is, then try `alternateOrderingBasename(input)`.
+ *
+ * Only flips between the two DUAL-READ-era orderings (type-first ↔
+ * family-first, [[HS-EPIC-6SNQ]]); era-3 (file-key-first) has no defined
+ * binary flip here — that alternation is scoped to the step-4 rename epic —
+ * so a file-key-first input returns `null` rather than a guessed shape.
+ */
+export function alternateOrderingBasename(input) {
+  const parts = parseSpecId(input);
+  if (!parts || parts.era === 3) return null;
+  const alt = rebuildBasename(
+    parts,
+    parts.ordering === 'type-first' ? 'family-first' : 'type-first',
+  );
+  const orig = normalizeIdInput(input);
+  return alt.toLowerCase() === orig.toLowerCase() ? null : alt;
+}
+
+/**
+ * True when `input` is a **bare family token** — `HS-<familyKey>` with no type
+ * label and no title slug (e.g. `HS-P2TR`). Such a token names a whole
+ * shared-suffix family, not a single spec, so it is ambiguous for any mutating
+ * operation. A bare type token (`HS-TASK`) is NOT a family token.
+ */
+export function isBareFamilyToken(input) {
+  const base = normalizeIdInput(input);
+  const m = base.match(/^HS-([A-Za-z0-9]+)$/);
+  if (!m) return false;
+  return !isTypeLabel(m[1]);
+}
+
+/**
+ * Guard for mutating MCP/CLI ops: reject a `spec_id` that is a bare family token
+ * (ambiguous — resolves to a family, not one spec). Returns an error object
+ * `{ error, message }` to surface to the caller, or `null` when the id is
+ * unambiguous enough to act on. Read-only resolvers do NOT call this — they fan
+ * a family token out to a set or just miss.
+ */
+export function requireResolvableSpecId(input) {
+  if (isBareFamilyToken(input)) {
+    const base = normalizeIdInput(input);
+    return {
+      error: 'AMBIGUOUS_SPEC_ID',
+      message:
+        `"${base}" is a bare family key, which names a whole shared-suffix family ` +
+        `rather than one spec. Pass a full basename that includes the type label ` +
+        `(e.g. ${base}-TASK-<slug> or HS-TASK-${base.replace(/^HS-/, '')}-<slug>).`,
+    };
+  }
+  return null;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Display formatting ([[HS-57WO-094P-RES-long-form-spec-id-display-hs-file-key]])
+//
+// Ids are MINTED and STORED short (`HS-<fileKey>`) because the file key alone is
+// unique. They are READ long: a bare file key hides the family key that names
+// the milestone lineage, and hides the entity type. Everything below is
+// display-only — nothing here participates in minting, lookup, or persistence.
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Frontmatter `type:` (lowercase kind) → basename TYPE label. Lets a display
+ * caller that holds a loaded spec supply the type without re-parsing a
+ * basename. Mirror: spex-console/src/lib/vault-id.ts `FRONTMATTER_TYPE_LABELS`.
+ */
+export const FRONTMATTER_TYPE_LABELS = {
+  task: 'TASK',
+  epic: 'EPIC',
+  milestone: 'MIL',
+  research: 'RES',
+  capture: 'CAP',
+  diagnose: 'DIAG',
+  review: 'REV',
+  agent: 'AGENT',
+  'golden-case': 'GCASE',
+  roadmap: 'ROADMAP',
+  idea: 'IDEA',
+  flow: 'FLOW',
+  doc: 'DOC',
+  protocol: 'PROTO',
+  decision: 'DEC',
+  lesson: 'LES',
+  'ui-pattern': 'UIP',
+  reference: 'REF',
+};
+
+/**
+ * TYPE label for a frontmatter `type:` value (or for an already-uppercase label
+ * passed through). Returns null for unknown/blank input — callers fall back to
+ * the label parsed out of the basename.
+ */
+export function typeLabelForKind(kind) {
+  const raw = String(kind || '').trim();
+  if (!raw) return null;
+  const mapped = FRONTMATTER_TYPE_LABELS[raw.toLowerCase()];
+  if (mapped) return mapped;
+  const upper = raw.toUpperCase();
+  return KNOWN_TYPE_LABELS.has(upper) ? upper : null;
+}
+
+/**
+ * The long, human-facing form of a spec id: `HS-<fileKey>-<familyKey>`, plus the
+ * TYPE label when `includeType` is set.
+ *
+ *   formatDisplayId('HS-57WO-094P-RES-long-form-…')                  → 'HS-57WO-094P'
+ *   formatDisplayId('HS-57WO-094P-RES-long-form-…', {includeType:1}) → 'HS-57WO-094P-RES'
+ *   formatDisplayId('HS-57WO', { basename: 'HS-57WO-094P-RES-…' })   → 'HS-57WO-094P'
+ *   formatDisplayId('HS-57WO', { frontmatter: { family: '094P' } })  → 'HS-57WO-094P'
+ *
+ * `includeType` exists because Atom 2 of the display contract is
+ * context-dependent: a surface whose surrounding prose already names the kind
+ * ("Ready to claim **task** `HS-…`") must NOT also suffix `-TASK`. Surfaces with
+ * no such prose — log lines, table cells — pass `includeType: true`.
+ *
+ * Resolution order for the family key and type, cheapest first:
+ *   1. `options.frontmatter` / `options.type` (free when the caller holds the spec)
+ *   2. positional parse of `options.basename` (free — era-3 basenames carry both)
+ *   3. positional parse of `input` itself
+ * A caller holding only a short id and no context should look the basename up in
+ * `.heyspex/vault-index.json` (`specs[].path`) and pass it as `basename`.
+ *
+ * **Degradation is total: this never throws and never blocks a render.** When
+ * the family key cannot be resolved the input is returned unchanged — a bare id
+ * in a log line beats an exception in a claim banner.
+ *
+ * **Legacy names always carry their TYPE**, regardless of `includeType`: an
+ * era-1/era-2 spec has no separate file key, so `HS-<familyKey>` alone would be
+ * a bare family token (ambiguous — see {@link isBareFamilyToken}). Keeping the
+ * label preserves resolvability.
+ *
+ * **`familyInContext`** (owner ruling 2026-08-17, how-spec-ids-and-naming-work
+ * §2): when the surrounding UI already carries the family — a family-group
+ * header, a funnel/tree anchored on one initiative — rows render the BARE file
+ * id (`HS-<fileKey>`, the stored `id:` form) instead of repeating the family.
+ * `includeType` is IGNORED under this option: a type suffix on a bare file key
+ * would re-mint the retired era-2 shape (`HS-<token>-<TYPE>`). Legacy ids (no
+ * file key) keep their full family-first form.
+ *
+ * Mirror: spex-console/src/lib/vault-id.ts `formatDisplayId` — keep in lockstep.
+ *
+ * @param {string} input id or basename, in any era
+ * @param {{ includeType?: boolean, basename?: string|null, frontmatter?: object|null, type?: string|null, familyInContext?: boolean }} [options]
+ * @returns {string}
+ */
+export function formatDisplayId(input, options = {}) {
+  const {
+    includeType = false,
+    basename = null,
+    frontmatter = null,
+    type = null,
+    familyInContext = false,
+  } = options;
+  const raw = normalizeIdInput(input);
+  if (!raw) return String(input ?? '');
+
+  const parsed = (basename && parseSpecId(basename)) || parseSpecId(raw);
+  const familyKey = familyOf({ id: raw, basename, frontmatter }) ?? parsed?.familyKey ?? null;
+  if (!familyKey) return raw; // no family in hand — nothing to lengthen
+
+  const typeLabel =
+    typeLabelForKind(type ?? frontmatter?.type) ?? parsed?.typeLabel ?? null;
+  const fileKey = fileKeyFromBasename(basename ?? raw) ?? leadingFileKeyToken(raw);
+
+  if (!fileKey) {
+    // Legacy (no file key): the canonical family-first form IS the display form,
+    // and its TYPE is load-bearing for resolvability, so it is never dropped —
+    // familyInContext included (there is no shorter unambiguous form to give).
+    return typeLabel ? `HS-${familyKey}-${typeLabel}` : raw;
+  }
+  // Context-scoped bare file id (owner ruling 2026-08-17): the family lives in
+  // a surrounding header, so the row shows the stored `id:` form alone. No
+  // type suffix ever — `HS-<fileKey>-<TYPE>` is the retired era-2 shape.
+  if (familyInContext) return `HS-${fileKey}`;
+  const head = `HS-${fileKey}-${familyKey}`;
+  return includeType && typeLabel ? `${head}-${typeLabel}` : head;
+}
+
+/**
+ * File key of a BARE short id (`HS-57WO`) — the era-3 shape `parseSpecId`
+ * rejects for having only one token. Returns null when the token is a type
+ * label or is not file-key-shaped.
+ *
+ * Exported (mirror of `bareFileKeyOf` in spex-console/src/lib/vault-id.ts):
+ * era-3 `id:` values are the STORED form for every newly minted spec, so
+ * validators need a shared way to recognize one rather than re-deriving the
+ * shape from a local regex.
+ * @param {string|null|undefined} input
+ * @returns {string|null}
+ */
+export function bareFileKeyOf(input) {
+  const m = normalizeIdInput(input).match(/^HS-([A-Za-z0-9]+)$/);
+  if (!m) return null;
+  const token = m[1].toUpperCase();
+  if (KNOWN_TYPE_LABELS.has(token)) return null;
+  return FILE_KEY_RE.test(token) ? token : null;
+}
+
+const leadingFileKeyToken = bareFileKeyOf;
+
+/**
+ * Collapse ANY pasted spec-id form to its era-3 FILE KEY — the token the
+ * database and every era-3 `id:` actually store ([[HS-XV4W]] promote failure,
+ * 2026-08-21: a human pastes the DISPLAY form `HS-<fileKey>-<familyKey>`
+ * because that is what agents are told to render, and the DB lookup 404'd it).
+ * Owner ruling: resolvers must recognize any potential form of the
+ * filename/id, exactly like the local disk lookup does.
+ *
+ * Accepted forms → file key:
+ *   - bare short id            `HS-XV4W`
+ *   - display long id          `HS-XV4W-HV6H`
+ *   - full era-3 id/basename   `HS-XV4W-HV6H-CAP-some-slug` (with/without .md)
+ * Returns null for era-1/era-2 ids (they have no file key), bare type tokens,
+ * and anything else unrecognizable — callers then use the input as given.
+ * @param {string|null|undefined} input
+ * @returns {string|null}
+ */
+export function lookupFileKeyOf(input) {
+  const base = normalizeIdInput(input);
+  if (!base) return null;
+  const bare = bareFileKeyOf(base);
+  if (bare) return bare;
+  const parsed = parseSpecId(base);
+  if (parsed) return parsed.era === 3 ? (parsed.fileKey ?? null) : null;
+  // Two-token display form: parseSpecId rejects it (neither token is a type
+  // label, no third token) — recognize it here. The second token must be
+  // key-shaped too, or this would misread era-agnostic garbage.
+  const m = base.match(/^HS-([A-Za-z0-9]+)-([A-Za-z0-9]+)$/i);
+  if (!m) return null;
+  const t0 = m[1].toUpperCase();
+  const t1 = m[2].toUpperCase();
+  if (KNOWN_TYPE_LABELS.has(t0) || KNOWN_TYPE_LABELS.has(t1)) return null;
+  if (!FILE_KEY_RE.test(t0) || !FILE_KEY_RE.test(t1)) return null;
+  return t0;
+}
+
+/**
+ * The short lookup id (`HS-<fileKey>`) for any recognizable era-3 id form, or
+ * null. Convenience wrapper over {@link lookupFileKeyOf} for resolvers that
+ * want the full id string to query with.
+ * @param {string|null|undefined} input
+ * @returns {string|null}
+ */
+export function shortLookupIdOf(input) {
+  const key = lookupFileKeyOf(input);
+  return key ? `HS-${key}` : null;
+}
+
+/**
+ * Is `id` a well-formed **era-3** frontmatter id for the spec stored at
+ * `basename`? Mirror of `isEra3SpecId` in spex-console/src/lib/vault-id.ts —
+ * era-3 ids are type-less (`HS-<fileKey>`), so a per-type id pattern cannot
+ * describe them; the basename's leading token is what makes the bare id
+ * verifiable. A bare id on a legacy (era-1/era-2) filename still fails.
+ * @param {string|null|undefined} id
+ * @param {string|null|undefined} basename
+ * @returns {boolean}
+ */
+export function isEra3SpecId(id, basename) {
+  const raw = normalizeIdInput(id);
+  if (!raw) return false;
+  if (parseSpecId(raw)?.era === 3) return true;
+  const fileKey = bareFileKeyOf(raw);
+  if (!fileKey) return false;
+  const parsed = parseSpecId(basename ?? '');
+  return parsed?.era === 3 && (parsed.fileKey ?? '').toUpperCase() === fileKey;
+}