heyspex 0.2.5 → 0.2.7

package/spexharness/src/gates/directive-obligation-gate.decide.mjs

@@ -1,132 +1,132 @@
-// spexharness/src/gates/directive-obligation-gate.decide.mjs
-//
-// Pure decision logic for the directive-obligation-gate ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]).
-// No stdin/stdout/process.exit and no fs: every input arrives as an argument, so the gate module
-// (./directive-obligation-gate.mjs) owns all I/O and a test drives these functions directly.
-
-import { extractShellTargets } from './_shell-write-targets.mjs';
-import { isProductCodePath } from '../../../scripts/lib/directive-obligations.mjs';
-
-const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'write_file', 'edit_file']);
-const SHELL_TOOLS = new Set(['Bash', 'PowerShell', 'Shell']);
-const SPAWN_TOOLS = new Set(['Agent', 'Task']);
-
-/** Sub-agent types that only read / plan / triage: spawning one never builds anything. */
-export const READ_ONLY_AGENT_TYPES = new Set([
-  'explore',
-  'plan',
-  'claude-code-guide',
-  'capture-triager',
-  'plan-grounder',
-  'research-synthesizer',
-  'resolution-triager',
-  'statusline-setup',
-]);
-
-// Commands that build, install, serve or publish product code. Test runners are deliberately absent.
-const BUILD_CMD_RE = new RegExp(
-  '(?:^|[\\s;&|(])(?:' +
-    '(?:npm|pnpm|yarn|bun)\\s+(?:run\\s+)?(?:build|dev|start|install|i|add|ci|publish|deploy)\\b' +
-    '|(?:npx\\s+)?(?:next|vite|webpack|turbo|esbuild)\\s+(?:build|dev)\\b' +
-    '|dotnet\\s+(?:build|publish|run)\\b' +
-    '|cargo\\s+(?:build|run|install)\\b' +
-    '|make\\b' +
-    '|vercel\\s+(?:deploy|--prod)\\b' +
-    '|(?:claude|spexcode)\\s+(?:-p|--print)\\b' +
-    ')',
-  'i',
-);
-
-/** Is this a heyspex_* MCP call (any spelling)? Those are never gated. */
-export function isHeyspexMcpTool(name) {
-  return /(?:^|__)heyspex_/.test(String(name ?? ''));
-}
-
-function pathOf(toolInput) {
-  return toolInput?.file_path ?? toolInput?.notebook_path ?? toolInput?.path ?? toolInput?.filePath ?? '';
-}
-
-/**
- * Classify one tool call into the surface this gate cares about.
- * @returns {{ kind: 'exempt'|'spawn'|'code_write'|'shell_build'|'shell_write', detail?: string }}
- */
-export function classifyToolCall({ toolName, toolInput }, { cwd, vaultRoot } = {}) {
-  const name = String(toolName ?? '');
-  if (!name || isHeyspexMcpTool(name)) return { kind: 'exempt' };
-  const input = toolInput ?? {};
-
-  if (SPAWN_TOOLS.has(name)) {
-    const type = String(input.subagent_type ?? '').trim().toLowerCase();
-    if (type && READ_ONLY_AGENT_TYPES.has(type)) return { kind: 'exempt' };
-    return { kind: 'spawn', detail: type || 'general-purpose' };
-  }
-
-  if (WRITE_TOOLS.has(name)) {
-    const target = pathOf(input);
-    return isProductCodePath(target, { cwd, vaultRoot }) ? { kind: 'code_write', detail: String(target) } : { kind: 'exempt' };
-  }
-
-  if (SHELL_TOOLS.has(name)) {
-    const command = String(input.command ?? '');
-    const product = extractShellTargets(command).find((t) => isProductCodePath(t, { cwd, vaultRoot }));
-    if (product) return { kind: 'shell_write', detail: product };
-    if (BUILD_CMD_RE.test(command)) return { kind: 'shell_build', detail: command.trim().slice(0, 80) };
-    return { kind: 'exempt' };
-  }
-
-  return { kind: 'exempt' };
-}
-
-const HOW_TO_DISCHARGE =
-  'Capture the owner\'s words first: call heyspex_update_capture (or heyspex_file_spec / the /hs-capture skill) with their exact ' +
-  'message, then retry. Reads, greps, git, test runs, vault and .heyspex writes and every heyspex_* tool stay open meanwhile.';
-
-/**
- * Rule 1: while a capture obligation is outstanding for this session, deny a sub-agent spawn, a
- * product-code write and a build/product-write shell command.
- * @returns {{ deny: boolean, reason?: string, rule?: string }}
- */
-export function decideObligation(call, { outstandingCount, cwd, vaultRoot }) {
-  if (!outstandingCount) return { deny: false };
-  const c = classifyToolCall(call, { cwd, vaultRoot });
-  if (c.kind === 'exempt') return { deny: false };
-  const what =
-    c.kind === 'spawn' ? `spawn a ${c.detail} sub-agent`
-    : c.kind === 'code_write' ? `write product code (${c.detail})`
-    : c.kind === 'shell_write' ? `write product code from the shell (${c.detail})`
-    : `run a build command (${c.detail})`;
-  return {
-    deny: true,
-    rule: 'directive-obligation',
-    reason:
-      `HEYSPEX directive-obligation-gate: the capture_on_idea directive was issued for this session and the capture has not happened, so you may not ${what}. ` +
-      `${HOW_TO_DISCHARGE} (Break-glass, owner only: HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]])`,
-  };
-}
-
-/**
- * Rule 2 (claim-before-build): deny a build sub-agent spawn or a product-code write when the session
- * has no claimed spec, no on-deck capture and no waiver. Independent of the plan-exit marker and CLAUDE_AGENT.
- */
-export function decideClaimBeforeBuild(call, { hasRoadToCode, cwd, vaultRoot }) {
-  if (hasRoadToCode) return { deny: false };
-  const c = classifyToolCall(call, { cwd, vaultRoot });
-  if (c.kind !== 'spawn' && c.kind !== 'code_write') return { deny: false };
-  const what = c.kind === 'spawn' ? `spawn a ${c.detail} sub-agent` : `edit product code (${c.detail})`;
-  return {
-    deny: true,
-    rule: 'claim-before-build',
-    reason:
-      `HEYSPEX claim-before-build: this session holds no claimed spec (claim heartbeat confirmed), has no capture on deck and no waiver, so you may not ${what}. ` +
-      'Claim the spec you are building (heyspex_claim_spec) or capture the idea (heyspex_update_capture / /hs-capture), then retry. ' +
-      '(Break-glass, owner only: HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]])',
-  };
-}
-
-export function stopReason(count) {
-  return (
-    `HEYSPEX directive-obligation-gate: you are about to stop with ${count} capture obligation(s) unmet - the capture_on_idea directive ` +
-    'was issued this session and no capture write was seen. Capture the owner\'s words now (heyspex_update_capture with their exact message, ' +
-    'or /hs-capture), then finish. This re-drive fires once; it will not block again. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]'
-  );
-}
+// spexharness/src/gates/directive-obligation-gate.decide.mjs
+//
+// Pure decision logic for the directive-obligation-gate ([[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]).
+// No stdin/stdout/process.exit and no fs: every input arrives as an argument, so the gate module
+// (./directive-obligation-gate.mjs) owns all I/O and a test drives these functions directly.
+
+import { extractShellTargets } from './_shell-write-targets.mjs';
+import { isProductCodePath } from '../../../scripts/lib/directive-obligations.mjs';
+
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'write_file', 'edit_file']);
+const SHELL_TOOLS = new Set(['Bash', 'PowerShell', 'Shell']);
+const SPAWN_TOOLS = new Set(['Agent', 'Task']);
+
+/** Sub-agent types that only read / plan / triage: spawning one never builds anything. */
+export const READ_ONLY_AGENT_TYPES = new Set([
+  'explore',
+  'plan',
+  'claude-code-guide',
+  'capture-triager',
+  'plan-grounder',
+  'research-synthesizer',
+  'resolution-triager',
+  'statusline-setup',
+]);
+
+// Commands that build, install, serve or publish product code. Test runners are deliberately absent.
+const BUILD_CMD_RE = new RegExp(
+  '(?:^|[\\s;&|(])(?:' +
+    '(?:npm|pnpm|yarn|bun)\\s+(?:run\\s+)?(?:build|dev|start|install|i|add|ci|publish|deploy)\\b' +
+    '|(?:npx\\s+)?(?:next|vite|webpack|turbo|esbuild)\\s+(?:build|dev)\\b' +
+    '|dotnet\\s+(?:build|publish|run)\\b' +
+    '|cargo\\s+(?:build|run|install)\\b' +
+    '|make\\b' +
+    '|vercel\\s+(?:deploy|--prod)\\b' +
+    '|(?:claude|spexcode)\\s+(?:-p|--print)\\b' +
+    ')',
+  'i',
+);
+
+/** Is this a heyspex_* MCP call (any spelling)? Those are never gated. */
+export function isHeyspexMcpTool(name) {
+  return /(?:^|__)heyspex_/.test(String(name ?? ''));
+}
+
+function pathOf(toolInput) {
+  return toolInput?.file_path ?? toolInput?.notebook_path ?? toolInput?.path ?? toolInput?.filePath ?? '';
+}
+
+/**
+ * Classify one tool call into the surface this gate cares about.
+ * @returns {{ kind: 'exempt'|'spawn'|'code_write'|'shell_build'|'shell_write', detail?: string }}
+ */
+export function classifyToolCall({ toolName, toolInput }, { cwd, vaultRoot } = {}) {
+  const name = String(toolName ?? '');
+  if (!name || isHeyspexMcpTool(name)) return { kind: 'exempt' };
+  const input = toolInput ?? {};
+
+  if (SPAWN_TOOLS.has(name)) {
+    const type = String(input.subagent_type ?? '').trim().toLowerCase();
+    if (type && READ_ONLY_AGENT_TYPES.has(type)) return { kind: 'exempt' };
+    return { kind: 'spawn', detail: type || 'general-purpose' };
+  }
+
+  if (WRITE_TOOLS.has(name)) {
+    const target = pathOf(input);
+    return isProductCodePath(target, { cwd, vaultRoot }) ? { kind: 'code_write', detail: String(target) } : { kind: 'exempt' };
+  }
+
+  if (SHELL_TOOLS.has(name)) {
+    const command = String(input.command ?? '');
+    const product = extractShellTargets(command).find((t) => isProductCodePath(t, { cwd, vaultRoot }));
+    if (product) return { kind: 'shell_write', detail: product };
+    if (BUILD_CMD_RE.test(command)) return { kind: 'shell_build', detail: command.trim().slice(0, 80) };
+    return { kind: 'exempt' };
+  }
+
+  return { kind: 'exempt' };
+}
+
+const HOW_TO_DISCHARGE =
+  'Capture the owner\'s words first: call heyspex_update_capture (or heyspex_file_spec / the /hs-capture skill) with their exact ' +
+  'message, then retry. Reads, greps, git, test runs, vault and .heyspex writes and every heyspex_* tool stay open meanwhile.';
+
+/**
+ * Rule 1: while a capture obligation is outstanding for this session, deny a sub-agent spawn, a
+ * product-code write and a build/product-write shell command.
+ * @returns {{ deny: boolean, reason?: string, rule?: string }}
+ */
+export function decideObligation(call, { outstandingCount, cwd, vaultRoot }) {
+  if (!outstandingCount) return { deny: false };
+  const c = classifyToolCall(call, { cwd, vaultRoot });
+  if (c.kind === 'exempt') return { deny: false };
+  const what =
+    c.kind === 'spawn' ? `spawn a ${c.detail} sub-agent`
+    : c.kind === 'code_write' ? `write product code (${c.detail})`
+    : c.kind === 'shell_write' ? `write product code from the shell (${c.detail})`
+    : `run a build command (${c.detail})`;
+  return {
+    deny: true,
+    rule: 'directive-obligation',
+    reason:
+      `HEYSPEX directive-obligation-gate: the capture_on_idea directive was issued for this session and the capture has not happened, so you may not ${what}. ` +
+      `${HOW_TO_DISCHARGE} (Break-glass, owner only: HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]])`,
+  };
+}
+
+/**
+ * Rule 2 (claim-before-build): deny a build sub-agent spawn or a product-code write when the session
+ * has no claimed spec, no on-deck capture and no waiver. Independent of the plan-exit marker and CLAUDE_AGENT.
+ */
+export function decideClaimBeforeBuild(call, { hasRoadToCode, cwd, vaultRoot }) {
+  if (hasRoadToCode) return { deny: false };
+  const c = classifyToolCall(call, { cwd, vaultRoot });
+  if (c.kind !== 'spawn' && c.kind !== 'code_write') return { deny: false };
+  const what = c.kind === 'spawn' ? `spawn a ${c.detail} sub-agent` : `edit product code (${c.detail})`;
+  return {
+    deny: true,
+    rule: 'claim-before-build',
+    reason:
+      `HEYSPEX claim-before-build: this session holds no claimed spec (claim heartbeat confirmed), has no capture on deck and no waiver, so you may not ${what}. ` +
+      'Claim the spec you are building (heyspex_claim_spec) or capture the idea (heyspex_update_capture / /hs-capture), then retry. ' +
+      '(Break-glass, owner only: HEYSPEX_DIRECTIVE_OBLIGATION_GATE_OFF=1. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]])',
+  };
+}
+
+export function stopReason(count) {
+  return (
+    `HEYSPEX directive-obligation-gate: you are about to stop with ${count} capture obligation(s) unmet - the capture_on_idea directive ` +
+    'was issued this session and no capture write was seen. Capture the owner\'s words now (heyspex_update_capture with their exact message, ' +
+    'or /hs-capture), then finish. This re-drive fires once; it will not block again. [[HS-20SW-DRSM-DIAG-heyspex-capture-on-idea-and-workflow]]'
+  );
+}

