heyspex 0.2.0 → 0.2.1

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

@@ -121,6 +121,7 @@ export async function collectOccupiedKeysEitherKindViaTier(
   { tier, consoleUrl, consoleFetch = defaultConsoleFetch, walk = walkSpecListPages } = {},
 ) {
   return readViaSelector({
+    allowDiskFallback: false,
     tier,
     diskRead: () => collectOccupiedKeysEitherKind(vaultRoot),
     neonRead: async () => {

package/vendor/heyspex-mcp/on-deck-brief.mjs

@@ -44,7 +44,7 @@
 // full-mode each get phase-appropriate dispatch.
 // ────────────────────────────────────────────────────────────────────────────
 
-import { ConsoleUnreachableCloudModeError, readViaSelector, resolveReadTier, resolveVaultWriteMode } from './read-path.mjs';
+import { ConsoleUnreachableCloudModeError, readViaSelector, resolveReadTier, resolveVaultWriteMode, withDegradationScope } from './read-path.mjs';
 import { consoleFetch, controlError, controlOk, enrichConsoleFailurePayloadAsync } from './console-transport.mjs';
 import { disambiguateClaimSpecId, findSpecFile, loadRoadmap, loadSpec, loadSpecByIdViaTier, loadTask, loadTaskViaGraph, parseFrontmatter, prefetchCloudTaskGraph, wikilinkTarget } from './vault-io.mjs';
 import { isAbsolute, join } from 'node:path';
@@ -1924,7 +1924,7 @@ export function composeAgentOrchestration(result, args = {}) {
           '',
           '---',
           '',
-          `📝 \`${displaySpecId}\` has no \`summary:\` yet — author one in the spec's frontmatter before claiming.`,
+          `📝 \`${displaySpecId}\` has no \`summary:\` yet — author one with \`heyspex_author_summary\` (cloud reliance) or in the file's frontmatter (local reliance) before claiming.`,
         ].join('\n');
     return {
       user_prompt: notice,
@@ -2860,7 +2860,24 @@ export async function injectVaultWriteMode(args = {}, resolveWriteMode = resolve
   return args;
 }
 
+/**
+ * Degrade-don't-die wrapper: when any cloud loader inside the brief fell back
+ * to the local clone ({@link readViaSelector}), the response JSON carries
+ * `degraded: true, source: 'disk', cloud_error, warning` at its top level.
+ */
 export async function handleNextOnDeck(vaultRoot, config, args) {
+  const { value, degraded } = await withDegradationScope(() => handleNextOnDeckInner(vaultRoot, config, args));
+  if (!degraded || !value || value.isError) return value;
+  try {
+    const first = value.content?.[0];
+    const parsed = JSON.parse(first.text);
+    return { ...value, content: [{ ...first, text: JSON.stringify({ ...parsed, ...degraded }, null, 2) }] };
+  } catch {
+    return value;
+  }
+}
+
+async function handleNextOnDeckInner(vaultRoot, config, args) {
   // Resolve the Neon layer-1 pin first (async), then the frozen milestone
   // snapshot order (async, [[HS-TASK-JHIA]]), then run the sync resolver with
   // both threaded in via `neon_pin_spec_id` / `frozen_epic_order`. See