heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/mvp-mode.mjs

@@ -12,13 +12,56 @@
  * close-out gate while ON).
  */
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
 
 export function configYamlPath(vaultRoot) {
   return join(vaultRoot, '.heyspex', 'config.yaml');
 }
 
+// The code checkout (this package's root). Since the repo split (2026-08-31)
+// `.heyspex/config.yaml` is git-tracked HERE and ignored in the vault repo
+// (`.heyspex/*` in its .gitignore), so a vault-root-only read found nothing,
+// reported MVP mode OFF, and every task became a full review unit an agent
+// could not hand off (409 CLOSE_NOT_PERMITTED on every submit). Same
+// precedence as console-transport.mjs / dev-tools.mjs: HS_PKG_ROOT wins.
+// Resolved per call (not once at import) so a caller that sets HS_PKG_ROOT
+// after this module loads — a test pointing the fallback at its own fixture
+// checkout — is honored; a real process sets it before boot, so the value is
+// identical there.
+function checkoutRoot() {
+  return resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+}
+
+/**
+ * Candidate config.yaml paths, first hit wins: the vault root, then the code
+ * checkout — but the fallback applies only to a directory that IS a HeySpex
+ * vault and merely lacks the file, i.e. the post-split vault checkout.
+ *
+ * "Is a vault" means the `heyspex.yaml` marker `hs init` writes at the vault
+ * root (adr-0009 / the vault-marker contract in CLAUDE.md). Deliberately
+ * NARROWER than `isVaultRoot()` in vault-resolve.mjs (marker OR `specs/`) and
+ * narrower than an earlier `.heyspex/` container check: a scratch or fixture
+ * directory routinely grows `specs/` and a `.heyspex/` container (that is what
+ * `writeReviewFocus`, `record_wip`, etc. create) without ever being a vault
+ * checkout, and under the looser tests it silently inherited THIS repo's real
+ * config — turning MVP mode on and the review grain to milestone inside a
+ * fixture whose assertions describe an unconfigured vault. The marker is
+ * written by `hs init` and present in every real vault checkout, so a real
+ * user's fallback is unchanged; a marker-less directory keeps the original
+ * "file missing ⇒ MVP off" contract.
+ */
+export function configYamlCandidates(vaultRoot) {
+  const out = [];
+  if (vaultRoot) out.push(configYamlPath(vaultRoot));
+  const isVault = Boolean(vaultRoot) && existsSync(join(vaultRoot, 'heyspex.yaml'));
+  const fallback = configYamlPath(checkoutRoot());
+  if (isVault && !out.includes(fallback)) out.push(fallback);
+  return out;
+}
+
 function stripInlineComment(value) {
   // Drop a trailing ` # comment` that isn't inside quotes. The config uses
   // unquoted scalars, so a simple split on ` #` is sufficient and safe.
@@ -89,12 +132,16 @@ export function parseMvpModeBlock(raw) {
  * falsy) — same contract as the console's `readMvpModeState`.
  */
 export function readMvpModeState(vaultRoot) {
-  let raw;
-  try {
-    raw = readFileSync(configYamlPath(vaultRoot), 'utf-8');
-  } catch {
-    return null;
+  let raw = null;
+  for (const candidate of configYamlCandidates(vaultRoot)) {
+    try {
+      raw = readFileSync(candidate, 'utf-8');
+      break;
+    } catch {
+      raw = null;
+    }
   }
+  if (raw === null) return null;
   const block = parseMvpModeBlock(raw);
   if (!block || !block.enabled) return null;
   return block;

package/vendor/heyspex-mcp/obligation-backstop.mjs

@@ -0,0 +1,103 @@
+/**
+ * MCP-side backstop for the directive-obligation gate ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]).
+ *
+ * The PreToolUse hook (spexharness/src/gates/directive-obligation-gate.mjs) is the primary enforcement,
+ * but hooks do not load on every surface (a bare MCP client, a seat with no harness). This module lets
+ * the tools themselves refuse implementation work while a capture directive is outstanding. It reads
+ * the SAME state file the hook writes, through scripts/lib/directive-obligations.mjs (never a second
+ * parser): `.heyspex/directive-obligations.json` under the project root.
+ *
+ * FAIL OPEN everywhere: a missing / unreadable state file, no obligation, any thrown error -> never refuse.
+ * Break-glass (owner only, env): HEYSPEX_OBLIGATION_BACKSTOP_OFF=1.
+ */
+import path from 'node:path';
+
+import { outstanding, readObligations } from '../../scripts/lib/directive-obligations.mjs';
+
+export const OBLIGATION_BACKSTOP_OFF_ENV = 'HEYSPEX_OBLIGATION_BACKSTOP_OFF';
+export const CAPTURE_OBLIGATION_ERROR = 'CAPTURE_OBLIGATION_OUTSTANDING';
+/** With no resolvable session id, only an obligation armed this recently counts. */
+export const NO_SESSION_WINDOW_MS = 30 * 60 * 1000;
+/** heyspex_file_spec types that are implementation filings (research/diagnose/memory/capture stay open). */
+export const IMPLEMENTATION_TYPES = Object.freeze(['task', 'epic', 'milestone']);
+
+/** The ids the MCP identity layer returns when it could not resolve a real session. */
+function isUnresolvedSession(sessionId) {
+  const s = String(sessionId ?? '').trim();
+  return !s || s === 'local';
+}
+
+/** Project roots to look in, in order: the hook's own (CLAUDE_PROJECT_DIR), the cwd, then the vault root. */
+export function candidateRoots({ roots, vaultRoot, env = process.env } = {}) {
+  if (Array.isArray(roots) && roots.length) return roots;
+  const out = [];
+  const fromEnv = String(env.CLAUDE_PROJECT_DIR ?? '').trim();
+  if (fromEnv) out.push(fromEnv);
+  out.push(process.cwd());
+  if (vaultRoot) out.push(vaultRoot);
+  return [...new Set(out.map((r) => path.resolve(r)))];
+}
+
+function summarize(ob, reason) {
+  return { outstanding: true, reason, armedAt: ob.issued_at ?? null, directiveKey: ob.id ?? ob.prompt_sha ?? null };
+}
+
+const NONE = (reason) => ({ outstanding: false, reason, armedAt: null, directiveKey: null });
+
+/**
+ * @param {{ sessionId?: string, now?: number, roots?: string[], vaultRoot?: string, env?: object }} [opts]
+ * @returns {{ outstanding: boolean, reason: string, armedAt: string|null, directiveKey: string|null }}
+ */
+export function checkOutstandingCaptureObligation({ sessionId, now = Date.now(), roots, vaultRoot, env = process.env } = {}) {
+  try {
+    if (String(env[OBLIGATION_BACKSTOP_OFF_ENV] ?? '') === '1') return NONE('backstop off (env)');
+    const known = !isUnresolvedSession(sessionId);
+    for (const root of candidateRoots({ roots, vaultRoot, env })) {
+      const full = readObligations(root, known ? String(sessionId).trim() : undefined);
+      if (!full) continue;
+      if (known) {
+        const open = outstanding(full, String(sessionId).trim(), now);
+        if (open.length) return summarize(open[0], 'capture directive issued for this session and not yet satisfied');
+        continue;
+      }
+      // No session id: any unsatisfied obligation armed in this project within the window.
+      const records = [full, ...Object.entries(full.others ?? {}).map(([sid, o]) => ({ ...o, session_id: sid }))];
+      for (const rec of records) {
+        if (!rec?.session_id) continue;
+        const open = outstanding(rec, rec.session_id, now).filter((o) => now - Date.parse(o.issued_at) <= NO_SESSION_WINDOW_MS);
+        if (open.length) return summarize(open[0], 'capture directive armed in this project within 30 minutes and not yet satisfied (session unknown)');
+      }
+    }
+    return NONE('no outstanding capture obligation');
+  } catch {
+    return NONE('obligation state unreadable (fail open)');
+  }
+}
+
+/**
+ * Tool-level verdict. Returns null (allow) or { error, message, tool, armed_at, directive_key }.
+ * Refuses heyspex_claim_spec always, and heyspex_file_spec only for task/epic/milestone filings.
+ */
+export function evaluateObligationBackstop(toolName, args = {}, opts = {}) {
+  try {
+    if (toolName !== 'heyspex_claim_spec' && toolName !== 'heyspex_file_spec') return null;
+    if (toolName === 'heyspex_file_spec') {
+      const type = String(args?.type ?? '').trim().toLowerCase();
+      if (!IMPLEMENTATION_TYPES.includes(type)) return null;
+    }
+    const r = checkOutstandingCaptureObligation(opts);
+    if (!r.outstanding) return null;
+    return {
+      error: CAPTURE_OBLIGATION_ERROR,
+      message:
+        `${toolName} refused: the capture_on_idea directive was issued (${r.armedAt ?? 'earlier'}) and the capture has not happened. ` +
+        'Call heyspex_update_capture for the armed capture (with the owner\'s exact words), or have the owner say "discard". ' +
+        `Then retry. (Owner-only break-glass: ${OBLIGATION_BACKSTOP_OFF_ENV}=1.)`,
+      tool: toolName,
+      armed_at: r.armedAt,
+      directive_key: r.directiveKey,
+    };
+  } catch {
+    return null;
+  }
+}

package/vendor/heyspex-mcp/occupied-keys.mjs

@@ -0,0 +1,142 @@
+/**
+ * occupied-keys.mjs — tier-aware vault KEY occupancy for the id minters
+ * ([[HS-FJWL]]).
+ *
+ * `collectOccupiedKeysEitherKind` (spec-id-lib.mjs) is a `readdirSync` walk of
+ * `specs/**` basenames. That is complete on the DISK tier and blind on the
+ * CLOUD tier: since the cutover to cloud reliance a filed spec gets a Neon row
+ * and NO local `.md` (`landed.onDisk: false`), so the walk answers from a local
+ * clone that is not empty, just STALE — a large, plausible-looking set that
+ * silently omits every cloud-only spec. A blind scan is tolerable for FAMILY
+ * keys (they are a "pick something fresh" default, not a uniqueness gate —
+ * spec-id-lib.mjs `collectOccupiedFamilyKeysFromVault`) and unsound for FILE
+ * keys, which under Naming V3 ARE the unique per-file identity that `id:` keys
+ * onto. Re-issuing one mints a duplicate id.
+ *
+ * Shape follows the existing `*ViaTier` family and composes on
+ * {@link readViaSelector} — {@link collectOccupiedCaptureIdsViaTier}
+ * (capture-tools.mjs) is the direct precedent.
+ *
+ * CONSOLE READ STRATEGY — full enumeration, not a per-candidate existence
+ * probe. `GET /api/specs/resolve?q=<key>` would be one request per mint, but it
+ * answers `404 { error: "not_found" }` BOTH for "this key is free" and for "you
+ * are not authorized for this vault" (`resolveCallerVaultScope` →
+ * `not_found`, spex-console/src/app/api/specs/resolve/route.ts), so a
+ * signed-out session would read every key as free and mint duplicates — the
+ * exact failure this module exists to prevent. It also cannot see family keys
+ * in era-1 (`HS-TASK-<family>-…`) or era-3 (`HS-<fileKey>-<family>-TYPE-…`)
+ * positions, because its prefix tier only matches a LEADING `<token>-`.
+ * Enumerating `GET /api/specs?fields=id,basename` instead applies the SAME
+ * basename parsers the disk walk uses, so both namespaces and all three eras
+ * are covered identically, and an unauthorized answer is detectable (it comes
+ * back as an empty page — see the empty-set refusal below).
+ */
+
+import { consoleFetch as defaultConsoleFetch } from './console-transport.mjs';
+import { walkSpecListPages } from './list-tools.mjs';
+import { readViaSelector } from './read-path.mjs';
+import {
+  bareFileKeyOf,
+  collectOccupiedKeysEitherKind,
+  fileKeyFromBasename,
+  parseSpecId,
+} from './spec-id-lib.mjs';
+
+/** The projection the cloud occupancy walk asks for — two fields, ~60 bytes/row. */
+export const OCCUPIED_KEYS_LIST_PATH = '/api/specs?fields=id,basename';
+
+/** `routeLabel` for the selector's unreachable-console error. */
+const ROUTE_LABEL = `GET ${OCCUPIED_KEYS_LIST_PATH}`;
+
+/**
+ * Cross-namespace occupancy (FILE keys ∪ FAMILY keys) from `GET /api/specs`
+ * rows — the cloud twin of {@link collectOccupiedKeysEitherKind}'s union.
+ *
+ * Reads the same two atoms the disk walk reads, from the same parsers:
+ *   - `basename` → `fileKeyFromBasename` (era-3 leading token / era-1-2
+ *     after-TYPE token) and `parseSpecId(...).familyKey` (positional in every
+ *     era).
+ *   - `id` → a bare era-3 `HS-<fileKey>` (`bareFileKeyOf`), plus the positional
+ *     atoms of a full id. The disk walk has only filenames to go on; list rows
+ *     carry the stored `id:` too, so this is a strict superset — never a
+ *     smaller set than the disk scan would return for the same specs.
+ *
+ * @param {Array<{ id?: string|null, basename?: string|null }>} rows
+ * @returns {Set<string>} uppercase keys
+ */
+export function occupiedKeysFromSpecRows(rows) {
+  const occupied = new Set();
+  const addFrom = (value) => {
+    if (typeof value !== 'string' || !value.trim()) return;
+    const bare = bareFileKeyOf(value);
+    if (bare) occupied.add(bare);
+    const fileKey = fileKeyFromBasename(value);
+    if (fileKey) occupied.add(fileKey.toUpperCase());
+    const parsed = parseSpecId(value);
+    if (parsed?.familyKey) occupied.add(parsed.familyKey.toUpperCase());
+    if (parsed?.fileKey) occupied.add(parsed.fileKey.toUpperCase());
+  };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    addFrom(row?.basename);
+    addFrom(row?.id);
+  }
+  return occupied;
+}
+
+/**
+ * Tier-aware {@link collectOccupiedKeysEitherKind}.
+ *
+ * - `disk`: byte-identical to today's scan; `neonRead` never runs, so a
+ *   disk-tier mint makes ZERO console calls.
+ * - `neon`: walks `GET /api/specs?fields=id,basename` to exhaustion. The route
+ *   caps a page at 500 rows and hands back `next_cursor`
+ *   ([[HS-0R2X-8KK5-EPIC]]); {@link walkSpecListPages} follows it, because a
+ *   caller that reads page 1 only would UNDER-COUNT occupancy, which is the
+ *   same duplicate-id bug wearing a different hat.
+ *
+ * FAILS LOUDLY, deliberately, and in TWO ways the read path does not:
+ *
+ *  1. An unreachable/erroring console throws
+ *     {@link ConsoleUnreachableCloudModeError} via the selector — no silent
+ *     disk fallback. That is the selector's own contract, and it is the right
+ *     one here for a stronger reason than it is for a read: handing out a
+ *     possibly-duplicate id is worse than refusing to mint. A read that falls
+ *     back to a stale local copy shows stale data; a MINT that falls back to a
+ *     stale local copy writes a colliding id into the vault of record.
+ *  2. An EMPTY occupancy set from the cloud is refused rather than returned.
+ *     `GET /api/specs` answers `200 { specs: [], vaultScope: { authorized:
+ *     false } }` when the caller is not authorized for the vault
+ *     (spex-console/src/app/api/specs/route.ts), and an empty set is exactly
+ *     what makes every candidate key look free. A real vault that could be
+ *     minted into is never empty — the spec being minted is filed INTO an
+ *     existing vault — so "zero rows" is always either a signed-out session or
+ *     a wrong-vault scope, never a legitimate answer.
+ *
+ * @param {string} vaultRoot
+ * @param {{ tier: 'disk'|'neon', consoleUrl?: string, consoleFetch?: Function, walk?: Function }} opts
+ * @returns {Promise<Set<string>>}
+ */
+export async function collectOccupiedKeysEitherKindViaTier(
+  vaultRoot,
+  { tier, consoleUrl, consoleFetch = defaultConsoleFetch, walk = walkSpecListPages } = {},
+) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => collectOccupiedKeysEitherKind(vaultRoot),
+    neonRead: async () => {
+      const rows = await walk(consoleFetch, OCCUPIED_KEYS_LIST_PATH);
+      if (!Array.isArray(rows) || rows.length === 0) {
+        throw new Error(
+          `${ROUTE_LABEL} returned 0 specs — refusing to mint against an empty occupancy set. ` +
+            `An unauthorized or wrong-vault caller gets \`200 { specs: [], vaultScope: ` +
+            `{ authorized: false } }\` from this route, which is indistinguishable from ` +
+            `"every key is free"; minting on it would hand out a duplicate file key.`,
+        );
+      }
+      return occupiedKeysFromSpecRows(rows);
+    },
+    routeLabel: ROUTE_LABEL,
+    consoleUrl,
+  });
+}