heyspex 0.1.0

package/vendor/heyspex-mcp/capture-kind-suggest.mjs

@@ -0,0 +1,121 @@
+/**
+ * Lexical capture-content → suggested `kind` classifier — [[HS-QOBQ-S4JZ-DIAG-capture-kind-is-never-classified-every]].
+ *
+ * Every capture materializes at `kind: idea` (the schema default) and nothing
+ * ever inspected the content to check whether that default is right. This is
+ * the cheapest possible rung (regex/lexical, no model call) for the two call
+ * sites the diagnose named:
+ *   1. Capture time — `scripts/claude-hooks/_intent-classifier-router.mjs`
+ *      (already running on every UserPromptSubmit) appends a "this reads
+ *      like <kind>" hint to the capture-on-idea directive.
+ *   2. Promote time — `promote-capture.mjs`'s proposal phase re-checks the
+ *      capture's stored `kind:` against this same guess and surfaces a
+ *      mismatch instead of silently promoting a miskinded capture.
+ *
+ * Deliberately suggest-only ([[HS-5HYS-elicitation]]: suggest, never
+ * auto-apply) — nothing here writes frontmatter. Pure, dependency-free,
+ * never throws; an unrecognized/ambiguous body returns `kind: null` (no
+ * suggestion — leave the existing/default kind alone).
+ *
+ * Kept intentionally narrow: bug-fix is the strong, well-evidenced lexical
+ * signal the diagnose calls out ("error, stacktrace, broken, regression,
+ * 'this is itself a bug'"). clip/question are cheap, low-risk bonus signals
+ * (a bare URL body; a single trailing-`?` sentence). reference/feedback have
+ * no reliable lexical tell and are left to agent judgment, same as today.
+ */
+
+import { fileURLToPath } from 'node:url';
+
+/** Bug-report language — the diagnose's own named signal set, plus common
+ *  JS/TS runtime-error shapes so a pasted stack trace is caught too. */
+const BUG_FIX_RE =
+  /\b(stack ?trace|traceback|regression|silently (?:fails?|broke|breaks?)|doesn'?t work|does not work|no longer works|fails? to|null pointer|undefined is not a function|cannot read propert(?:y|ies) of (?:null|undefined)|this is (?:itself )?a bug|reproduc(?:e|es|ed|ible)|(?:type|reference|syntax)error\b|unhandled exception|threw an exception)\b/i;
+// "error"/"exception"/"broken"/"crash" alone are common in non-bug prose
+// ("error handling", "crash course") — require them paired with another
+// defect-shaped word, OR appearing next to code-ish punctuation (a stack
+// frame / file:line / exception class), to keep the false-positive rate low.
+const BUG_FIX_WEAK_RE = /\b(error|exception|broken|crash(?:es|ed|ing)?|bug)\b/i;
+const CODE_SHAPE_RE = /(\bat\s+\S+\(.*:\d+:\d+\)|\.(?:mjs|ts|tsx|js|jsx|cs|py):\d+|Traceback \(most recent call last\)|Exception in thread)/;
+
+/** A body that is essentially just a link — nothing to synthesize, just save it. */
+const URL_ONLY_RE = /^\s*<?(https?:\/\/\S+)>?\s*$/i;
+
+/** A single short question — no other substantive paragraph. */
+const QUESTION_ONLY_RE = /^\s*(?:why|how|what|when|where|who|which|should|is|are|does|do|can)\b[^\n]{0,240}\?\s*$/i;
+
+/**
+ * @param {string|null|undefined} text — the capture body (frontmatter stripped).
+ * @returns {{ kind: 'bug-fix'|'clip'|'question'|null, matched: string|null }}
+ */
+export function guessCaptureKindFromText(text) {
+  const body = typeof text === 'string' ? text.trim() : '';
+  if (!body) return { kind: null, matched: null };
+
+  const bugMatch = body.match(BUG_FIX_RE);
+  if (bugMatch) return { kind: 'bug-fix', matched: bugMatch[0] };
+  if (BUG_FIX_WEAK_RE.test(body) && CODE_SHAPE_RE.test(body)) {
+    const weak = body.match(BUG_FIX_WEAK_RE);
+    return { kind: 'bug-fix', matched: weak ? weak[0] : 'error-shaped content' };
+  }
+
+  if (URL_ONLY_RE.test(body)) return { kind: 'clip', matched: body.match(URL_ONLY_RE)[1] };
+
+  if (QUESTION_ONLY_RE.test(body) && !body.includes('\n\n')) {
+    return { kind: 'question', matched: body.slice(0, 80) };
+  }
+
+  return { kind: null, matched: null };
+}
+
+/**
+ * Compare a stored `kind:` against the content-implied guess.
+ * @param {unknown} storedKind
+ * @param {string|null|undefined} bodyText
+ * @returns {{ mismatch: boolean, storedKind: string|null, suggestedKind: string|null, matched: string|null }}
+ */
+export function checkCaptureKindMismatch(storedKind, bodyText) {
+  const normalizedStored = typeof storedKind === 'string' && storedKind ? storedKind : 'idea';
+  const guess = guessCaptureKindFromText(bodyText);
+  const mismatch = guess.kind !== null && guess.kind !== normalizedStored;
+  return { mismatch, storedKind: normalizedStored, suggestedKind: guess.kind, matched: guess.matched };
+}
+
+async function runSelfTest() {
+  let ok = true;
+  const check = (name, cond) => {
+    console.log(`  ${cond ? '✓' : '✗'} ${name}`);
+    if (!cond) ok = false;
+  };
+  console.log('== capture-kind-suggest.mjs self-test ==\n');
+
+  check(
+    'bug language → bug-fix',
+    guessCaptureKindFromText('Getting a TypeError: cannot read property of undefined when I load the page, this is a bug.').kind === 'bug-fix',
+  );
+  check(
+    'stacktrace-shaped body → bug-fix',
+    guessCaptureKindFromText('It crashes.\n  at handleClick (app.tsx:42:10)\n  at onClick (app.tsx:12:3)').kind === 'bug-fix',
+  );
+  check('bare URL body → clip', guessCaptureKindFromText('https://example.com/some/article').kind === 'clip');
+  check('single question → question', guessCaptureKindFromText('How does the claim lease renewal actually work?').kind === 'question');
+  check('plain idea prose → null (no suggestion)', guessCaptureKindFromText('It would be nice if the dashboard showed a sparkline here.').kind === null);
+  check('empty body → null', guessCaptureKindFromText('').kind === null);
+  check('"error handling" alone (no code shape) → null, not a false-positive bug-fix', guessCaptureKindFromText('We should improve error handling in the settings form.').kind === null);
+
+  const mismatch = checkCaptureKindMismatch('idea', 'TypeError: x is not a function — this is itself a bug, reproducible every time.');
+  check('mismatch detection: idea + bug body → mismatch true, suggestedKind bug-fix', mismatch.mismatch === true && mismatch.suggestedKind === 'bug-fix');
+  const noMismatch = checkCaptureKindMismatch('bug-fix', 'TypeError: x is not a function.');
+  check('no mismatch when stored kind already matches', noMismatch.mismatch === false);
+
+  console.log(`\n${ok ? '✓ self-test PASS' : '✗ self-test FAIL'}`);
+  return ok ? 0 : 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runSelfTest()
+    .then((code) => process.exit(code))
+    .catch((e) => {
+      console.error(e);
+      process.exit(1);
+    });
+}

package/vendor/heyspex-mcp/capture-outbox.mjs

@@ -0,0 +1,239 @@
+/**
+ * Capture offline buffer — loss-proof scratch for when console/Neon is unreachable.
+ *
+ * Per [[heyspex-is-online-only-no-offline]]: capture is online-only. When the
+ * console API is unreachable the MCP capture tools REFUSE (hard error) instead of
+ * silently minting a divergent file scaffold + pin (the [[HS-CAP-SID6]] zombie
+ * source — see [[capture-pin-had-no-clear-logic]]). But the user's loss-aversion
+ * is non-negotiable ("capture must always work"), so the verbatim input is stashed
+ * here as plain text and drained into Neon automatically on reconnect.
+ *
+ * This is NOT control-plane state and does NOT violate [[control-plane-belongs-in-neon]]:
+ * - It is write-only and transient — never read AS state by /hs-next, the
+ *   supervisor, or any tool. It is a dumb buffer of raw user words.
+ * - It is never a pin, never a `capture_sessions` row, never source of truth.
+ * - It is the exact "thoughts written into a notes file, captured on reconnect"
+ *   escape hatch the online-only decision blesses — just automated.
+ * The decision's bar for a new `.heyspex/*` file is "Neon is genuinely unavailable
+ * for this case" — which is literally this case.
+ *
+ * Layout: `.heyspex/capture-outbox/<ISO>__<NN>__<kind>.txt`, one file per stashed
+ * field. The body is the verbatim words (human-readable: open the file = your
+ * words). Metadata lives in the filename so the file stays plain text.
+ */
+
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  renameSync,
+  rmSync,
+} from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { buildCaptureBufferPatches } from './capture-buffer-patches.mjs';
+
+/**
+ * Capture args that carry content worth preserving, in chronological write order.
+ * Covers EVERY content-bearing `heyspex_update_capture` argument ([[HS-K27H-DIAG-0G86]]
+ * AC4: the "your exact words are saved" message may only be shown when the words
+ * really are in the outbox — before this list included example/user_stories/kind/
+ * done_when, those args were silently dropped while the message claimed otherwise).
+ */
+export const OUTBOX_KINDS = [
+  'user_quote',
+  'agent_note',
+  'core_idea',
+  'summary',
+  'concept',
+  'agent_expansion',
+  'example',
+  'user_stories',
+  'kind',
+  'done_when',
+];
+
+/**
+ * Process-monotonic sequence, zero-padded into the filename as the within-
+ * millisecond tiebreaker. The ISO timestamp alone collides when two stashes land
+ * in the same ms — without this, lexical sort would fall through to `kind` and
+ * reorder entries (e.g. core_idea before an earlier user_quote). Sort key is
+ * therefore (timestamp, seq) = strict creation order.
+ */
+let stashSeq = 0;
+
+export function captureOutboxDir(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'capture-outbox');
+}
+
+/**
+ * Directory for entries that cannot self-heal — moved here by `quarantineOutboxEntry`
+ * when the console structurally refuses them (HTTP 4xx). Kept for audit / debugging;
+ * never replayed automatically. The active outbox can always drain because 4xx
+ * entries no longer head-of-line-block it ([[HS-EPIC-CPMR]]).
+ */
+export function captureOutboxQuarantineDir(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'capture-outbox', 'quarantine');
+}
+
+/**
+ * Stash the content-bearing fields of a capture-update args object as plaintext,
+ * one file per field. Returns the written entries (empty array if nothing to stash).
+ */
+export function stashCaptureArgs(vaultRoot, args = {}) {
+  const entries = [];
+  for (const kind of OUTBOX_KINDS) {
+    const raw = args[kind];
+    if (raw !== undefined && String(raw).trim()) {
+      entries.push({ kind, text: String(raw).trim() });
+    }
+  }
+  if (entries.length === 0) return [];
+
+  const dir = captureOutboxDir(vaultRoot);
+  mkdirSync(dir, { recursive: true });
+  const stampBase = new Date().toISOString().replace(/[:.]/g, '-');
+  const written = [];
+  for (const e of entries) {
+    const seq = String(stashSeq++).padStart(6, '0');
+    const fname = `${stampBase}__${seq}__${e.kind}.txt`;
+    const path = join(dir, fname);
+    writeFileSync(path, `${e.text}\n`, 'utf8');
+    written.push({ ...e, path, file: fname });
+  }
+  return written;
+}
+
+/** List stashed entries oldest-first (filenames sort chronologically). */
+export function listOutbox(vaultRoot) {
+  const dir = captureOutboxDir(vaultRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith('.txt'))
+    .map((d) => d.name)
+    .sort()
+    .map((f) => {
+      const m = f.match(/__\d+__([a-z_]+)\.txt$/);
+      const kind = m ? m[1] : 'user_quote';
+      let text = '';
+      try {
+        text = readFileSync(join(dir, f), 'utf8').replace(/\n+$/, '');
+      } catch {
+        /* skip unreadable */
+      }
+      return { file: f, path: join(dir, f), kind, text };
+    })
+    .filter((e) => e.text.length > 0);
+}
+
+export function outboxCount(vaultRoot) {
+  return listOutbox(vaultRoot).length;
+}
+
+/** Remove a stashed entry after it has been durably filed to Neon. */
+export function removeOutboxEntry(path) {
+  try {
+    rmSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Quarantine a stashed entry that the console structurally refused (HTTP 4xx).
+ * Moves the file to `.heyspex/capture-outbox/quarantine/` and writes a
+ * sidecar `<name>.reason.json` with `{ reason, status, consoleMessage,
+ * quarantined_at }` for post-hoc inspection. Returns true on success.
+ *
+ * Per [[HS-EPIC-CPMR]] — the active outbox is for transient retry-worthy
+ * failures only. 4xx-class responses will fail identically on retry, so they
+ * don't belong there. Removing them (vs. discarding) keeps an audit trail
+ * without head-of-line-blocking the queue.
+ */
+export function quarantineOutboxEntry(vaultRoot, entryPath, metadata = {}) {
+  try {
+    const qdir = captureOutboxQuarantineDir(vaultRoot);
+    mkdirSync(qdir, { recursive: true });
+    const name = basename(entryPath);
+    const dest = join(qdir, name);
+    renameSync(entryPath, dest);
+    const sidecarPath = join(qdir, `${name}.reason.json`);
+    const sidecar = {
+      reason: metadata.reason || 'console_refused',
+      status: metadata.status ?? null,
+      consoleMessage: metadata.consoleMessage ?? null,
+      quarantined_at: new Date().toISOString(),
+    };
+    writeFileSync(sidecarPath, `${JSON.stringify(sidecar, null, 2)}\n`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List quarantined entries oldest-first. Read-only — used for inspection /
+ * debugging, never auto-replayed.
+ */
+export function listQuarantinedOutbox(vaultRoot) {
+  const dir = captureOutboxQuarantineDir(vaultRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith('.txt'))
+    .map((d) => d.name)
+    .sort()
+    .map((f) => {
+      const m = f.match(/__\d+__([a-z_]+)\.txt$/);
+      const kind = m ? m[1] : 'user_quote';
+      let text = '';
+      try {
+        text = readFileSync(join(dir, f), 'utf8').replace(/\n+$/, '');
+      } catch {
+        /* skip unreadable */
+      }
+      let reason = null;
+      try {
+        const raw = readFileSync(join(dir, `${f}.reason.json`), 'utf8');
+        reason = JSON.parse(raw);
+      } catch {
+        /* sidecar may be absent */
+      }
+      return { file: f, path: join(dir, f), kind, text, reason };
+    });
+}
+
+export function quarantineCount(vaultRoot) {
+  return listQuarantinedOutbox(vaultRoot).length;
+}
+
+/**
+ * Map a stashed entry to the `capture_sessions` PATCH it should replay on
+ * reconnect. Delegates to `buildCaptureBufferPatches` — the SAME builder the
+ * live `heyspex_update_capture` path uses — so a drained entry is genuinely
+ * indistinguishable from one filed live: canonical STRUCTURED shapes
+ * (userQuotes: Array<{at,text}>, coreIdea/summary/details/example/userStories/
+ * doneWhen: {at,text,confirmed}), camelCase paths.
+ *
+ * Pre-[[HS-K27H-DIAG-0G86]] this hand-rolled FLAT string patches
+ * (`user_quotes: "- **iso · you:** …"`, `core_idea: "text"`) — the exact
+ * legacy shapes every downstream reader rejects ([[HS-EPIC-CPMR]]), so the
+ * "will sync automatically" promise replayed content into a form that never
+ * rendered. That is AC4's "drain path capable of replaying it" violation.
+ *
+ * @param {object} entry - { kind, text } from listOutbox.
+ * @param {string} iso - timestamp to stamp on the replayed entry.
+ * @param {object} [currentBuffer] - the session's current content_buffer, so
+ *   append-shaped sections (userQuotes/chatTurns) merge instead of clobbering.
+ *   The drain loop threads its locally-merged buffer through here.
+ * @returns {{path: string, value: unknown} | null}
+ */
+export function outboxEntryToPatch(entry, iso, currentBuffer = {}) {
+  const text = String(entry.text ?? '').trim();
+  if (!text) return null;
+  if (!OUTBOX_KINDS.includes(entry.kind)) return null;
+  const patches = buildCaptureBufferPatches({ [entry.kind]: text }, currentBuffer, iso);
+  return patches[0] ?? null;
+}

package/vendor/heyspex-mcp/capture-stage-gate.mjs

@@ -0,0 +1,160 @@
+/**
+ * The capture-stage rule: an open capture must not be turned into an epic, task
+ * or milestone. Its sanctioned exit is promote-to-research.
+ *
+ * WHY THIS LIVES IN THE TOOL AND NOT ONLY IN A HOOK
+ *
+ * The rule shipped first as a Claude Code PreToolUse hook
+ * (scripts/claude-hooks/capture-workflow-gate.mjs). That hook was registered,
+ * built, and marked done, and it never once refused anything, for three separate
+ * reasons stacked on top of each other:
+ *
+ *   1. It returned early unless `CLAUDE_AGENT === 'true'`, which interactive
+ *      Claude Code sessions do not set. Silent in every session a human reads.
+ *   2. Worse, and independent of 1: it resolved the capture-on-deck pin from
+ *      `.heyspex/capture-focus.yaml`. That pin moved to the Neon control plane —
+ *      `/hs-capture` writes it there and only falls back to the file when the
+ *      console is unreachable. The file kept a June pin whose capture was already
+ *      promoted, so the lookup returned CAPTURE_RETIRED and the gate allowed
+ *      everything, in unattended sessions too. A hook cannot fix this: hooks are
+ *      dependency-free by design and have no database access.
+ *   3. Hooks fail open, and one agent-writable file (`.heyspex/mode.json` set to
+ *      "off") disarms every one of them but the env-vault guard.
+ *
+ * The tool has none of those problems. It reads the live pin, it runs in every
+ * session, and it cannot be switched off by writing a file. Same reasoning that
+ * moved the preflight gate into the tools (preflight-gate.mjs).
+ *
+ * This module is PURE — no filesystem, no network, no env reads beyond the
+ * documented switches. Resolving which capture is on deck is the caller's job,
+ * so the decision can be tested without a console.
+ *
+ * Env:
+ *   HEYSPEX_CAPTURE_STAGE_GATE_OFF=1   Break-glass. Allows everything.
+ *   HEYSPEX_CAPTURE_STAGE_GATE=warn    Drop from refusing to a warning that
+ *                                      rides along on the successful response.
+ */
+
+/** file_spec types that are the premature-promotion case we refuse. */
+export const BLOCKED_FILE_SPEC_TYPES = new Set(['epic', 'task', 'milestone']);
+
+/**
+ * file_spec types that ARE the sanctioned capture exits, or are unrelated to the
+ * capture pipeline. Never refused.
+ */
+export const ALLOWED_FILE_SPEC_TYPES = new Set([
+  'research',
+  'diagnose',
+  'memory-lesson',
+  'memory-decision',
+  'memory-reference',
+  'memory-ui-pattern',
+  'review',
+  'pillar',
+]);
+
+/**
+ * Frontmatter fields a capture-derived spec uses to point back at its capture.
+ * Kept in sync with the hook by both importing this module.
+ */
+export const REFERENCE_FIELDS = [
+  'source',
+  'related',
+  'promoted_from',
+  'parent',
+  'informed_by',
+  'sources_captures',
+];
+
+export const CAPTURE_STAGE_GATE_OFF_ENV = 'HEYSPEX_CAPTURE_STAGE_GATE_OFF';
+export const CAPTURE_STAGE_GATE_RUNG_ENV = 'HEYSPEX_CAPTURE_STAGE_GATE';
+
+/**
+ * Does this filing point back at `captureId`?
+ *
+ * Scans the known linkage fields plus summary/body as a backstop. A wikilink
+ * like `[[HS-CAP-VDPB-some-idea]]` starts with the id, so a substring test is
+ * enough and avoids brittle wikilink parsing.
+ *
+ * Deliberately narrow, and it UNDER-matches: an agent could file an epic
+ * carrying the idea's content with no backlink at all, and nothing here would
+ * see it. That is accepted. Widening this to "a capture is open, so refuse every
+ * epic" would fire on essentially every filing for the rest of a session,
+ * because a capture's pin is permanent until it is promoted or closed.
+ */
+export function referencesCapture(toolArgs, captureId) {
+  if (!captureId) return false;
+  const fm = toolArgs?.frontmatter;
+  if (fm && typeof fm === 'object') {
+    for (const field of REFERENCE_FIELDS) {
+      const v = fm[field];
+      if (v == null) continue;
+      const hay = Array.isArray(v) ? v.join('\n') : String(v);
+      if (hay.includes(captureId)) return true;
+    }
+  }
+  for (const key of ['summary', 'body']) {
+    const v = toolArgs?.[key];
+    if (typeof v === 'string' && v.includes(captureId)) return true;
+  }
+  return false;
+}
+
+/** Which rung is the gate on? `refuse` (default) or `warn`. */
+export function captureStageRung(env = process.env) {
+  const raw = String(env?.[CAPTURE_STAGE_GATE_RUNG_ENV] ?? '').trim().toLowerCase();
+  return raw === 'warn' ? 'warn' : 'refuse';
+}
+
+export function captureStageMessage(captureId, type) {
+  return (
+    `This ${type} derives from the open capture ${captureId}, and a capture must not ` +
+    `become an epic, task or milestone. Promote it to research first — that is the ` +
+    `capture's sanctioned exit (the promote-to-research offer, or /hs-res). File ` +
+    `implementation specs later, from the research, not from the raw capture. ` +
+    `(Deliberate exception: set ${CAPTURE_STAGE_GATE_OFF_ENV}=1.)`
+  );
+}
+
+/**
+ * The decision.
+ *
+ * @param {object} input
+ * @param {object} input.toolArgs        heyspex_file_spec arguments.
+ * @param {object|null} input.activeCapture  The resolved capture on deck, or null
+ *   when nothing is genuinely open. Must carry `spec_id`. A resolver error
+ *   (retired / not found / no pin) is a null here — the caller decides that.
+ * @param {object} [input.env]
+ * @returns {{ decision: 'allow' } | { decision: 'refuse'|'warn', captureId, type, message }}
+ */
+export function decideCaptureStageGate({ toolArgs = {}, activeCapture = null, env = process.env } = {}) {
+  if (env?.[CAPTURE_STAGE_GATE_OFF_ENV] === '1') return { decision: 'allow' };
+
+  const type = String(toolArgs?.type ?? '').trim().toLowerCase();
+  if (!type) return { decision: 'allow' };
+  if (ALLOWED_FILE_SPEC_TYPES.has(type)) return { decision: 'allow' };
+  if (!BLOCKED_FILE_SPEC_TYPES.has(type)) return { decision: 'allow' };
+
+  const captureId = activeCapture?.spec_id;
+  if (!captureId) return { decision: 'allow' };
+  if (!referencesCapture(toolArgs, captureId)) return { decision: 'allow' };
+
+  return {
+    decision: captureStageRung(env),
+    captureId,
+    type,
+    message: captureStageMessage(captureId, type),
+  };
+}
+
+/** The MCP error payload for a refusal. */
+export function buildCaptureStageRefusal(verdict) {
+  return {
+    error: 'CAPTURE_STAGE_VIOLATION',
+    message: verdict.message,
+    capture_id: verdict.captureId,
+    attempted_type: verdict.type,
+    do_instead: 'Promote the capture to research (heyspex_promote_capture or /hs-res), then file from the research.',
+    break_glass: `${CAPTURE_STAGE_GATE_OFF_ENV}=1`,
+  };
+}