heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/seat-block-ledger.mjs

@@ -0,0 +1,113 @@
+// vendor/heyspex-mcp/seat-block-ledger.mjs
+//
+// Per-session "has the DEV-FACTORY SEAT banner already gone out this session"
+// decision for the two vendor surfaces that used to each keep their OWN flag:
+//   - tool-dispatch.mjs handleInitialize()      → surface 'mcp_instructions'
+//   - cli.mjs maybePrependSeatBanner()          → surface 'preflight' (when the
+//     first tool called is heyspex_preflight) or 'tool_result' otherwise
+//
+// Before this module, `initialize` always appended the banner to `instructions`
+// AND, independently, the first tools/call response ALSO got the banner
+// prepended (a separate `seatBannerSeenSessions` Set tracked only THAT surface) —
+// so a caller could see "DEV-FACTORY SEAT: ..." twice in one session. That is
+// exactly the bug spexharness/src/bootstrap-injection.mjs's engine contract
+// exists to close for every surface (its own header calls out wiring
+// vendor/heyspex-mcp as the deferred follow-up — HS-8U8X).
+//
+// spexharness/ is dev-only tooling: it is deliberately NOT part of the published
+// `heyspex` npm package (see dev-factory-bridge.mjs for the identical open-core
+// concern with dev-factory/spexcrawl/). scripts/verify-mcp-package.mjs's
+// `closure` check fails the build if the server's STATIC import graph reaches a
+// file the package doesn't ship, so the engine contract is reached the same way
+// spexcrawl is: a memoized `await import()`, never a static import. A
+// published install (no spexharness/ tree on disk) gets the fallback ledger
+// below instead — same "at most one surface, across the whole session" contract,
+// just without a shared spexharness bootstrap ledger to defer to.
+
+/** @type {Promise<typeof import('../../spexharness/src/bootstrap-injection.mjs')>|undefined} */
+let enginePromise;
+
+function loadEngine() {
+  if (!enginePromise) {
+    enginePromise = import('../../spexharness/src/bootstrap-injection.mjs').catch(() => null);
+  }
+  return enginePromise;
+}
+
+/**
+ * Local, dependency-free ledger with the exact `shouldIncludeSeatBlock` /
+ * `markSeatBlockSent` shape bootstrap-injection.mjs's `withSeatBlockLedger`
+ * exposes — used when the engine module is not reachable (a published install,
+ * or any import failure). "No bootstrap yet" degrades to "emit once, guarded",
+ * never to "emit unguarded".
+ */
+function createFallbackLedger() {
+  const sent = new Set();
+  return {
+    shouldIncludeSeatBlock(surface) {
+      if (sent.has(surface)) return false;
+      return sent.size === 0;
+    },
+    markSeatBlockSent(surface) {
+      sent.add(surface);
+    },
+  };
+}
+
+function fallbackSeatBlockForSurface(ledger, surface, seatLine) {
+  if (!ledger.shouldIncludeSeatBlock(surface)) return null;
+  ledger.markSeatBlockSent(surface);
+  return seatLine ?? null;
+}
+
+/** One ledger controller per session id — two sessions sharing this process (e.g. two
+ *  fleet workers spawned back-to-back) never see each other's sends. */
+const controllersBySession = new Map();
+
+async function getSeatBlockController(sessionId) {
+  const key = sessionId || 'local';
+  const existing = controllersBySession.get(key);
+  if (existing) return existing;
+
+  const engine = await loadEngine();
+  const ledger = engine?.withSeatBlockLedger ? engine.withSeatBlockLedger({}) : createFallbackLedger();
+  const forSurface = engine?.seatBlockForSurface
+    ? (surface, seatLine) => engine.seatBlockForSurface(ledger, surface, seatLine)
+    : (surface, seatLine) => fallbackSeatBlockForSurface(ledger, surface, seatLine);
+
+  const controller = { forSurface };
+  controllersBySession.set(key, controller);
+  return controller;
+}
+
+/**
+ * Decide whether `surface` should emit the seat banner for `sessionId` this
+ * session — sourced from the engine contract's per-session ledger when
+ * spexharness/ is reachable (memoized per session id), else a local fallback
+ * with identical "exactly once, across every surface" semantics. Returns the
+ * banner text when `surface` is cleared to send it, else `null`. Never throws;
+ * a falsy `seatLine` (not enabled / unknown caller) short-circuits to `null`
+ * WITHOUT touching the ledger, so an ineligible caller never "uses up" the
+ * session's one send.
+ *
+ * @param {string|null|undefined} sessionId
+ * @param {string} surface one of bootstrap-injection.mjs's SEAT_BLOCK_SURFACES
+ *   ('mcp_instructions', 'preflight', 'tool_result', 'bootstrap').
+ * @param {string|null|undefined} seatLine
+ * @returns {Promise<string|null>}
+ */
+export async function seatBlockForSessionSurface(sessionId, surface, seatLine) {
+  if (!seatLine) return null;
+  try {
+    const controller = await getSeatBlockController(sessionId);
+    return controller.forSurface(surface, seatLine);
+  } catch {
+    return null;
+  }
+}
+
+/** Test-only: forget every per-session ledger and the memoized engine probe. */
+export function resetSeatBlockLedgerForTests() {
+  controllersBySession.clear();
+  enginePromise = undefined;
+}