package/spexharness/src/gates/vault-write-tier-guard.decide.mjs

@@ -1,125 +1,153 @@
-// spexharness/src/gates/vault-write-tier-guard.decide.mjs
-//
-// Pure decision for the vault-write-tier-guard PreToolUse gate (HS-FCNH).
-//
-// Problem: on a machine in prod / cloud reliance (`hs dev: prod`) the console
-// reads Neon, and the vault clone on disk is a MIRROR the console never reads
-// back. An agent that hand-edits `<vault>/specs/**/*.md` because a console
-// prompt said so writes into a place nobody reads. This gate denies those disk
-// writes in cloud write mode and names the cloud-routed tool to use instead.
-//
-// No process.exit / stdout here. `fs.existsSync` is the only I/O and is
-// injectable (`deps.exists`).
-//
-// call = { toolName, toolInput }
-// deps = { vaultRoot, writeMode, env, cwd?, exists?, platform? }
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { extractShellTargets } from './_shell-write-targets.mjs';
-
-export const KILL_ENV = 'HEYSPEX_VAULT_WRITE_TIER_GUARD_OFF';
-
-const FILE_TOOLS = new Set(['write', 'edit', 'multiedit', 'notebookedit']);
-const SHELL_TOOLS = new Set(['bash', 'powershell']);
-
-function norm(p, platform) {
-  const r = String(p);
-  return platform === 'win32' ? r.toLowerCase() : r;
-}
-
-/** True when `p` resolves to `<vaultRoot>/specs/**\/*.md` outside `.trash/`. */
-export function isGuardedVaultPath(p, { vaultRoot, cwd, platform = process.platform }) {
-  if (!p || typeof p !== 'string') return false;
-  let abs;
-  try {
-    abs = path.resolve(cwd ?? process.cwd(), p);
-  } catch {
-    return false;
-  }
-  const root = norm(path.resolve(vaultRoot), platform);
-  const target = norm(abs, platform);
-  const rel = path.relative(root, target);
-  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
-  const segs = rel.split(/[\\/]+/);
-  if (segs[0] !== 'specs' || segs.length < 2) return false;
-  if (segs.includes('.trash')) return false;
-  return path.extname(target) === '.md';
-}
-
-function editTexts(toolInput) {
-  const out = [];
-  for (const k of ['new_string', 'content', 'new_source', 'command']) {
-    if (typeof toolInput?.[k] === 'string') out.push(toolInput[k]);
-  }
-  if (Array.isArray(toolInput?.edits)) {
-    for (const e of toolInput.edits) if (typeof e?.new_string === 'string') out.push(e.new_string);
-  }
-  return out;
-}
-
-function pickTool(toolInput) {
-  return editTexts(toolInput).some((t) => /^summary:/m.test(t))
-    ? 'heyspex_author_summary'
-    : 'heyspex_edit_file';
-}
-
-const ROWS = [
-  ['summary: field', 'heyspex_author_summary { spec_id, summary }  (load via heyspex_load_tools)', 'heyspex_author_summary'],
-  ['body / other frontmatter', 'heyspex_edit_file { file_path, content }      (cloud-routed in this mode)', 'heyspex_edit_file'],
-  ['status', 'heyspex_submit_for_review / heyspex_claim_spec — never hand-edit status', null],
-  ['new spec', 'heyspex_file_spec', null],
-];
-
-export function denyReason(target, tool) {
-  const rows = ROWS.map(([label, use, t]) => {
-    const mark = t === tool ? '=> ' : '   ';
-    return `${mark}${label.padEnd(24)} → ${use}`;
-  }).join('\n');
-  return (
-    `[vault-write-tier-guard] This machine writes the vault to the CLOUD (hs dev: prod). ` +
-    `${target} is a disk mirror the console never reads back (HS-FCNH).\n${rows}\n` +
-    `Break-glass for a human: ${KILL_ENV}=1.`
-  );
-}
-
-/**
- * @param {{ toolName: string, toolInput: Record<string, unknown> }} call
- * @param {{ vaultRoot?: string|null, writeMode?: string, env?: Record<string,string|undefined>,
- *           cwd?: string, exists?: (p: string) => boolean, platform?: string }} deps
- * @returns {{ allow: boolean, reason?: string, tool?: string }}
- */
-export function decide(call, deps = {}) {
-  const env = deps.env ?? process.env;
-  if (deps.writeMode !== 'cloud') return { allow: true };
-  if (String(env[KILL_ENV] ?? '') === '1') return { allow: true };
-  const vaultRoot = deps.vaultRoot;
-  if (!vaultRoot || typeof vaultRoot !== 'string') return { allow: true };
-  const exists = deps.exists ?? ((p) => fs.existsSync(p));
-  if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { allow: true };
-
-  const platform = deps.platform ?? process.platform;
-  const ctx = { vaultRoot, cwd: deps.cwd, platform };
-  const tool = String(call?.toolName ?? '').toLowerCase();
-  const input = call?.toolInput ?? {};
-
-  if (FILE_TOOLS.has(tool)) {
-    const fp = input.file_path ?? input.notebook_path ?? input.filePath;
-    if (isGuardedVaultPath(fp, ctx)) {
-      return { allow: false, tool: pickTool(input), reason: denyReason(String(fp), pickTool(input)) };
-    }
-    return { allow: true };
-  }
-
-  if (SHELL_TOOLS.has(tool)) {
-    const command = String(input.command ?? '');
-    if (!command) return { allow: true };
-    for (const t of extractShellTargets(command)) {
-      if (isGuardedVaultPath(t, ctx)) {
-        return { allow: false, tool: pickTool(input), reason: denyReason(t, pickTool(input)) };
-      }
-    }
-  }
-  return { allow: true };
-}
+// spexharness/src/gates/vault-write-tier-guard.decide.mjs
+//
+// Pure decision for the vault-write-tier-guard PreToolUse gate (HS-FCNH).
+//
+// Problem: on a machine in prod / cloud reliance (`hs dev: prod`) the console
+// reads Neon, and the vault clone on disk is a MIRROR the console never reads
+// back. An agent that hand-edits `<vault>/specs/**/*.md` because a console
+// prompt said so writes into a place nobody reads. This gate denies those disk
+// writes in cloud write mode and names the cloud-routed tool to use instead.
+//
+// No process.exit / stdout here. `fs.existsSync` is the only I/O and is
+// injectable (`deps.exists`).
+//
+// call = { toolName, toolInput }
+// deps = { vaultRoot, writeMode, env, cwd?, exists?, readFile?, platform? }
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { extractShellTargets } from './_shell-write-targets.mjs';
+
+export const KILL_ENV = 'HEYSPEX_VAULT_WRITE_TIER_GUARD_OFF';
+
+const FILE_TOOLS = new Set(['write', 'edit', 'multiedit', 'notebookedit']);
+const SHELL_TOOLS = new Set(['bash', 'powershell']);
+
+function norm(p, platform) {
+  const r = String(p);
+  return platform === 'win32' ? r.toLowerCase() : r;
+}
+
+/** True when `p` resolves to `<vaultRoot>/specs/**\/*.md` outside `.trash/`. */
+export function isGuardedVaultPath(p, { vaultRoot, cwd, platform = process.platform }) {
+  if (!p || typeof p !== 'string') return false;
+  let abs;
+  try {
+    abs = path.resolve(cwd ?? process.cwd(), p);
+  } catch {
+    return false;
+  }
+  const root = norm(path.resolve(vaultRoot), platform);
+  const target = norm(abs, platform);
+  const rel = path.relative(root, target);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  const segs = rel.split(/[\\/]+/);
+  if (segs[0] !== 'specs' || segs.length < 2) return false;
+  if (segs.includes('.trash')) return false;
+  return path.extname(target) === '.md';
+}
+
+function editTexts(toolInput) {
+  const out = [];
+  for (const k of ['new_string', 'content', 'new_source', 'command']) {
+    if (typeof toolInput?.[k] === 'string') out.push(toolInput[k]);
+  }
+  if (Array.isArray(toolInput?.edits)) {
+    for (const e of toolInput.edits) if (typeof e?.new_string === 'string') out.push(e.new_string);
+  }
+  return out;
+}
+
+const ID_LINE = /^id:[ \t]*\S/m;
+
+/** The frontmatter block of `text`, or '' when it has none. */
+function frontmatterOf(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(String(text ?? ''));
+  return m ? m[1] : '';
+}
+
+/**
+ * True when the write touches a cloud-backed spec: the file on disk carries an
+ * `id:` frontmatter key, or the incoming text does. An id-less working doc
+ * (e.g. `specs/refinement/*.md`) has no cloud row — `heyspex_edit_file` refuses
+ * it in cloud mode (CLOUD_MODE_UNSUPPORTED_WRITE) — so disk is its only home and
+ * blocking it would leave the agent no way to write it at all (HS-FCY9).
+ */
+function touchesCloudSpec(target, toolInput, { cwd, readFile }) {
+  if (editTexts(toolInput).some((t) => ID_LINE.test(t))) return true;
+  let current;
+  try {
+    current = readFile(path.resolve(cwd ?? process.cwd(), target));
+  } catch {
+    return false;
+  }
+  return ID_LINE.test(frontmatterOf(current));
+}
+
+function pickTool(toolInput) {
+  return editTexts(toolInput).some((t) => /^summary:/m.test(t))
+    ? 'heyspex_author_summary'
+    : 'heyspex_edit_file';
+}
+
+const ROWS = [
+  ['summary: field', 'heyspex_author_summary { spec_id, summary }  (load via heyspex_load_tools)', 'heyspex_author_summary'],
+  ['body / other frontmatter', 'heyspex_edit_file { file_path, content }      (cloud-routed in this mode)', 'heyspex_edit_file'],
+  ['status', 'heyspex_submit_for_review / heyspex_claim_spec — never hand-edit status', null],
+  ['new spec', 'heyspex_file_spec', null],
+];
+
+export function denyReason(target, tool) {
+  const rows = ROWS.map(([label, use, t]) => {
+    const mark = t === tool ? '=> ' : '   ';
+    return `${mark}${label.padEnd(24)} → ${use}`;
+  }).join('\n');
+  return (
+    `[vault-write-tier-guard] This machine writes the vault to the CLOUD (hs dev: prod). ` +
+    `${target} is a disk mirror the console never reads back (HS-FCNH).\n${rows}\n` +
+    `Break-glass for a human: ${KILL_ENV}=1.`
+  );
+}
+
+/**
+ * @param {{ toolName: string, toolInput: Record<string, unknown> }} call
+ * @param {{ vaultRoot?: string|null, writeMode?: string, env?: Record<string,string|undefined>,
+ *           cwd?: string, exists?: (p: string) => boolean, platform?: string }} deps
+ * @returns {{ allow: boolean, reason?: string, tool?: string }}
+ */
+export function decide(call, deps = {}) {
+  const env = deps.env ?? process.env;
+  if (deps.writeMode !== 'cloud') return { allow: true };
+  if (String(env[KILL_ENV] ?? '') === '1') return { allow: true };
+  const vaultRoot = deps.vaultRoot;
+  if (!vaultRoot || typeof vaultRoot !== 'string') return { allow: true };
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  if (!exists(path.join(vaultRoot, 'heyspex.yaml'))) return { allow: true };
+
+  const platform = deps.platform ?? process.platform;
+  const ctx = { vaultRoot, cwd: deps.cwd, platform };
+  const tool = String(call?.toolName ?? '').toLowerCase();
+  const input = call?.toolInput ?? {};
+  const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
+  const guarded = (t) => isGuardedVaultPath(t, ctx) && touchesCloudSpec(t, input, { cwd: deps.cwd, readFile });
+
+  if (FILE_TOOLS.has(tool)) {
+    const fp = input.file_path ?? input.notebook_path ?? input.filePath;
+    if (guarded(fp)) {
+      return { allow: false, tool: pickTool(input), reason: denyReason(String(fp), pickTool(input)) };
+    }
+    return { allow: true };
+  }
+
+  if (SHELL_TOOLS.has(tool)) {
+    const command = String(input.command ?? '');
+    if (!command) return { allow: true };
+    for (const t of extractShellTargets(command)) {
+      if (guarded(t)) {
+        return { allow: false, tool: pickTool(input), reason: denyReason(t, pickTool(input)) };
+      }
+    }
+  }
+  return { allow: true };
+}

