heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/spec-edit-tools.mjs

@@ -0,0 +1,453 @@
+// Spec editing tools: heyspex_regen_task, regen_tasks_for_epic, backfill_epic,
+// edit_file, propose_metadata, list_known_tags, canvas_inbox. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeCanvasInbox } from './canvas-inbox.mjs';
+import { consoleFetch, controlError, controlOk } from './console-transport.mjs';
+import { detectTagDrift } from './plan-ground.mjs';
+import { consoleErrorMessage } from './console-fetch.mjs';
+import { detectAgentIdentity, getConsoleUrl } from './mcp-config.mjs';
+import { resolveVaultWriteMode } from './read-path.mjs';
+import { deferredPayloadFromError, splitRawSpec, updateSpecViaConsole } from './cloud-vault-writes.mjs';
+import { writeFileSync } from 'node:fs';
+import { executeShipEpicCloudAware } from './plan-push.mjs';
+import { executeRegenTask, executeRegenTasksForEpic } from './regen-tasks.mjs';
+import { loadTask } from './vault-io.mjs';
+import { InvalidListCursorError, fitPageToByteBudget, resolvePageLimit } from './list-tools.mjs';
+import { DEFAULT_TOOL_BUDGET_BYTES } from './response-budget.mjs';
+
+export function handleRegenTask(vaultRoot, args = {}) {
+  const result = executeRegenTask(vaultRoot, {
+    task_id: args.task_id,
+    commit: args.commit === true || args.commit === 'true',
+    new_body: args.new_body,
+    retire_reason: args.retire_reason,
+    loadTask: (ref) => loadTask(vaultRoot, ref),
+  });
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    isError: result.ok === false,
+  };
+}
+
+export function handleRegenTasksForEpic(vaultRoot, args = {}) {
+  const result = executeRegenTasksForEpic(vaultRoot, {
+    epic_id: args.epic_id,
+    commit: args.commit === true || args.commit === 'true',
+    task_specs: args.task_specs,
+    loadTask: (ref) => loadTask(vaultRoot, ref),
+  });
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    isError: result.ok === false,
+  };
+}
+
+/**
+ * [[HS-Y00G-EPIC]] — Safe file edit: claim → write → release.
+ * Acquires the file claim, writes content to disk, and releases the claim.
+ * If claim fails (already claimed by another agent), returns the conflict info.
+ *
+ * WHERE THE WRITE GOES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+ * The write mode is resolved ONCE here, at the handler entry, and threaded to
+ * step 2 below:
+ *
+ *   - `local` — byte-identical to the original behavior: `writeFileSync` to
+ *     `args.file_path`, and the success payload carries exactly the fields it
+ *     always did.
+ *   - `cloud` — the mutated markdown is split back into the
+ *     `{ frontmatter, body }` pair `PUT /api/specs/:id` takes and sent through
+ *     {@link updateSpecViaConsole}. Nothing touches this machine's disk: a
+ *     markdown file written in cloud reliance is a split brain, a document on a
+ *     machine the console's index has never heard of (and that may hold no
+ *     vault clone at all).
+ *
+ * The spec id comes from the POST-EDIT content's own `id:` frontmatter — the
+ * caller has already produced the finished document, so its frontmatter is the
+ * authority on which spec this edit replaces. Content with no resolvable `id:`
+ * (a non-spec file, or a spec fragment) has NO cloud route: there is no console
+ * verb for "write these bytes to this arbitrary path". That degrades explicitly
+ * as `CLOUD_MODE_UNSUPPORTED_WRITE` naming the file — never a silent fallback
+ * to the disk write the mode just forbade.
+ *
+ * @param {object} args
+ * @param {object} [deps] Injection seam so tests drive every branch without a
+ *   socket: `consoleFetch` (defaults to the real transport), `consoleUrl`
+ *   (defaults to `getConsoleUrl()`), `resolveWriteMode` (defaults to
+ *   `resolveVaultWriteMode`).
+ */
+export async function handleEditFile(args = {}, deps = {}) {
+  if (!args.file_path || typeof args.file_path !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'file_path is required' }) }],
+    };
+  }
+  if (typeof args.content !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'content is required and must be a string' }) }],
+    };
+  }
+
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const fetchDep = deps.consoleFetch ?? consoleFetch;
+  // Resolved ONCE per handler entry, then threaded to step 2. `?? 'local'`
+  // keeps every pre-existing caller on exactly the disk write it had.
+  const writeMode = (await (deps.resolveWriteMode ?? resolveVaultWriteMode)()) ?? 'local';
+
+  // Step 1: Acquire claim
+  const claimBody = {
+    file_path: args.file_path,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    ttl_ms: 300000, // 5-minute default for file claims
+  };
+  if (args.working_spec_id && typeof args.working_spec_id === 'string') {
+    claimBody.working_spec_id = args.working_spec_id;
+  }
+
+  const claimResult = await fetchDep('/api/file-claims/acquire', { method: 'POST', body: claimBody });
+
+  if (claimResult.status === 409) {
+    const conflict = claimResult.body && typeof claimResult.body === 'object' ? claimResult.body : {};
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({
+        error: 'FILE_CLAIMED',
+        message: `CONFLICT: file "${args.file_path}" is claimed by another agent.`,
+        claimed_by: conflict.existing?.agent ?? 'unknown',
+        claimed_session: conflict.existing?.sessionId ?? null,
+        expires_at: conflict.existing?.expiresAt ?? null,
+        conflict: conflict,
+      }, null, 2) }],
+    };
+  }
+
+  if (!claimResult.ok) {
+    return controlError(claimResult, 'EDIT_FILE_CLAIM_FAILED', { file_path: args.file_path });
+  }
+
+  // Always release before returning a failure, so a rejected write never leaves
+  // the file locked for the claim's full TTL.
+  const releaseClaim = () =>
+    fetchDep('/api/file-claims/release', { method: 'DELETE', body: { file_path: args.file_path } });
+
+  // Step 2: Write — to disk in local mode, to `PUT /api/specs/:id` in cloud mode.
+  let cloudWrite = null;
+  if (writeMode === 'cloud') {
+    const consoleUrl = deps.consoleUrl ?? getConsoleUrl();
+    const { frontmatter, body } = splitRawSpec(args.content);
+    const specId = typeof frontmatter?.id === 'string' ? frontmatter.id.trim() : '';
+    if (!specId) {
+      await releaseClaim();
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'CLOUD_MODE_UNSUPPORTED_WRITE',
+          message:
+            `heyspex_edit_file cannot write "${args.file_path}" in cloud vault-write mode: the content carries no `
+            + '`id:` frontmatter, and the console has no route that writes arbitrary bytes to an arbitrary path '
+            + '(POST /api/specs creates a typed spec, PUT /api/specs/:id replaces one by id). NOTHING WAS WRITTEN — '
+            + 'the local disk write is deliberately NOT used as a fallback, because a file written here would be '
+            + 'invisible to the console index this session reads from.',
+          file_path: args.file_path,
+          write_mode: 'cloud',
+          console_url: consoleUrl,
+          on_disk: false,
+        }, null, 2) }],
+      };
+    }
+    try {
+      cloudWrite = await updateSpecViaConsole({
+        consoleFetch: fetchDep,
+        consoleUrl,
+        specId,
+        frontmatter,
+        body,
+      });
+    } catch (err) {
+      await releaseClaim();
+      // Outage: the edit was queued to the write outbox (truthful receipt, not an error).
+      const deferred = deferredPayloadFromError(err);
+      if (deferred) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ ...deferred, file_path: args.file_path, spec_id: specId, write_mode: 'cloud', on_disk: false }, null, 2) }],
+        };
+      }
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+          message: String(err?.message ?? err),
+          file_path: args.file_path,
+          spec_id: specId,
+          write_mode: 'cloud',
+          on_disk: false,
+          ...(err?.notFound ? { not_found: true } : {}),
+        }, null, 2) }],
+      };
+    }
+  } else {
+    try {
+      writeFileSync(args.file_path, args.content, 'utf8');
+    } catch (err) {
+      // Release the claim on write failure so the file isn't locked forever
+      await releaseClaim();
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'WRITE_FAILED',
+          message: `Failed to write file: ${err?.message ?? err}`,
+          file_path: args.file_path,
+        }) }],
+      };
+    }
+  }
+
+  // Step 3: Release claim
+  const releaseResult = await releaseClaim();
+
+  return controlOk({
+    written: true,
+    file_path: args.file_path,
+    released: releaseResult.ok ? releaseResult.body?.released ?? true : false,
+    agent: identity.agent,
+    session_id: identity.sessionId,
+    // Cloud-only additions — the local payload stays byte-identical to the
+    // shape every existing caller already parses.
+    ...(cloudWrite
+      ? {
+          write_mode: 'cloud',
+          on_disk: false,
+          spec_id: cloudWrite.specId,
+          rel_path: cloudWrite.relPath,
+          console_url: cloudWrite.consoleUrl,
+        }
+      : {}),
+  });
+}
+
+/**
+ * Known-tags paging contract, mirrored from the console route
+ * (`spex-console/src/lib/scheduler/known-tags-query.ts`): the cursor is
+ * base64url JSON `{ c: count, t: tag }` over the `(count DESC, tag ASC)` sort
+ * key of the aggregate query. Encoded here only to RE-POINT the cursor when the
+ * byte budget trims a page — the console mints every cursor it hands out.
+ */
+export const KNOWN_TAGS_TOOL = Object.freeze({
+  default_limit: 100,
+  max_limit: 500,
+  // Measured on `content[0].text`; the dispatcher re-measures the whole envelope (escaped), so leave headroom.
+  byte_budget: Math.floor(DEFAULT_TOOL_BUDGET_BYTES * 0.8),
+});
+
+export function encodeKnownTagsCursor({ count, tag }) {
+  return Buffer.from(JSON.stringify({ c: Number(count) || 0, t: String(tag ?? '') }), 'utf8').toString('base64url');
+}
+
+/**
+ * `heyspex_list_known_tags` — the closed tag vocabulary for the focus-areas NLU
+ * path ([[HS-TASK-I0EK]] / [[HS-EPIC-7WJN]]). GET /api/scheduler/known-tags →
+ * ONE page `{ tags: [{ name, count }], next_cursor, page }` from an aggregate
+ * query paged with a keyset cursor over (count, tag)
+ * ([[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]], resolving
+ * [[HS-7QM6-1Q1C-DIAG-heyspex-list-known-tags-response-busts-t]] — the reply
+ * that once hit 138 KB). `limit` and `after` pass straight through to the
+ * console; the page is then fitted to the tool's byte budget, re-pointing
+ * `next_cursor` at the last tag kept so nothing is lost. Agents call this
+ * before proposing a focus pivot so they only suggest tags that exist.
+ * Requires a reachable console.
+ *
+ * Augments the console response with an additive `drift` array ([[HS-TASK-H0SI]]
+ * / [[HS-EPIC-OOPW]]): near-duplicate tag pairs within the page flagged by
+ * lexical string similarity (NOT embeddings) so the agent can propose a merge to
+ * keep the closed vocabulary clean. No tag is mutated here — `drift` is a
+ * suggestion signal only.
+ */
+export async function handleListKnownTags(args = {}, { consoleFetch: fetchDep = consoleFetch, byteBudget = KNOWN_TAGS_TOOL.byte_budget } = {}) {
+  const limit = resolvePageLimit(args.limit, KNOWN_TAGS_TOOL);
+  const params = new URLSearchParams({ limit: String(limit) });
+  if (typeof args.after === 'string' && args.after) params.set('after', args.after);
+  const result = await fetchDep(`/api/scheduler/known-tags?${params.toString()}`);
+  if (!result.ok) {
+    if (result.status === 400 && result.body?.error === 'invalid_cursor') {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_CURSOR', message: new InvalidListCursorError().message, tool: 'heyspex_list_known_tags' }, null, 2) }],
+      };
+    }
+    return controlError(result, 'KNOWN_TAGS_FAILED');
+  }
+  const body = result.body && typeof result.body === 'object' ? result.body : {};
+  const tags = Array.isArray(body.tags) ? body.tags : [];
+  const base = {
+    ...body,
+    tags,
+    next_cursor: typeof body.next_cursor === 'string' && body.next_cursor ? body.next_cursor : null,
+    page: { limit, returned: tags.length, byte_budget: byteBudget, budget_trimmed: false, ...(body.page ?? {}) },
+  };
+  const fitOpts = {
+    rows_key: 'tags',
+    // A page of tags that would fill the whole budget leaves no room for the
+    // drift signal the tool exists to surface: reserve a tenth for the
+    // strongest pairs. A page that needs no trim gets the whole budget.
+    byte_budget: byteBudget - Math.floor(byteBudget * 0.1),
+    cursorFor: (row) => encodeKnownTagsCursor({ count: row.count, tag: row.name }),
+  };
+  // 1. Fit the TAGS to the budget first (with an empty drift envelope in
+  //    place so its bytes are accounted for) — the cursor must land on a tag
+  //    the caller received, and drift over an un-returned tag is noise.
+  let current = fitPageToByteBudget({ ...base, drift: [] }, fitOpts).result;
+  // 2. Drift over the returned page only. It is pairwise (quadratic in page
+  //    size) and sorted by similarity desc, so when it would bust the budget
+  //    keep the strongest pairs that fit. Only when not even zero pairs fit
+  //    (the truncation markers cost a few bytes) does one more tag go, and
+  //    drift is recomputed over what remains.
+  for (;;) {
+    const fitted = fitKnownTagsDrift(current, detectTagDrift(current.tags), byteBudget);
+    if (fitted) return { content: [{ type: 'text', text: fitted.text }] };
+    if (current.tags.length <= 1) {
+      // A lone tag that cannot fit even with no drift: return it rather than
+      // an empty page with no way forward (the list-tools rule).
+      return { content: [{ type: 'text', text: JSON.stringify({ ...current, drift: [] }, null, 2) }] };
+    }
+    const kept = current.tags.slice(0, -1);
+    current = {
+      ...current,
+      tags: kept,
+      next_cursor: fitOpts.cursorFor(kept[kept.length - 1]),
+      page: { ...current.page, returned: kept.length, budget_trimmed: true },
+    };
+  }
+}
+
+/**
+ * Largest similarity-desc prefix of `drift` whose page fits `byteBudget`:
+ * the whole list untouched when it fits, else `page.drift_truncated: true` +
+ * `drift_dropped`. `null` when not even an empty drift list fits.
+ */
+function fitKnownTagsDrift(page, drift, byteBudget) {
+  const serialize = (payload) => JSON.stringify(payload, null, 2);
+  const fits = (text) => Buffer.byteLength(text, 'utf8') <= byteBudget;
+  const full = { ...page, drift };
+  const fullText = serialize(full);
+  if (fits(fullText)) return { payload: full, text: fullText };
+  let lo = 0;
+  let hi = drift.length - 1;
+  let best = null;
+  while (lo <= hi) {
+    const mid = (lo + hi) >>> 1;
+    const candidate = { ...page, drift: drift.slice(0, mid), page: { ...page.page, drift_truncated: true, drift_dropped: drift.length - mid } };
+    const text = serialize(candidate);
+    if (fits(text)) {
+      best = { payload: candidate, text };
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
+/**
+ * AI metadata proposal — [[HS-TASK-TAOD]] Phase 4 of [[HS-EPIC-Y9OJ]].
+ *
+ * Thin MCP wrapper around console `POST /api/ai/propose-metadata` (Haiku 4.5).
+ * One-shot at create time — agents must NOT call this on edit, status change,
+ * or update flows; that's the closed-loop bias the epic explicitly rejects.
+ */
+export async function handleProposeMetadata(args = {}) {
+  const name = typeof args?.name === 'string' ? args.name : '';
+  const body = typeof args?.body === 'string' ? args.body : '';
+  if (!name.trim() && !body.trim()) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            { ok: false, reason: 'invalid_request', message: 'name or body is required' },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  }
+
+  const payload = { action: 'propose', name, body };
+  if (typeof args?.specType === 'string') payload.specType = args.specType;
+  if (typeof args?.parentExcerpt === 'string') payload.parentExcerpt = args.parentExcerpt;
+
+  const result = await consoleFetch('/api/ai/propose-metadata', {
+    method: 'POST',
+    body: payload,
+  });
+
+  if (!result.ok) {
+    const reason =
+      result.errorKind === 'timeout'
+        ? 'console_timeout'
+        : result.status === 0
+          ? 'console_unreachable'
+          : 'console_error';
+    const errorPayload = {
+      ok: false,
+      reason,
+      message: consoleErrorMessage(
+        result,
+        `Console /api/ai/propose-metadata returned ${result.status}`,
+      ),
+      console_response: result.body,
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(errorPayload, null, 2) }],
+    };
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result.body, null, 2) }],
+  };
+}
+
+// Ground-truth dev-server status. The heavy logic lives in the repo's
+// scripts/dev-server-status.mjs (the shared core for the hs CLI verb and the
+// PreToolUse reminder hook too); we dynamic-import it from the vault root so
+// the three faces stay in lockstep. Must never throw out of the tool call.
+export async function handleCanvasInbox(vaultRoot, args = {}) {
+  // Session id: explicit arg wins; otherwise the ambient Claude Code session.
+  const explicit = typeof args.session_id === 'string' ? args.session_id.trim() : '';
+  const sessionId =
+    explicit ||
+    (process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || '').trim();
+
+  const result = await executeCanvasInbox({ vaultRoot, sessionId });
+  return {
+    ...(result.ok ? {} : { isError: true }),
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/**
+ * `heyspex_ship_epic` / `backfill_epic`. Cloud-aware entry
+ * ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]] sweep):
+ * `executeShipEpicCloudAware` resolves `resolveVaultWriteMode()` ONCE and either
+ * runs the untouched synchronous disk path (`local`) or creates the epic, its
+ * tasks and the review doc through `POST /api/specs` in create-first/link-second
+ * order (`cloud`). The handler became `async` for that — awaiting is safe in
+ * both modes, since the local branch still returns the same plain object.
+ */
+export async function handleShipEpic(vaultRoot, args) {
+  const result = await executeShipEpicCloudAware(vaultRoot, args);
+  if (result.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}

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

@@ -114,6 +114,26 @@ export function findReviewDocForSpec(vaultRoot, parentSpecId) {
  */
 export const FILE_KEY_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
 
+/**
+ * `hs next CJV2` → `HS-CJV2` (owner ruling 2026-09-01): typing the bare file
+ * key is the natural gesture — the `HS-` prefix carries no information the
+ * CLI needs, so requiring it is friction. Accepts the long display form too
+ * (`CJV2-90JL`, `CJV2-90JL-EPIC`) by normalizing on the FIRST segment.
+ *
+ * Returns the `HS-`-prefixed uppercase id, or `null` when the token is not a
+ * spec-id shape at all (so the caller can keep its own "unexpected argument"
+ * error). A token that already starts with `HS-` comes back uppercased and
+ * otherwise untouched. Mirror: spex-console/src/lib/vault-id.ts
+ * `normalizeBareSpecIdToken`.
+ */
+export function normalizeBareSpecIdToken(input) {
+  const token = String(input ?? '').trim().toUpperCase();
+  if (!token) return null;
+  if (token.startsWith('HS-')) return token;
+  const head = token.split('-')[0];
+  return FILE_KEY_RE.test(head) ? `HS-${token}` : null;
+}
+
 /**
  * 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
@@ -202,14 +222,36 @@ export function allocateFileKey(occupied, options = {}) {
 }
 
 /**
- * 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]]).
+ * Mint a FILE KEY against an ALREADY-RESOLVED occupancy set. `randomUnit` is
+ * injectable for tests. `occupied` must be 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]]).
+ *
+ * TAKES THE OCCUPANCY, NOT A VAULT ROOT ([[HS-FJWL]]). This used to be
+ * `mintFileKey(vaultRoot)` and resolved occupancy itself, by walking
+ * `specs/**` — correct on the disk tier, blind on the cloud tier, where a
+ * filed spec has a Neon row and no local `.md` and the stale local clone still
+ * answers with a large, plausible-looking set. File keys are the unique
+ * per-file identity under Naming V3, so a blind scan there re-issues a live
+ * id. Callers now resolve occupancy for THEIR tier —
+ * `collectOccupiedKeysEitherKindViaTier` (occupied-keys.mjs) on a tier-aware
+ * path, `collectOccupiedKeysEitherKind` below on a path that is disk-only by
+ * construction — and hand the set in.
+ *
+ * The `Set` check is the migration's fail-loud: a call site left passing a
+ * vaultRoot string would otherwise mint against `collectOccupiedKeysEitherKind`
+ * of nothing, i.e. against an empty set, i.e. duplicates. Refuse instead.
  */
-export function mintFileKey(vaultRoot, options = {}) {
-  return allocateFileKey(collectOccupiedKeysEitherKind(vaultRoot), options);
+export function mintFileKey(occupied, options = {}) {
+  if (!(occupied instanceof Set)) {
+    throw new TypeError(
+      'mintFileKey(occupied, options) takes a resolved occupancy Set, not a vaultRoot ' +
+        '([[HS-FJWL]]). Use collectOccupiedKeysEitherKindViaTier(vaultRoot, { tier, consoleUrl }) ' +
+        'on a tier-aware path, or collectOccupiedKeysEitherKind(vaultRoot) on a disk-only one.',
+    );
+  }
+  return allocateFileKey(occupied, options);
 }
 
 /**
@@ -267,6 +309,20 @@ export function collectOccupiedKeysEitherKind(vaultRoot) {
  * 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.
+ *
+ * DELIBERATELY STILL DISK-ONLY — do not "fix" this into a network call
+ * ([[HS-FJWL]]). {@link mintFileKey} was made tier-aware because a file key is
+ * the unique per-file identity: re-issuing one is a duplicate id. A FAMILY key
+ * is the opposite — any number of specs may legally share one (V3 shared-
+ * surname model, see {@link collectOccupiedFamilyKeysFromVault}), so this
+ * occupancy scan is a "pick something fresh" heuristic, NOT a uniqueness gate.
+ * Missing a cloud-only family key costs at most a family name reused by an
+ * unrelated spec, which the model already permits; paying a paged console walk
+ * per family mint would buy nothing. The cross-namespace half
+ * ([[HS-SJOT-AEP1-DIAG]] — a family key must not equal a FILE key) is carried
+ * by the union below on the disk tier and, in cloud reliance, by the console's
+ * own `createSpec` mint, which resolves occupancy through `loadAll()` and is
+ * tier-correct by construction.
  */
 export function mintFamilyKey(vaultRoot, options = {}) {
   return allocateFileKey(collectOccupiedKeysEitherKind(vaultRoot), options);
@@ -553,21 +609,41 @@ export function isBareFamilyToken(input) {
 }
 
 /**
- * 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.
+ * Guard for mutating MCP/CLI ops: reject a `spec_id` that is a bare `HS-XXXX`
+ * token the caller has not proven names exactly 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.
+ *
+ * WORDING ([[HS-05ZW-XHR4-DIAG-the-capture-dropped-it-warning-blamed]] follow-on):
+ * {@link isBareFamilyToken} is SHAPE-ONLY — `HS-05ZW` is exactly as likely to be
+ * an era-3 FILE key (the stored `id:` of every newly minted spec) as a family
+ * key, and nothing here can tell them apart without a lookup. So the default
+ * message states only what was actually established: the token could not be
+ * resolved to one spec from this machine, and it may be either. A caller that
+ * HAS verified the family reading (e.g. `classifyBareSpecId` found the token
+ * among the vault's occupied family keys) passes `confirmedFamily: true` to get
+ * the stronger, now-earned wording. The actionable hint is identical either way.
+ *
+ * @param {string|null|undefined} input
+ * @param {{ confirmedFamily?: boolean, detail?: string|null }} [opts]
  */
-export function requireResolvableSpecId(input) {
+export function requireResolvableSpecId(input, opts = {}) {
   if (isBareFamilyToken(input)) {
     const base = normalizeIdInput(input);
+    const hint =
+      `Pass a full basename that includes the type label ` +
+      `(e.g. ${base}-TASK-<slug> or HS-TASK-${base.replace(/^HS-/, '')}-<slug>; ` +
+      `the era-3 form is ${base}-<FAMILY>-<TYPE>-<slug>).`;
+    const claim = opts.confirmedFamily
+      ? `"${base}" is a bare family key, which names a whole shared-suffix family ` +
+        `rather than one spec.`
+      : `"${base}" is a bare token that could not be resolved to exactly one spec ` +
+        `from this machine — it may be the file key of a spec with no local copy, ` +
+        `or a family key naming a whole shared-suffix family.`;
     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>).`,
+      message: opts.detail ? `${claim} ${opts.detail} ${hint}` : `${claim} ${hint}`,
     };
   }
   return null;