package/vendor/heyspex-mcp/seat-identity.mjs

@@ -19,7 +19,7 @@
 
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { PACKAGE_ROOT } from "./package-root.mjs";
 
 /**
  * Read and parse <vaultRoot>/dev-factory/seats.json.
@@ -169,11 +169,7 @@ function selfTest() {
   };
 
   // Repo root is two dirs up from this file (vendor/heyspex-mcp/ → repo root).
-  const repoRoot = path.resolve(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "..",
-    "..",
-  );
+  const repoRoot = PACKAGE_ROOT;
 
   // 1. Real registry smoke-read.
   const real = readSeatsRegistry(repoRoot);

package/vendor/heyspex-mcp/session-owner.mjs

@@ -0,0 +1,108 @@
+// session-owner.mjs — the ONE place the MCP server learns which account owns
+// the documents it files ([[HS-WE87-WW9R-TASK-thread-the-gated-caller-through-every]],
+// epic [[HS-P1AW-WW9R-EPIC-identity-threading-and-the-end-of-the]] — invariant 1).
+//
+// Until this module the three frontmatter writers (`capture-focus.mjs`,
+// `research-focus.mjs`, `defer-spec.mjs`) each stamped the HeySpex owner's
+// handle as a literal — on a customer machine that put the platform owner's
+// name on the customer's own documents. They now ask here, and when nothing
+// resolves the `owner:` key is OMITTED rather than guessed.
+//
+// Resolution order (no network — this runs inside synchronous writers and
+// under `node --test`):
+//   1. `HS_ACCOUNT_ID` env — the same override the CLI's account reader honours.
+//   2. the credentials store's current account (`credentials.mjs`
+//      `readCurrentAccountId`, [[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]]):
+//      `current_account_id` of `~/.heyspex/credentials.yaml`, set by `hs login` /
+//      `hs mcp pair` from the account GET /api/mcp/session confirmed for the
+//      stored bearer and moved by `hs login --switch-account` / `hs logout`.
+//      An existing single-account (v1) file has no such key: its account is
+//      the `~/.heyspex/config.yaml` `account_id:` the earlier `hs login` wrote
+//      ([[HS-630L-WW9R-TASK-one-strict-cli-account-reader-hs-login]]) — read
+//      for that case only, never written any more (one account-id store).
+//   3. null — the writer omits `owner:`.
+//
+// This is ALSO the CLI's account reader: `resolveConfiguredAccountId` in
+// spex-console/src/lib/cli/vault-workspace-shared.ts and `readConfiguredAccountId`
+// in spex-console/src/lib/cli/install-identity.ts both delegate to
+// `resolveSessionOwnerUncached`, so one precedence serves `hs vault`, `hs connect`,
+// `hs install` and every MCP frontmatter writer. Its bearer twin is
+// `./credentials.mjs` (HS-HL0D).
+//
+// Cached per process once resolved from the real environment (the MCP server
+// is spawned once per session; pairing changes restart it). Callers inject
+// `env` / `homeDir` / `readFile` for tests, which bypasses the cache.
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { readCurrentAccountId } from './credentials.mjs';
+
+const ACCOUNT_ID_LINE_RE = /^account_id:\s*["']?([^"'\r\n#]+)/m;
+
+/**
+ * Read the paired account id from `~/.heyspex/config.yaml`, or null.
+ * @param {{ homeDir?: string, readFile?: (p: string) => string }} [opts]
+ */
+export function readConfigAccountId({ homeDir = homedir(), readFile } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  try {
+    const raw = read(join(homeDir, '.heyspex', 'config.yaml'));
+    const match = String(raw ?? '').match(ACCOUNT_ID_LINE_RE);
+    const value = match?.[1]?.trim() ?? '';
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the session owner without caching — the pure core.
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
+ * @returns {string | null}
+ */
+export function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir(), readFile } = {}) {
+  const fromEnv = typeof env?.HS_ACCOUNT_ID === 'string' ? env.HS_ACCOUNT_ID.trim() : '';
+  if (fromEnv) return fromEnv;
+  return readCurrentAccountId({ homeDir, readFile });
+}
+
+let cached = null;
+let cacheFilled = false;
+
+/**
+ * The account every MCP-authored document is stamped with, or null when the
+ * machine has no resolvable account (the writers then OMIT `owner:`).
+ *
+ * The real-environment answer is memoised per process; any injected option
+ * bypasses the cache so tests stay hermetic.
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
+ * @returns {string | null}
+ */
+export function resolveSessionOwner(opts) {
+  if (opts && Object.keys(opts).length > 0) return resolveSessionOwnerUncached(opts);
+  if (!cacheFilled) {
+    cached = resolveSessionOwnerUncached();
+    cacheFilled = true;
+  }
+  return cached;
+}
+
+/** Test seam: forget the per-process answer. */
+export function __resetSessionOwnerCacheForTests() {
+  cached = null;
+  cacheFilled = false;
+}
+
+/**
+ * The `owner:` frontmatter entry for an object-shaped frontmatter — `{ owner }`
+ * when an account resolved, `{}` when none did (the key is omitted, never
+ * guessed). `explicit` (an `args.owner` the caller supplied) wins.
+ * @param {{ explicit?: unknown, resolve?: () => string | null }} [opts]
+ */
+export function ownerFrontmatterEntry({ explicit, resolve = resolveSessionOwner } = {}) {
+  const chosen =
+    typeof explicit === 'string' && explicit.trim() ? explicit.trim() : (resolve() ?? null);
+  return chosen ? { owner: chosen } : {};
+}

