heyspex 0.1.0 → 0.2.1

package/spexharness/src/token-inventory.mjs

@@ -0,0 +1,207 @@
+// spexharness/src/token-inventory.mjs
+//
+// The harness's session-start token inventory: measure every piece a session injects at
+// open (seat context, WIP block, memories, preflight procedures…), order them by value,
+// cut from the BOTTOM of that order when the budget is hit, and produce the one-line
+// inventory the front prints on session open — "what was injected and how much is left".
+//
+// Budget is a PARAMETER, never a constant: a seat opened on a 64k local model and the same
+// seat opened on a long-window hosted model run the same bootstrap and differ only in the
+// number resolved here. The seat row is the source of that number (`tokenBudget`), and 64k
+// is the default when the row doesn't carry one — the smallest window the fleet targets, so
+// a seat that never states a budget is still planned to fit the local model.
+//
+// Sizing is NOT reimplemented here: `estimateTokens` (chars/4) comes from
+// dev-factory/lib/context-budget.mjs, which is already THE prompt-token estimate for the
+// factory (see that file's header for why a second copy of the arithmetic is a defect, not
+// a convenience). Because chars/4 is an approximation, callers that must also reserve room
+// for a model's OUTPUT should resolve their budget with that module's `promptBudgetTokens`
+// and pass the result in as `budget` — this module deliberately does not re-derive it.
+//
+// Pure: no I/O, no console. `printTokenInventory` takes the log function, so a front (or a
+// test) decides where the line goes. Nothing here reads or writes the bootstrap — pieces
+// arrive as an argument, so the caller assembling them and this measurement stay separable.
+
+import { estimateTokens } from '../../dev-factory/lib/context-budget.mjs';
+
+export { estimateTokens };
+
+/** Default session-start token budget: 64k — the smallest window the local fleet targets. */
+export const DEFAULT_TOKEN_BUDGET = 65536;
+
+/**
+ * Seat-row keys carrying a token budget, in precedence order. `tokenBudget` is the
+ * canonical one; the snake_case spelling and the model-window names are accepted because
+ * seat rows are hand-edited JSON (dev-factory/seats.json) and a near-miss key silently
+ * falling back to 64k is worse than reading it.
+ */
+const SEAT_BUDGET_KEYS = ['tokenBudget', 'token_budget', 'contextTokens', 'numCtx', 'num_ctx'];
+
+/** A usable budget is a finite, positive number; anything else (null, "", NaN, 0, -1) is not. */
+function usableBudget(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+/**
+ * Resolve the token budget for a seat: the seat row's own budget, else {@link DEFAULT_TOKEN_BUDGET}.
+ * A missing seat, a seat with no budget key, or an unusable value (0, negative, non-numeric)
+ * all fall back to the default rather than throwing — a seat must never fail to open because
+ * its row is missing an optional field.
+ *
+ * @param {object|null} [seat] a seat row (dev-factory/seats.json shape), or null.
+ * @returns {number} a positive integer token budget.
+ */
+export function seatTokenBudget(seat = null) {
+  if (!seat || typeof seat !== 'object') return DEFAULT_TOKEN_BUDGET;
+  for (const key of SEAT_BUDGET_KEYS) {
+    const budget = usableBudget(seat[key]);
+    if (budget !== null) return budget;
+  }
+  return DEFAULT_TOKEN_BUDGET;
+}
+
+/**
+ * Measure one piece. `tokens` (a size the caller already knows — e.g. a tokenizer's count)
+ * wins over `text`; otherwise the text is sized with the repo-wide chars/4 estimate.
+ *
+ * @param {{ name?: string, text?: string, tokens?: number, priority?: number }} piece
+ * @param {number} [index] used to name an unnamed piece so the inventory line never has a blank slot.
+ * @returns {{ name: string, tokens: number, chars: number, priority: number, estimated: boolean }}
+ */
+export function measurePiece(piece, index = 0) {
+  const { name, text, tokens, priority } = piece ?? {};
+  // An explicit `tokens: 0` is a real measurement (an empty piece), while null/undefined
+  // means "not measured yet" — so absence, not falsiness, is what falls back to the text.
+  const explicit = tokens == null ? null : (usableBudget(tokens) ?? (Number(tokens) === 0 ? 0 : null));
+  const body = text == null ? '' : String(text);
+  return {
+    name: name ? String(name) : `piece-${index + 1}`,
+    tokens: explicit === null ? estimateTokens(body) : explicit,
+    chars: body.length,
+    priority: Number.isFinite(Number(priority)) ? Number(priority) : 0,
+    estimated: explicit === null,
+  };
+}
+
+/**
+ * Measure every piece and order it by value: descending `priority`, ties broken by the
+ * order the caller supplied (a stable sort), so a caller that already hands pieces over
+ * most-valuable-first gets exactly its own order back without stating a priority at all.
+ *
+ * @param {Array<object>} pieces
+ * @returns {Array<ReturnType<typeof measurePiece>>}
+ */
+export function measurePieces(pieces = []) {
+  const list = Array.isArray(pieces) ? pieces : [];
+  return list
+    .map((piece, index) => ({ measured: measurePiece(piece, index), index }))
+    .sort((a, b) => b.measured.priority - a.measured.priority || a.index - b.index)
+    .map(({ measured }) => measured);
+}
+
+/**
+ * Build the session-start token inventory: measure each piece, keep them down the value
+ * order while they fit the budget, and cut from the BOTTOM once one doesn't. The cut is a
+ * true tail cut — the first piece that overflows and everything below it are dropped, so a
+ * cheap low-value piece never leapfrogs an expensive higher-value one it was ranked under
+ * (that would silently reorder the seat's context by size instead of by value).
+ *
+ * @param {{
+ *   pieces?: Array<{ name?: string, text?: string, tokens?: number, priority?: number }>,
+ *   seat?: object|null,
+ *   budget?: number|null,
+ * }} [opts]
+ *   `budget` — an explicit budget, which wins over the seat row (a front that must also
+ *   reserve output tokens resolves that itself and passes the result). `seat` — the seat
+ *   row to read the budget from when `budget` is absent.
+ * @returns {{
+ *   budget: number,
+ *   injected: Array<{ name: string, tokens: number, chars: number, priority: number, estimated: boolean }>,
+ *   dropped: Array<{ name: string, tokens: number, chars: number, priority: number, estimated: boolean }>,
+ *   measured: Array<object>,
+ *   injectedTokens: number,
+ *   droppedTokens: number,
+ *   totalTokens: number,
+ *   remainingTokens: number,
+ *   withinBudget: boolean,
+ *   line: string,
+ * }}
+ */
+export function buildTokenInventory({ pieces = [], seat = null, budget = null } = {}) {
+  const resolvedBudget = usableBudget(budget) ?? seatTokenBudget(seat);
+  const measured = measurePieces(pieces);
+
+  const injected = [];
+  const dropped = [];
+  let injectedTokens = 0;
+  let cutting = false;
+  for (const piece of measured) {
+    // Once the budget is hit, everything below stays cut — bottom-of-the-order, not
+    // best-fit packing.
+    if (cutting || injectedTokens + piece.tokens > resolvedBudget) {
+      cutting = true;
+      dropped.push(piece);
+      continue;
+    }
+    injected.push(piece);
+    injectedTokens += piece.tokens;
+  }
+
+  const droppedTokens = dropped.reduce((sum, piece) => sum + piece.tokens, 0);
+  const inventory = {
+    budget: resolvedBudget,
+    injected,
+    dropped,
+    measured,
+    injectedTokens,
+    droppedTokens,
+    totalTokens: injectedTokens + droppedTokens,
+    remainingTokens: resolvedBudget - injectedTokens,
+    withinBudget: dropped.length === 0,
+    line: '',
+  };
+  inventory.line = formatInventoryLine(inventory);
+  return inventory;
+}
+
+/**
+ * Render the one line a front prints on session open: what was injected, at what size, and
+ * how much of the budget is left — plus what was cut, when anything was. Always exactly one
+ * line (no newline characters), so it can sit in a status bar, a log line, or a chat header.
+ *
+ * @param {ReturnType<typeof buildTokenInventory>} inventory
+ * @returns {string}
+ */
+export function formatInventoryLine(inventory) {
+  const {
+    budget = DEFAULT_TOKEN_BUDGET,
+    injected = [],
+    dropped = [],
+    injectedTokens = 0,
+    remainingTokens = budget - injectedTokens,
+  } = inventory ?? {};
+
+  const used = budget > 0 ? Math.round((injectedTokens / budget) * 100) : 100;
+  const parts = [
+    `context ${injectedTokens}/${budget} tokens (${used}%)`,
+    `${remainingTokens} left`,
+    `in: ${injected.length ? injected.map((p) => `${p.name} ${p.tokens}`).join(', ') : '(none)'}`,
+  ];
+  if (dropped.length) parts.push(`cut: ${dropped.map((p) => `${p.name} ${p.tokens}`).join(', ')}`);
+  return parts.join(' · ').replace(/[\r\n]+/g, ' ');
+}
+
+/**
+ * Print the inventory line on session open. The log function is an argument so a front
+ * chooses the sink (stdout, a chat header, a log file) and a test can capture it.
+ *
+ * @param {ReturnType<typeof buildTokenInventory>} inventory
+ * @param {(line: string) => void} [log]
+ * @returns {string} the line that was printed.
+ */
+export function printTokenInventory(inventory, log = console.log) {
+  const line = inventory?.line ?? formatInventoryLine(inventory);
+  log(line);
+  return line;
+}

package/vendor/heyspex-mcp/account-switch.mjs

@@ -0,0 +1,96 @@
+// account-switch.mjs — the ONE function that moves "which account is current"
+// on this machine: the credentials store's `current_account_id` (and its token
+// mirror) AND `~/.heyspex/registry.json`'s `current_account_id` move together,
+// so the bearer and the active-vault pointer can never name different accounts
+// ([[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]], invariant 4).
+//
+// The task offered two shapes: a hidden `hs vault current-account` sub (edits
+// `spex-console/src/lib/cli/vault.ts`, held by a sibling task) or one function
+// that writes both files. This is the second. It lives beside credentials.mjs
+// rather than under scripts/lib/ because `hs login` / `hs logout` (cli-verbs.mjs)
+// ship in the npm package, whose `files` list already carries every
+// vendor/heyspex-mcp/*.mjs but would need a package.json entry for a new
+// scripts/lib/ file.
+//
+// The registry half edits ONLY `current_account_id` of a schema-v2 file and
+// keeps every other byte of the JSON value (accounts' pointers, rows) as is. A
+// missing file has no pointers to move; a v1 file is re-keyed only by the
+// explicit `hs vault migrate-registry`; an unreadable file is left for
+// `hs doctor`. Each of those is reported, never "fixed" here.
+//
+// Plain Node ESM, zero dependencies. Never logs token material.
+
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { assertNotRealHomeUnderTest, removeAccount, setCurrentAccount } from './credentials.mjs';
+
+/** `~/.heyspex/registry.json` for `homeDir`. */
+export function registryFilePath(homeDir = heyspexHome()) {
+  return join(homeDir, '.heyspex', 'registry.json');
+}
+
+/**
+ * Set registry.json's `current_account_id` (or clear it with `null`).
+ * @param {{ homeDir?: string, accountId: string | null }} input
+ * @returns {{ status: 'updated' | 'unchanged' | 'absent' | 'v1' | 'unreadable', path: string }}
+ */
+export function setRegistryCurrentAccount({ homeDir = heyspexHome(), accountId }) {
+  const path = registryFilePath(homeDir);
+  if (!existsSync(path)) return { status: 'absent', path };
+  let json;
+  try {
+    json = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return { status: 'unreadable', path };
+  }
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return { status: 'unreadable', path };
+  if (json.schema_version !== 2) return { status: 'v1', path };
+  const next = accountId ?? null;
+  if ((json.current_account_id ?? null) === next) return { status: 'unchanged', path };
+  json.current_account_id = next;
+  assertNotRealHomeUnderTest(path);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(json, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+  return { status: 'updated', path };
+}
+
+/**
+ * Make `accountId` the machine's current account in BOTH stores. The account
+ * must already hold a token (a switch never pairs). Throws when it does not;
+ * the registry is touched only after the credentials half succeeded.
+ * @param {{ homeDir?: string, accountId: string }} input
+ */
+export function switchCurrentAccount({ homeDir = heyspexHome(), accountId }) {
+  const credentialsPath = setCurrentAccount({ homeDir, accountId });
+  const registry = setRegistryCurrentAccount({ homeDir, accountId });
+  return { accountId, credentialsPath, registry };
+}
+
+/**
+ * Sign one account out (default: the current one). When the current account is
+ * removed, both stores' `current_account_id` are cleared; removing another
+ * account leaves the registry alone.
+ * @param {{ homeDir?: string, accountId?: string | null }} [input]
+ */
+export function signOutAccount({ homeDir = heyspexHome(), accountId = null } = {}) {
+  const result = removeAccount({ homeDir, accountId });
+  const registry =
+    result.removed && result.wasCurrent
+      ? setRegistryCurrentAccount({ homeDir, accountId: null })
+      : { status: 'unchanged', path: registryFilePath(homeDir) };
+  return { ...result, registry };
+}
+
+/**
+ * After a fresh pairing stored `accountId` as current in the credentials
+ * store, carry the registry's pointer along with it.
+ * @param {{ homeDir?: string, accountId: string }} input
+ */
+export function followCurrentAccountInRegistry({ homeDir = heyspexHome(), accountId }) {
+  return setRegistryCurrentAccount({ homeDir, accountId });
+}

package/vendor/heyspex-mcp/alignment-gate.mjs

@@ -29,11 +29,57 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
 import { wikilinkTarget } from './blocker-resolver.mjs';
+import { readViaSelector } from './read-path.mjs';
 import { spexConsoleSettingsCandidates } from './vault-settings.mjs';
 
 export const ALIGNMENT_FUSE_DAYS = 7;
 export const DEFAULT_FOCUS_PIN_EXPIRATION_DAYS = 7;
 
+/**
+ * Marker carried by every result this module returns when a read the DISK tier
+ * performs has no equivalent in the `neon` read tier.
+ *
+ * The rule it exists to enforce: **a cloud-mode gate never fails OPEN
+ * silently.** In the `neon` tier there may be no git checkout of the vault at
+ * all, so `git log` against the vault root is not "slow" or "empty" — it is
+ * meaningless. The honest verdict is "cannot verify in cloud mode", carried in
+ * the result itself, NOT a thrown ENOENT and NOT a quiet `skip: true`.
+ */
+export const CLOUD_MODE_UNSUPPORTED_READ = 'CLOUD_MODE_UNSUPPORTED_READ';
+
+/** Build one clearly-marked "this could not be sourced in cloud mode" record. */
+export function cloudModeUnsupportedRead({ what, why, routeLabel = null, consoleUrl = null }) {
+  return {
+    unsupported: CLOUD_MODE_UNSUPPORTED_READ,
+    what,
+    why,
+    route_label: routeLabel,
+    console_url: consoleUrl ?? null,
+  };
+}
+
+/** True for any value produced by {@link cloudModeUnsupportedRead}. */
+export function isCloudModeUnsupportedRead(value) {
+  return Boolean(value) && value.unsupported === CLOUD_MODE_UNSUPPORTED_READ;
+}
+
+/**
+ * Why the git-time reads below have no cloud twin, stated once.
+ *
+ * The console serves no git-history route (audited 2026-09-14 across
+ * `spex-console/src/app/api/`): `/api/activity` and `/api/specs/[id]/activity`
+ * serve the agent tool-call log, not vault history; `POST /api/snapshot`
+ * TRIGGERS a git export drain and reads nothing back; `/api/specs` carries only
+ * frontmatter `created:` / `updated:` — the hand-editable fields the commit
+ * timestamp was deliberately chosen to be immune to (see the section header
+ * above). Substituting them would silently swap a spoof-proof signal for a
+ * spoofable one inside a gate, which is worse than reporting the gap.
+ */
+const GIT_HISTORY_UNSOURCEABLE_WHY =
+  'the neon read tier may hold no git checkout of the vault, and the console exposes no git-history route — '
+  + '/api/specs carries only frontmatter `created:`/`updated:`, the hand-editable fields the commit timestamp is chosen to be immune to, '
+  + 'and /api/activity is the agent tool-call log, not vault history';
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Git-time helpers — SSOT for "when did this spec enter the vault?" The
 // commit timestamp (`%ct`, seconds-since-epoch in committer's local timezone)
@@ -149,6 +195,100 @@ export function computeAlignmentSignature({ childIds, epicUpdated, worldStateHas
   return djb2(`${sortedChildren}|${epicUpdated || ''}|${worldStateHash || ''}`);
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Tier-aware git-time reads ([[HS-T6GS-MCPC-EPIC]] — every vault read the MCP
+// server makes goes through `readViaSelector`).
+//
+// The tier is RESOLVED ONCE by the handler that owns the request and threaded
+// in as `deps.tier`; nothing in this module calls `resolveReadTier()` itself.
+// `tier` defaults to `'disk'` so every existing caller — and every existing
+// test — keeps today's behavior byte-for-byte: the disk arm of
+// `readViaSelector` is literally `diskRead()`, and `diskRead` here is the
+// untouched synchronous function above.
+//
+// The `neon` arm does NOT call the console: nothing there serves git history
+// (see GIT_HISTORY_UNSOURCEABLE_WHY). It returns a clearly-marked
+// CLOUD_MODE_UNSUPPORTED_READ record instead — kept inside `neonRead` so that
+// the day a `/api/vault/git-history`-shaped route exists, swapping this body
+// for a real fetch also gets the CONSOLE_UNREACHABLE_CLOUD_MODE failure
+// envelope for free.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Console URL to NAME in cloud-mode diagnostics; never resolved on the disk path. */
+function diagnosticConsoleUrl(tier, deps) {
+  return tier === 'disk' ? null : (deps?.consoleUrl ?? null);
+}
+
+/** Tier-aware {@link gitFirstCommitTime}. `neon` answers an unsupported-read record. */
+export async function gitFirstCommitTimeViaTier(vaultRoot, path, deps = {}) {
+  const { tier = 'disk' } = deps;
+  const consoleUrl = diagnosticConsoleUrl(tier, deps);
+  return readViaSelector({
+    tier,
+    diskRead: () => gitFirstCommitTime(vaultRoot, path),
+    neonRead: async () =>
+      cloudModeUnsupportedRead({
+        what: `the first-commit timestamp of \`${path}\` (\`git log --diff-filter=A --follow --format=%ct -- ${path}\`)`,
+        why: GIT_HISTORY_UNSOURCEABLE_WHY,
+        routeLabel: 'git log --diff-filter=A --follow',
+        consoleUrl,
+      }),
+    routeLabel: 'git log --diff-filter=A --follow',
+    consoleUrl,
+  });
+}
+
+/** Tier-aware {@link gitLastCommitTime}. `neon` answers an unsupported-read record. */
+export async function gitLastCommitTimeViaTier(vaultRoot, path, deps = {}) {
+  const { tier = 'disk' } = deps;
+  const consoleUrl = diagnosticConsoleUrl(tier, deps);
+  return readViaSelector({
+    tier,
+    diskRead: () => gitLastCommitTime(vaultRoot, path),
+    neonRead: async () =>
+      cloudModeUnsupportedRead({
+        what: `the last-commit timestamp of \`${path}\` (\`git log -1 --format=%ct -- ${path}\`)`,
+        why: GIT_HISTORY_UNSOURCEABLE_WHY,
+        routeLabel: 'git log -1 --format=%ct',
+        consoleUrl,
+      }),
+    routeLabel: 'git log -1 --format=%ct',
+    consoleUrl,
+  });
+}
+
+/**
+ * Tier-aware {@link computeWorldStateDelta}.
+ *
+ * The `neon` answer keeps the `{ addedPaths, hash }` SHAPE so a caller that
+ * only reads those two fields cannot crash — but it is additionally stamped
+ * `unsupported: CLOUD_MODE_UNSUPPORTED_READ` and carries the full
+ * `unsupported_read` record, so a caller that treats the empty delta as "no
+ * new specs" is the one making that (wrong) choice explicitly.
+ * {@link canSkipAlignmentViaTier} refuses to.
+ */
+export async function computeWorldStateDeltaViaTier(vaultRoot, sinceTs, deps = {}) {
+  const { tier = 'disk' } = deps;
+  const consoleUrl = diagnosticConsoleUrl(tier, deps);
+  return readViaSelector({
+    tier,
+    diskRead: () => computeWorldStateDelta(vaultRoot, sinceTs),
+    neonRead: async () => ({
+      addedPaths: [],
+      hash: djb2(''),
+      unsupported: CLOUD_MODE_UNSUPPORTED_READ,
+      unsupported_read: cloudModeUnsupportedRead({
+        what: 'the set of `specs/` files first committed since the last alignment review (`git log --since=… --diff-filter=A --name-only -- specs/`)',
+        why: GIT_HISTORY_UNSOURCEABLE_WHY,
+        routeLabel: 'git log --since --diff-filter=A -- specs/',
+        consoleUrl,
+      }),
+    }),
+    routeLabel: 'git log --since --diff-filter=A -- specs/',
+    consoleUrl,
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Settings-driven fuse — read spex-console/settings.json (or .heyspex/ mirror) so
 // disabling `focusPinExpirationEnabled` in the UI also disables the alignment
@@ -156,6 +296,25 @@ export function computeAlignmentSignature({ childIds, epicUpdated, worldStateHas
 // drop fuse_expired from the skip-reason ladder.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * LOCAL CACHE — stays on disk in BOTH read tiers, deliberately.
+ *
+ * Both call sites (`readAlignmentFuseSettings`, `readReadinessFloorSettings`)
+ * point this at `spexConsoleSettingsCandidates(vaultRoot)`, i.e.
+ * `spex-console/settings.json` and its read-only `.heyspex/` mirrors. That is
+ * gitignored machine-local CONFIG, not vault content: it never lives under
+ * `specs/`, it is not a document with an id, frontmatter or a wikilink target,
+ * and `PUT /api/settings` explicitly refuses to persist it outside local mode
+ * (HS-29MO). So there is nothing in Neon to read it from, and nothing about a
+ * cloud-reliant session that should change where a local knob is read.
+ *
+ * This is the same call that `read-path-wiring.test.mjs` AC5 makes for
+ * credentials, the scheduler cache and caller-supplied args files: "still read
+ * from disk in both reliances." Both call sites therefore keep this function
+ * untouched — no tier argument, no console route, no degrade marker; a missing
+ * file already means "use the shipped default", which is the correct answer on
+ * a machine with no console settings file, cloud-reliant or not.
+ */
 function readJsonSafe(path) {
   try {
     if (!existsSync(path)) return null;
@@ -165,6 +324,10 @@ function readJsonSafe(path) {
   }
 }
 
+/**
+ * Read tier: DISK in both tiers — machine-local console config, not vault
+ * content. See {@link readJsonSafe} for the full call-site conclusion.
+ */
 export function readAlignmentFuseSettings(vaultRoot) {
   const fallback = { enabled: true, days: DEFAULT_FOCUS_PIN_EXPIRATION_DAYS };
   for (const p of spexConsoleSettingsCandidates(vaultRoot)) {
@@ -261,6 +424,101 @@ export function canSkipAlignment(epic, vaultRoot, options = {}) {
   return { skip: true, reason: 'binary_skip_rule', signature: currentSignature };
 }
 
+/**
+ * Tier-aware {@link canSkipAlignment}.
+ *
+ * `disk` → `canSkipAlignment(epic, vaultRoot, options)`, byte-identical (the
+ * selector's disk arm is literally `diskRead()`). `tier` defaults to `'disk'`,
+ * so an existing caller that passes no deps is unchanged.
+ *
+ * `neon` → the gate FAILS CLOSED and SAYS SO. Two of the rule's four
+ * components are git-truth (`older_children` needs each child's first-commit
+ * time; `new_specs_since_breakdown` needs the added-files delta) and the third
+ * — `signature_drift` — mixes the world-state hash into its signature, so a
+ * synthesized empty delta would make it compare a signature against inputs it
+ * never actually read. Rather than pass on unverified inputs (fail open) or
+ * throw ENOENT from `git` against a directory that does not exist, the verdict
+ * is `{ skip: false, reason: 'cloud_mode_unverifiable' }` carrying
+ * {@link CLOUD_MODE_UNSUPPORTED_READ} and a per-read record naming exactly
+ * what could not be sourced and why.
+ *
+ * Two reasons survive cloud mode intact and are returned as themselves,
+ * because neither reads git or the vault: `no_checkpoint` (the epic's own
+ * frontmatter carries no `alignment_reviewed_at`) and `fuse_expired` (that
+ * timestamp against a local settings knob — see {@link readJsonSafe}). Both
+ * already say `skip: false`, so returning them changes nothing about failing
+ * closed; it just gives the more specific reason.
+ *
+ * A caller that HAS sourced the world-state delta by some other means may pass
+ * it as `options.worldStateDelta`; it is then trusted and not listed as
+ * unsupported, exactly as on disk.
+ */
+export async function canSkipAlignmentViaTier(epic, vaultRoot, options = {}, deps = {}) {
+  const { tier = 'disk' } = deps;
+  if (tier !== 'neon') {
+    return readViaSelector({
+      tier,
+      diskRead: () => canSkipAlignment(epic, vaultRoot, options),
+      routeLabel: 'canSkipAlignment',
+      consoleUrl: null,
+    });
+  }
+
+  const consoleUrl = deps.consoleUrl ?? null;
+  const fm = epic?.frontmatter || {};
+  const reviewedAt = fm.alignment_reviewed_at;
+  const reviewedMs = reviewedAt ? Date.parse(String(reviewedAt)) : NaN;
+  if (!Number.isFinite(reviewedMs)) {
+    // Frontmatter-only verdict — as true in cloud mode as on disk.
+    return { skip: false, reason: 'no_checkpoint' };
+  }
+
+  const unsupportedReads = [
+    cloudModeUnsupportedRead({
+      what: 'the first-commit timestamp of the epic and of each child, which the `older_children` check compares',
+      why: GIT_HISTORY_UNSOURCEABLE_WHY,
+      routeLabel: 'git log --diff-filter=A --follow',
+      consoleUrl,
+    }),
+  ];
+
+  let worldStateDelta = options.worldStateDelta;
+  if (!worldStateDelta) {
+    worldStateDelta = await computeWorldStateDeltaViaTier(vaultRoot, reviewedMs, { tier, consoleUrl });
+    if (worldStateDelta.unsupported_read) unsupportedReads.push(worldStateDelta.unsupported_read);
+  }
+
+  // Re-run the shared rule with the git-backed inputs NEUTRALIZED rather than
+  // re-implementing the ladder: `epicPath`/`childResolver` are nulled so the
+  // older_children walk is skipped (it is already a no-op without them), and
+  // the delta is whatever we could honestly source.
+  const inner = canSkipAlignment(epic, vaultRoot, {
+    ...options,
+    worldStateDelta,
+    epicPath: null,
+    childResolver: null,
+  });
+
+  // Reasons that stand on their own in cloud mode: they read no git history.
+  if (inner.reason === 'fuse_expired' || inner.reason === 'new_specs_since_breakdown') {
+    return { ...inner, cloud_mode_unsupported_reads: unsupportedReads };
+  }
+
+  return {
+    skip: false,
+    reason: 'cloud_mode_unverifiable',
+    unsupported: CLOUD_MODE_UNSUPPORTED_READ,
+    cloud_mode_unsupported_reads: unsupportedReads,
+    message:
+      `${CLOUD_MODE_UNSUPPORTED_READ}: the alignment skip rule cannot be verified in the neon read tier — `
+      + `${unsupportedReads.map((u) => u.what).join('; ')}. `
+      + 'The gate stays CLOSED (skip: false) rather than passing on inputs it never read.',
+    // What the rule WOULD have said from the components that were readable.
+    // Reported for transparency only — never as the verdict.
+    unverified_inner_verdict: inner,
+  };
+}
+
 /** Epic children live in `children:`; milestone children live in `epics:`. */
 export function childRefsField(grain) {
   return grain === 'milestone' ? 'epics' : 'children';
@@ -306,6 +564,39 @@ export function extractSection(body, headingRe) {
   return out.join('\n').trim();
 }
 
+/**
+ * Does the body carry a level-2 heading whose title matches `headingRe`? Same
+ * scan as `extractSection`, but it answers "is the heading THERE" rather than
+ * "what is under it" — an empty section and an absent one look identical to
+ * `extractSection` (both `''`), and the `## Done when` alias below has to tell
+ * them apart. Exported for the alias's own tests.
+ */
+export function hasHeading(body, headingRe) {
+  if (typeof body !== 'string') return false;
+  for (const line of body.split(/\r?\n/)) {
+    const h2 = line.match(/^##\s+(.+?)\s*$/);
+    if (h2 && !line.startsWith('###') && headingRe.test(h2[1])) return true;
+  }
+  return false;
+}
+
+/** The canonical acceptance section title this parser extracts from. */
+const ACCEPTANCE_HEADING_TITLE = /^acceptance(?:\s+criteria)?$/i;
+
+/**
+ * Deliberately BROADER than `ACCEPTANCE_HEADING_TITLE`, and used only to decide
+ * whether the `## Done when` alias may fire. The vault carries many suffixed
+ * Acceptance headings this parser does not extract from (`## Acceptance
+ * verification`, `## Acceptance gate — epic close`, `## Acceptance (epic-level)`,
+ * …). A doc that has ANY of them has an acceptance section, so the legacy alias
+ * must not fire there — otherwise the alias would newly disagree with the
+ * console parser, which matches `## Acceptance…` with arbitrary suffixes.
+ */
+const ACCEPTANCE_HEADING_TITLE_ANY = /^acceptance/i;
+
+/** Legacy back-compat alias for the acceptance section — see HS-VDJH-LBUA below. */
+const DONE_WHEN_HEADING_TITLE_ALIAS = /^done\s+when\b/i;
+
 /** Bullet lines (`-`/`*`, checkbox, or numbered `1.` / `1)`) → trimmed text array. */
 export function extractBullets(text) {
   if (typeof text !== 'string') return [];
@@ -332,7 +623,27 @@ export function parseAcceptanceSubsections(body) {
   // heading variant (~48 vault specs use the latter — and the console parser
   // already accepts it, so anchoring exactly here broke cross-surface parity and
   // wrongly routed those specs to the Tier-3 clarification floor). [[HS-TASK-I2Y8]]
-  const section = extractSection(body, /^acceptance(?:\s+criteria)?$/i);
+  let section = extractSection(body, ACCEPTANCE_HEADING_TITLE);
+  // HS-VDJH-LBUA — legacy `## Done when` BACK-COMPAT ALIAS (read side only; no
+  // vault file is ever rewritten). `## Acceptance criteria` stays canonical, but
+  // 138 vault files (measured 2026-09-01: 111 captures, 16 diagnoses, 8 tasks,
+  // 2 milestones, 1 research) carry the same section under `## Done when` and no
+  // `## Acceptance…` heading at all — the derived execution brief read zero
+  // criteria out of every one of them, so a dispatched diagnose could not be
+  // graded and the critic returned `uncertain` by construction.
+  //
+  // Tried ONLY when the document has no `## Acceptance…` heading, so the two
+  // vault files carrying BOTH headings still resolve to the canonical one
+  // regardless of document order — and a present-but-empty Acceptance section
+  // still reads as zero criteria rather than falling through. `\b` after `when`
+  // keeps the match tight: `## Done whenever …` is not a criteria section.
+  //
+  // Mirrors dev-factory/lib/acceptance-criteria.mjs and the console parser
+  // (spex-console/src/lib/acceptance-criteria.ts); the three are pinned together
+  // by spex-console/src/lib/__tests__/acceptance-criteria-parity.test.ts.
+  if (!section && !hasHeading(body, ACCEPTANCE_HEADING_TITLE_ANY)) {
+    section = extractSection(body, DONE_WHEN_HEADING_TITLE_ALIAS);
+  }
   if (!section) return { sections: [], hasSubsections: false };
 
   const lines = section.split(/\r?\n/);
@@ -1094,6 +1405,9 @@ export const DEFAULT_READINESS_FLOOR = { minAcceptanceBullets: 1, minGoalChars:
  * .heyspex mirror under a `briefReadinessFloor: { minAcceptanceBullets,
  * minGoalChars }` key. Missing / malformed values fall back per-field to
  * DEFAULT_READINESS_FLOOR. Mirrors readAlignmentFuseSettings' lookup order.
+ *
+ * Read tier: DISK in both tiers — this is machine-local config, not vault
+ * content. See {@link readJsonSafe} for the full call-site conclusion.
  */
 export function readReadinessFloorSettings(vaultRoot) {
   for (const p of spexConsoleSettingsCandidates(vaultRoot)) {