package/spexharness/src/seat-context.mjs

@@ -20,7 +20,7 @@
 
 import { readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { buildSeatContext, repoRoot } from '../../dev-factory/lib/seat-context.mjs';
+import { ambientOverlayRoot, buildSeatContext, repoRoot } from '../../dev-factory/lib/seat-context.mjs';
 
 export { repoRoot };
 
@@ -94,16 +94,21 @@ function listSkillIds(dir) {
  *   memories: string[],
  * }}
  */
-export function loadSeatContext({ root = repoRoot(), seatId = null, vaultRoot = null } = {}) {
-  const seatLine = buildSeatContext(root);
+export function loadSeatContext({ root: explicitRoot, seatId = null, vaultRoot = null } = {}) {
+  // The owner's seats.json is read only from an explicit root or an ambient root where the
+  // dev-factory overlay is open ([[HS-R475-C86Z-TASK-load-the-owner-dev-factory-overlay-only]]);
+  // skills/procedures still resolve off the plain repo root.
+  const root = explicitRoot ?? repoRoot();
+  const seatRoot = explicitRoot ?? ambientOverlayRoot();
+  const seatLine = seatRoot ? buildSeatContext(seatRoot) : null;
   const specsRoot = typeof vaultRoot === 'string' && vaultRoot.length > 0 ? vaultRoot : root;
 
   let seat = null;
-  if (seatId) {
+  if (seatId && seatRoot) {
     try {
       // Reuse the exact seats.json dev-factory/lib/seat-context.mjs already reads — no
       // second parse-and-guess of the registry shape here.
-      const seatsPath = path.join(root, 'dev-factory', 'seats.json');
+      const seatsPath = path.join(seatRoot, 'dev-factory', 'seats.json');
       const registry = JSON.parse(readFileSync(seatsPath, 'utf8'));
       const seats = Array.isArray(registry?.seats) ? registry.seats : [];
       seat = seats.find((s) => s && s.id === seatId) ?? null;

package/spexharness/src/session-bootstrap.mjs

@@ -148,8 +148,10 @@ function resolveIntent(explicitIntent, seat) {
  * Default seat-context loader: spexharness/src/seat-context.mjs's loadSeatContext, which is
  * itself the shared dev-factory builder. Not reimplemented, and called exactly once.
  */
-function defaultSeatContextLoader({ root, seatId, vaultRoot }) {
-  return loadSeatContext({ root, seatId, vaultRoot });
+function defaultSeatContextLoader({ root, rootExplicit = true, seatId, vaultRoot }) {
+  // A defaulted root goes through the dev-factory overlay gate (HS-R475): pass no root so
+  // loadSeatContext resolves the ambient one and reads seats.json only where the gate is open.
+  return loadSeatContext(rootExplicit ? { root, seatId, vaultRoot } : { seatId, vaultRoot });
 }
 
 /**
@@ -398,6 +400,7 @@ const DEFAULT_LOADERS = Object.freeze({
  * }}
  */
 export function createSessionBootstrap(options = {}) {
+  const rootExplicit = options.root !== undefined && options.root !== null;
   const {
     root = repoRoot(),
     vaultRoot = null,
@@ -432,7 +435,7 @@ export function createSessionBootstrap(options = {}) {
   }
 
   async function loadOnce() {
-    const base = { root, vaultRoot, seatId, sessionId: resolvedSessionId, front, wipLanePath, intentProcedures };
+    const base = { root, rootExplicit, vaultRoot, seatId, sessionId: resolvedSessionId, front, wipLanePath, intentProcedures };
 
     // Seat context first and once — the other three are derived from it rather than
     // re-reading seats.json / specs/ per piece. This is the "arrives three ways" fix.

package/vendor/heyspex-mcp/cli.mjs

@@ -28,7 +28,7 @@ import { createInterface } from 'node:readline';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-import { formatSeatBanner } from './seat-identity.mjs';
+import { formatSeatBanner, registerDevFactoryOwnerOverlay } from './seat-identity.mjs';
 import { seatBlockForSessionSurface } from './seat-block-ledger.mjs';
 import { appendPeerPresence } from './peer-presence.mjs';
 import {
@@ -417,6 +417,11 @@ if (!RUNNING_AS_CLI && !INFO_ONLY && process.env.HEYSPEX_DISABLE_STDIO_BOOTSTRAP
     process.stderr.write?.(`[heyspex-mcp] capture-channel watcher skipped: ${err?.message ?? err}\n`);
   }
 
+  // [[HS-RA2Q-C86Z-TASK-wire-the-owner-overlay-to-the-dev]]: the owner's dev-factory fleet becomes
+  // the seat owner overlay ONLY behind the HS-9JMD gate (heyspex-app source checkout + owner account +
+  // HEYSPEX_DEV_FACTORY not 0). A customer install registers nothing and reads no dev-factory file.
+  registerDevFactoryOwnerOverlay().catch(() => {});
+
   // [[HS-TASK-UT8H]] — pin stdin to UTF-8 explicitly. readline's default on a
   // non-TTY stream is utf-8, but pinning protects against runtime changes and
   // guards against any future host that pipes through a code-page-aware shell.