heyspex 0.1.0 → 0.2.0

package/spexharness/src/gates/deep-research-cost-gate.mjs

@@ -0,0 +1,274 @@
+// spexharness/src/gates/deep-research-cost-gate.mjs
+//
+// Engine port of scripts/claude-hooks/deep-research-cost-gate.mjs — the
+// PreToolUse cost-confirmation + grounding gate over a Workflow/Skill call
+// that launches deep-research (HS-BLH1 grounding extension, epic HS-7HR9).
+// See ./PORTING.md for the general recipe this follows.
+//
+// JUDGMENT CALL — bigger than git-stash-gate.mjs's, read before touching
+// this file: the original script exports NOTHING — no pure decision
+// function, not even its `COST` table or its regex matchers. Its entire
+// decision (inlineScriptTarget / resolveTarget / groundingBlock /
+// isGroundOnlyResearchLaunch / the COST table) is private to the module and
+// tangled with `main()`'s stdin read, stdout write and exit. PORTING.md's
+// step-1 default remedy — extract a pure function INSIDE the original — is
+// exactly what this porting task's own brief forbids for this pass ("do NOT
+// delete or edit anything under scripts/claude-hooks/ ... shells come
+// later"). So, unlike the reference port and unlike git-stash-gate.mjs's
+// port (which could reuse several already-exported primitives), THIS module
+// re-derives the original's decision logic by hand — copied verbatim where
+// the original's own strings/tables are copyable (the COST table, the
+// deny/ask message templates, the grounding-artifact field list), so
+// today's golden fixtures still match. The one real import is
+// `loadResearchFocus` (vendor/heyspex-mcp/research-focus.mjs), which WAS
+// already exported and pure — reused, not re-derived. If the original
+// script is ever changed to export its logic (the "shells come later" plan
+// this brief refers to), this module's private copies should be deleted in
+// favor of importing the real thing — until then, a change to the
+// original's regexes/COST table needs a matching edit here, and vice versa;
+// there is no structural drift-proofing possible while the original stays
+// unexported.
+//
+// Event mapping: PreToolUse (Workflow|Skill) → before_tool.
+// Decision mapping: allow stays allow; the inline-script backstop's `deny`
+// stays `deny`; the grounding block's `deny` stays `deny`; the cost
+// confirmation's `ask` is carried forward as a `rewrite` envelope
+// (`{ ask: true, reason }`) — the same mapping env-vault-guard.mjs's
+// reference port uses for its own `ask` case, since the engine has no
+// synchronous-approval primitive.
+//
+// Env hatches (unchanged): HEYSPEX_DEEP_RESEARCH_GATE_OFF=1 (mutes the whole
+// gate), HEYSPEX_RESEARCH_GROUNDING_GATE_OFF=1 (mutes only the grounding
+// check — the cost ask still fires).
+//
+// `ctx` contract (all optional):
+//   ctx.env                        - env var overrides (falls back to
+//                                     process.env).
+//   ctx.cwd                        - vault root to resolve the
+//                                     research-focus pin and grounding
+//                                     artifact from. Defaults to
+//                                     CLAUDE_PROJECT_DIR, else this repo's
+//                                     root.
+//   ctx.loadResearchFocus(root)    - override for the research-focus
+//                                     reader. Defaults to the real
+//                                     loadResearchFocus.
+//   ctx.readGroundingArtifact(root) - override for the grounding-artifact
+//                                     reader. Tests inject fakes here
+//                                     instead of touching disk.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadResearchFocus } from '../../../vendor/heyspex-mcp/research-focus.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+
+// Copied verbatim from the original (private consts there) — see the
+// judgment-call note above.
+const GROUNDING_ARTIFACT_REL = path.join('.heyspex', 'research-grounding.json');
+const GROUNDING_FIELDS = ['already_built', 'already_decided', 'owner_reference', 'residual_delta'];
+
+const COST = {
+  'deep-research': {
+    agents: '~97',
+    label: 'the BUILT-IN deep-research',
+    extra:
+      ' This is the EXPENSIVE built-in harness and it RATE-LIMITS. Strongly prefer a HeySpex bounded profile instead: deep-research-thorough (~31 agents) or deep-research-quick (~19 agents).',
+  },
+  'deep-research-thorough': {
+    agents: '~31',
+    label: 'deep-research-thorough (HeySpex bounded, 3-vote)',
+    extra: '',
+  },
+  'deep-research-medium': {
+    agents: '~24',
+    label: 'deep-research-medium (HeySpex bounded, 2-vote)',
+    extra: '',
+  },
+  'deep-research-quick': {
+    agents: '~19',
+    label: 'deep-research-quick (HeySpex bounded, single-vote)',
+    extra: '',
+  },
+};
+
+// Detect the recurring broken launch: a hand-authored inline `script` (often
+// with a `title` like "dynamic workflow: deep-research-thorough") that does
+// not lead with `export const meta` → the harness rejects it. We only trip
+// when there is NO `name`/`scriptPath` (the correct paths) but an inline
+// `script`/`title` clearly targets a deep-research profile. Copied verbatim
+// from the original — see the judgment-call note above.
+function inlineScriptTarget(input) {
+  if (typeof input.name === 'string' || typeof input.scriptPath === 'string') return null;
+  const hay = `${typeof input.script === 'string' ? input.script : ''}\n${typeof input.title === 'string' ? input.title : ''}`;
+  if (!hay.trim()) return null;
+  if (/deep-research-thorough/.test(hay)) return 'deep-research-thorough';
+  if (/deep-research-medium/.test(hay)) return 'deep-research-medium';
+  if (/deep-research-quick/.test(hay)) return 'deep-research-quick';
+  if (/deep-research/.test(hay)) return 'deep-research-thorough'; // steer built-in/unmapped to the bounded default
+  return null;
+}
+
+// Resolve which deep-research target a Workflow/Skill call refers to, or
+// null. Copied verbatim from the original.
+function resolveTarget(toolName, input) {
+  const candidates = [];
+  if (toolName === 'Workflow') {
+    if (typeof input.name === 'string') candidates.push(input.name);
+    if (typeof input.scriptPath === 'string') candidates.push(input.scriptPath);
+  } else if (toolName === 'Skill') {
+    if (typeof input.skill === 'string') candidates.push(input.skill);
+  }
+  for (const c of candidates) {
+    if (Object.prototype.hasOwnProperty.call(COST, c)) return c;
+  }
+  for (const c of candidates) {
+    if (/deep-research-thorough/.test(c)) return 'deep-research-thorough';
+    if (/deep-research-medium/.test(c)) return 'deep-research-medium';
+    if (/deep-research-quick/.test(c)) return 'deep-research-quick';
+    if (/deep-research/.test(c)) return 'deep-research';
+  }
+  return null;
+}
+
+// `/hs-res` spends no Anthropic tokens (so no cost ask), but IS still a full
+// external research pass and must still be grounded. Copied verbatim from
+// the original.
+function isGroundOnlyResearchLaunch(toolName, input) {
+  if (toolName !== 'Skill') return false;
+  return typeof input.skill === 'string' && /^hs-res$/i.test(input.skill.trim());
+}
+
+function defaultReadGroundingArtifact(root) {
+  try {
+    const full = path.join(root, GROUNDING_ARTIFACT_REL);
+    if (!fs.existsSync(full)) return null;
+    return JSON.parse(fs.readFileSync(full, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Returns a deny-reason string when a promotion-driven deep-research launch
+// is NOT grounded, else null (allow). Copied verbatim from the original
+// (parameterized on `root`/`deps` instead of calling repoRoot() and the
+// module-level readers directly, so ctx can override both for tests).
+function groundingBlock(root, deps) {
+  let focus;
+  try {
+    focus = deps.loadResearchFocus(root);
+  } catch {
+    return null; // discovery failure → fail open
+  }
+  const sourceIdeaId = focus?.source_idea_id;
+  if (!sourceIdeaId) return null; // no promotion pin → not gated
+
+  const artifact = deps.readGroundingArtifact(root);
+  const grounded =
+    artifact &&
+    typeof artifact === 'object' &&
+    artifact.source_idea_id === sourceIdeaId &&
+    GROUNDING_FIELDS.every((k) => typeof artifact[k] === 'string' && artifact[k].trim());
+  if (grounded) return null;
+
+  const why = !artifact
+    ? 'no grounding artifact was found'
+    : artifact.source_idea_id !== sourceIdeaId
+      ? `the grounding artifact is for a different idea (${artifact.source_idea_id ?? 'unknown'})`
+      : 'the grounding artifact is missing already_built / already_decided / owner_reference / residual_delta';
+  return (
+    `Deep-research launch blocked: this is a promotion-driven research run for ${sourceIdeaId}, but ${why}. ` +
+    `Ground FIRST so you research only the residual unknown, not work that already ships or is already decided ` +
+    `(the HS-VDPB → HS-LKCO burn re-derived companion features that already exist). Do both routes:\n` +
+    `  route-1 (plans): heyspex_recall_memories + /hs-ground on the idea.\n` +
+    `  route-2 (code): check companion/ · spex-console/ · scripts/ · the \`hs\` CLI, PLUS the feature's use case / roadmap / open tasks.\n` +
+    `  route-3 (owner's working reference): does the owner ALREADY RUN something that does this — a service, container, script, or tool on their own machine? Inspect it and record what it showed. This is the cheapest and highest-authority evidence there is.\n` +
+    `Then record the result to ${GROUNDING_ARTIFACT_REL} as ` +
+    `{ "source_idea_id": "${sourceIdeaId}", "already_built": "...", "already_decided": "...", "owner_reference": "...", "residual_delta": "...", "recorded_at": "<ISO>" } ` +
+    `and relaunch with the RESIDUAL DELTA as the question. If grounding shows it is already built/decided, do NOT launch — record and stop. ` +
+    `(Break-glass: set HEYSPEX_RESEARCH_GROUNDING_GATE_OFF=1.)`
+  );
+}
+
+/** The deep-research cost/grounding gate's id — unique across the built-in registry. */
+export const id = 'deep-research-cost-gate';
+/** Runs pre-tool, same as its PreToolUse Claude Code hook registration. */
+export const event = 'before_tool';
+/** Caller-defined severity label; this gate can deny, so it is "block". */
+export const severity = 'block';
+
+/**
+ * @param {{ point: string, toolName?: string, toolInput?: Record<string, unknown> }} evt
+ * @param {{ cwd?: string, loadResearchFocus?: (root: string) => object | null,
+ *            readGroundingArtifact?: (root: string) => object | null,
+ *            env?: Record<string, string | undefined> }} [ctx]
+ * @returns {{ decision: 'allow'|'deny'|'rewrite', reason?: string, rewrite?: object }}
+ */
+export function run(evt, ctx = {}) {
+  const env = ctx.env ?? process.env;
+  if (String(env.HEYSPEX_DEEP_RESEARCH_GATE_OFF ?? '') === '1') {
+    return { decision: 'allow' };
+  }
+
+  const toolName = evt?.toolName;
+  if (toolName !== 'Workflow' && toolName !== 'Skill') {
+    return { decision: 'allow' };
+  }
+
+  const input = evt?.toolInput ?? {};
+  const root = ctx.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? REPO_ROOT;
+  const deps = {
+    loadResearchFocus: ctx.loadResearchFocus ?? loadResearchFocus,
+    readGroundingArtifact: ctx.readGroundingArtifact ?? defaultReadGroundingArtifact,
+  };
+
+  // Backstop: a hand-authored inline-script deep-research launch (no
+  // name/scriptPath) would fail the harness's own validator. Deny it with
+  // the exact corrective so the caller relaunches by scriptPath instead.
+  if (toolName === 'Workflow') {
+    const inlineProfile = inlineScriptTarget(input);
+    if (inlineProfile) {
+      return {
+        decision: 'deny',
+        reason:
+          `Don't hand-author an inline deep-research workflow script — that trips the ` +
+          `"export const meta must be the FIRST statement" validator (the recurring ` +
+          `"dynamic workflow: ${inlineProfile}" launch error). Relaunch it via scriptPath so the ` +
+          `validated file loads: Workflow({ scriptPath: '.claude/workflows/${inlineProfile}.js', args: '<the research question>' }). ` +
+          `Do NOT use the Workflow \`name\` parameter (its loader trips the same validator) and do NOT invoke it via the Skill tool.`,
+      };
+    }
+  }
+
+  const target = resolveTarget(toolName, input);
+  const groundingOff = String(env.HEYSPEX_RESEARCH_GROUNDING_GATE_OFF ?? '') === '1';
+
+  // Grounding applies to every external research pass, including the
+  // zero-cost /hs-res path — which is grounded but never cost-asked.
+  if (!target) {
+    if (isGroundOnlyResearchLaunch(toolName, input) && !groundingOff) {
+      const groundingDeny = groundingBlock(root, deps);
+      if (groundingDeny) return { decision: 'deny', reason: groundingDeny };
+    }
+    return { decision: 'allow' }; // not a cost-bearing deep-research invocation
+  }
+
+  // Grounding gate: a promotion-driven deep-research launch must be grounded
+  // first. Runs before the cost ask so an ungrounded launch is denied, not
+  // merely cost-confirmed. Muted independently of the cost gate.
+  if (!groundingOff) {
+    const groundingDeny = groundingBlock(root, deps);
+    if (groundingDeny) return { decision: 'deny', reason: groundingDeny };
+  }
+
+  const c = COST[target];
+  const reason =
+    `Deep-research about to run: ${c.label} — ${c.agents} agent calls ` +
+    `(fan-out web search → fetch → adversarially verify → synthesize).${c.extra} ` +
+    `Approve to spend those tokens, or cancel and choose the cheaper profile.`;
+  return { decision: 'rewrite', reason, rewrite: { ask: true, reason } };
+}
+
+export default { id, event, severity, run };