package/vendor/heyspex-mcp/session-tools.mjs

@@ -0,0 +1,152 @@
+// Session hand-off and agent identity tools: heyspex_handoff_record, handoff_load,
+// import_agent. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { consoleFetch } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+
+/**
+ * Import a community agent role via console `POST /api/agents/import` — the MCP
+ * face of agent import ([[HS-TASK-Z666]]). Same core as `hs agent import`; no
+ * field-mapping logic duplicated in JS.
+ */
+export async function handleImportAgent(args = {}) {
+  if (!args.collection || typeof args.collection !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'collection is required' }) }],
+    };
+  }
+  if (!args.role || typeof args.role !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'role is required' }) }],
+    };
+  }
+  const body = {
+    collection: args.collection,
+    role: args.role,
+    ...(args.dry_run === true || args.dry_run === 'true' ? { dry_run: true } : {}),
+  };
+  const result = await consoleFetch('/api/agents/import', { method: 'POST', body });
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'IMPORT_AGENT_FAILED'),
+      message: consoleErrorMessage(result, `POST /api/agents/import returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: body,
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  const responseBody = result.body ?? {};
+  const payload = {
+    spec_id: responseBody.spec_id ?? null,
+    path: responseBody.path ?? null,
+    warnings: Array.isArray(responseBody.warnings) ? responseBody.warnings : [],
+    ...(responseBody.dry_run ? { dry_run: true } : {}),
+    console_response: responseBody,
+  };
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+/**
+ * Upsert the current resume context for this agent/lane into the Neon control
+ * plane — [[HS-EPIC-NCPS]] handoff_context / [[HS-EPIC-CLMW]] `hs handoff record`.
+ *
+ * Self-purging overwrite-in-place (PUT /api/control/handoff-context). The lane
+ * defaults to this agent's session id so each session is its own lane. Coordi-
+ * nation only — the endpoint rejects durable-knowledge fields.
+ */
+export async function handleHandoffRecord(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const laneKey =
+    typeof args.lane === 'string' && args.lane.trim()
+      ? args.lane.trim()
+      : identity.sessionId;
+  const body = {
+    lane_key: laneKey,
+    agent: identity.agent,
+    ...(typeof args.spec_id === 'string' ? { spec_id: args.spec_id } : {}),
+    ...(typeof args.phase === 'string' ? { phase: args.phase } : {}),
+    ...(typeof args.estimated_time === 'string' ? { estimated_time: args.estimated_time } : {}),
+    ...(Array.isArray(args.blockers) ? { blockers: args.blockers.map(String) } : {}),
+    ...(Array.isArray(args.links) ? { links: args.links.map(String) } : {}),
+  };
+  const result = await consoleFetch('/api/control/handoff-context', {
+    method: 'PUT',
+    body,
+  });
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'HANDOFF_RECORD_FAILED'),
+      message: consoleErrorMessage(result, `Handoff-context endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { lane: laneKey },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({ lane: laneKey, console_response: result.body }, null, 2),
+    }],
+  };
+}
+
+/**
+ * Read the current resume context for a lane from the Neon control plane —
+ * [[HS-EPIC-NCPS]] handoff_context / [[HS-EPIC-CLMW]] `hs handoff load`.
+ *
+ * Defaults to this agent's own lane (its session); `all: true` lists every
+ * active lane (parallel-agent off-on-deck). Self-purging — no per-session
+ * history; expired rows read as absent.
+ */
+export async function handleHandoffLoad(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const wantAll = args.all === true;
+  const laneKey =
+    typeof args.lane === 'string' && args.lane.trim()
+      ? args.lane.trim()
+      : identity.sessionId;
+  const path = wantAll
+    ? '/api/control/handoff-context'
+    : `/api/control/handoff-context?lane=${encodeURIComponent(laneKey)}`;
+  const result = await consoleFetch(path);
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'HANDOFF_LOAD_FAILED'),
+      message: consoleErrorMessage(result, `Handoff-context endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: wantAll ? { all: true } : { lane: laneKey },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(
+        wantAll ? result.body : { lane: laneKey, ...result.body },
+        null,
+        2,
+      ),
+    }],
+  };
+}

package/vendor/heyspex-mcp/settings-registry.mjs

@@ -0,0 +1,232 @@
+/**
+ * HeySpex close-out settings registry — the single declaration of every close-out
+ * setting: its dotted key, type, shipped default, description, CLI flag, admin-only
+ * marker, enforced marker, and which vault templates ship it.
+ *
+ * WHY: nothing today says which close-out settings exist, so a shipped default has
+ * nowhere to live and a mistyped key fails silently ([[HS-FCF5-15XI-RES-user-editable-close-out-settings-with]]).
+ * This registry is the one source every face is meant to read — `hs settings`, the
+ * MCP settings tools, and (later) the console — instead of each guessing its own
+ * fallback.
+ *
+ * DECLARATION ONLY (HS-6TDH): this module does not read or write
+ * `.heyspex/config.yaml`, does not import `config-settings.mjs`, and does not change
+ * any existing settings behavior. A later task in the same epic
+ * ([[HS-KW38-15XI-EPIC-settings-registry-core]]) teaches `config-settings.mjs` to
+ * resolve reads/writes through this registry (defaults, unknown-key refusal,
+ * enforced-entry refusal, type/enum validation).
+ *
+ * DEPENDENCY-FREE: Node stdlib only, no filesystem access at all — same rationale as
+ * the sibling module's "DEPENDENCY-FREE" note.
+ *
+ * Traceability: [[HS-KW38-15XI-EPIC-settings-registry-core]] ·
+ * [[HS-FCF5-15XI-RES-user-editable-close-out-settings-with]] ·
+ * [[HS-6TDH-15XI-TASK-declare-every-close-out-setting-in-one]]
+ */
+
+/**
+ * @typedef {'boolean' | 'string' | 'enum'} SettingType
+ *
+ * @typedef {Object} SettingEntry
+ * @property {string} key - Dotted key, e.g. "close_out.update_docs".
+ * @property {SettingType} type - The value's declared type.
+ * @property {*} default - The shipped default value (absent-key resolution target).
+ * @property {string} description - One or two sentences a person can read as help text.
+ * @property {string|null} cliFlag - The `hs close` / `hs settings` flag name (e.g.
+ *   "--update-docs"), or `null` for an enforced entry with no user-facing flag.
+ * @property {boolean} adminOnly - True for a HeySpex-admin-only entry; a non-admin
+ *   vault must treat the key as unknown.
+ * @property {boolean} enforced - True for a hard rule that cannot be changed by
+ *   anyone through any face, including a HeySpex admin.
+ * @property {string[]} templates - Which vault templates ship this entry:
+ *   "heyspex" (the HeySpex platform vault) and/or "customer" (the shipped customer
+ *   template).
+ * @property {string[]} [values] - Allowed values; present only when `type` is "enum".
+ */
+
+/**
+ * The ordered list of every declared close-out setting. Order is the order the
+ * close-out runner is meant to evaluate them in (a later task); it is also the
+ * order `hs settings list` should render them in.
+ *
+ * @type {ReadonlyArray<Readonly<SettingEntry>>}
+ */
+export const SETTINGS_REGISTRY = Object.freeze(
+  [
+    {
+      key: 'close_out.update_docs',
+      type: 'boolean',
+      default: true,
+      description:
+        'Updates docs/user and docs/admin per the docs-action rule (create/edit/append) at every close-out.',
+      cliFlag: '--update-docs',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.review_grain',
+      type: 'enum',
+      values: ['milestone', 'task'],
+      default: 'milestone',
+      description:
+        'Chooses the close-out review unit: "milestone" flips a completed task straight to closed with no per-task review companion, "task" is the canonical per-task close-out protocol with one HS-REV per task.',
+      cliFlag: '--review-grain',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.review_backlog_never_blocks',
+      type: 'boolean',
+      default: true,
+      description:
+        'A review backlog sitting at in_review/review_pending never blocks a new claim and never needs owner permission.',
+      cliFlag: '--review-backlog-never-blocks',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.flip_completed_to_closed',
+      type: 'boolean',
+      default: true,
+      description: 'Flips a completed task straight to closed at close-out.',
+      cliFlag: '--flip-completed-to-closed',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.append_review_seed',
+      type: 'boolean',
+      default: true,
+      description: 'Appends a one-line review seed to the task change-log at close-out.',
+      cliFlag: '--append-review-seed',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.rolling_review_doc',
+      type: 'boolean',
+      default: true,
+      description: 'Accumulates one rolling review doc per milestone at close-out.',
+      cliFlag: '--rolling-review-doc',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.run_command_drift_doctor',
+      type: 'boolean',
+      default: true,
+      description:
+        'Runs the HeySpex command-drift doctor at close-out. HeySpex-admin-only; a customer vault never sees this key.',
+      cliFlag: '--run-command-drift-doctor',
+      adminOnly: true,
+      enforced: false,
+      templates: ['heyspex'],
+    },
+    // Hard rules: enforced entries cannot be changed by anyone through any face,
+    // including a HeySpex admin, so they carry no user-facing CLI flag.
+    {
+      key: 'close_out.alignment',
+      type: 'boolean',
+      default: true,
+      description: 'Hard rule: alignment stays on. No mode may relax it.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.capture',
+      type: 'boolean',
+      default: true,
+      description: 'Hard rule: capture stays on. No mode may relax it.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.research',
+      type: 'boolean',
+      default: true,
+      description: 'Hard rule: research stays on. No mode may relax it.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+    // `close_out.git_commit` moved OUT of the hard-rule set above (owner ruling
+    // 2026-09-11, [[HS-PROTO-spexsource-agent-protocol]]): whether an agent
+    // ever commits at close-out is now a real, permission-gated toggle instead
+    // of an unconditional refusal. Default stays `false` for every vault —
+    // heyspex and customer alike — so nobody's out-of-box behavior changes; an
+    // owner opts in per vault via the normal settings-write-permission flow
+    // (`heyspex_settings_set` / `hs settings set --confirmed-by-user`). When
+    // `true`, the agent does not commit unconditionally — it still obeys the
+    // existing mode logic: the close-out commit lands at the boundary of the
+    // *active review grain* (`close_out.review_grain` — task / epic /
+    // milestone), routes only through the sanctioned `hs source preflight` →
+    // `hs source commit` path, and stays bound by every entry in
+    // spexsource-agent-protocol's always-forbidden list (no `--no-verify`, no
+    // force, no push — pushing is the separate `close_out.git_push` key,
+    // still enforced below). An explicit owner instruction for the session
+    // (e.g. "don't commit this one") overrides the setting for that session;
+    // the setting only changes the *default* when the owner said nothing.
+    {
+      key: 'close_out.git_commit',
+      type: 'boolean',
+      default: false,
+      description:
+        'Whether the agent commits automatically at close-out. Default false (a dirty tree is the expected hand-off; the human reviewer commits on Pass). When true, the agent still obeys the active review grain (close_out.review_grain) for WHEN to commit and the spexsource-agent-protocol always-forbidden list for HOW — never a bypass of those rules, just an opt-in default.',
+      cliFlag: '--git-commit',
+      adminOnly: false,
+      enforced: false,
+      templates: ['heyspex', 'customer'],
+    },
+    {
+      key: 'close_out.git_push',
+      type: 'boolean',
+      default: false,
+      description: 'Hard rule: an agent never pushes at close-out.',
+      cliFlag: null,
+      adminOnly: false,
+      enforced: true,
+      templates: ['heyspex', 'customer'],
+    },
+  ].map((entry) => Object.freeze(entry)),
+);
+
+/** Fast key → entry lookup, built once from `SETTINGS_REGISTRY`. */
+const BY_KEY = new Map(SETTINGS_REGISTRY.map((entry) => [entry.key, entry]));
+
+/**
+ * Look up one registry entry by its dotted key.
+ * @param {string} key
+ * @returns {Readonly<SettingEntry>|null}
+ */
+export function getSettingEntry(key) {
+  if (typeof key !== 'string') return null;
+  return BY_KEY.get(key) ?? null;
+}
+
+/** True when `key` names a declared registry entry. */
+export function isKnownSetting(key) {
+  return getSettingEntry(key) !== null;
+}
+
+/** Every declared key, in registry order. */
+export function listRegistryKeys() {
+  return SETTINGS_REGISTRY.map((entry) => entry.key);
+}
+
+/** Every declared key the given vault template ships ("heyspex" or "customer"). */
+export function listKeysForTemplate(template) {
+  return SETTINGS_REGISTRY.filter((entry) => entry.templates.includes(template)).map(
+    (entry) => entry.key,
+  );
+}