heyspex 0.1.0

package/vendor/heyspex-mcp/research-type-suggest.mjs

@@ -0,0 +1,112 @@
+/**
+ * Deterministic capture `kind` → suggested research `research_type` mapping
+ * — [[HS-MVC1-EPIC-deterministic-type-assist-suggest-resear]] /
+ * [[HS-MVC1-TASK-deterministic-research-type-assist-sugge]].
+ *
+ * HS-120I ([[HS-120I-EPIC-research-type-field-the-declared-purpose]]) added
+ * the required `research_type:` field on research docs and left a deliberate
+ * seam — `resolveResearchType(providedValue, suggestedType)` in
+ * `promote-capture.mjs` — for a future kind-based suggestion. This module
+ * IS that seam's inference: a small, pure, dependency-free function so both
+ * the promotion flow (`promote-capture.mjs`) and any future validation path
+ * can import the same mapping without duplicating it.
+ *
+ * Capture `kind:` enum (6 values, locked by
+ * [[HS-DLQI-EPIC-capture-rename-migration-idea-to-capture]] Milestone A —
+ * see [[entity-model]] §capture): `idea | bug-fix | clip | reference | question |
+ * feedback`. `feedback` was added by
+ * [[HS-I5DV-EPIC-feedback-capture-type-deterministic]] ([[HS-48ZZ-TASK]]).
+ *
+ * research `research_type:` enum (5 values — see [[entity-model]] §research /
+ * `schemas/heyspex-frontmatter.schema.json`): `new-feature | enhancement |
+ * diagnose | code-audit | reference`.
+ *
+ * Mapping (deliberately NOT 1:1 — the two vocabularies overlap only at
+ * `reference`):
+ *   - `bug-fix`  → `diagnose`  (a defect capture becomes diagnose-purpose research)
+ *   - `idea`     → `new-feature` primary, `enhancement` alternative (an idea
+ *                  capture could seed either a net-new feature or an
+ *                  enhancement to something existing — BOTH are surfaced,
+ *                  never silently collapsed to one; `new-feature` is picked
+ *                  as the single value a caller writes when it must pick one)
+ *   - `reference`→ `reference`  (the one kind/type name that coincide)
+ *   - `clip`     → `reference`  (a saved excerpt is reference-purpose research)
+ *   - `question` → `reference`  (an open question has no dedicated
+ *                  research_type value; `reference` is the safe default —
+ *                  same as an unknown/unrecognized kind, below)
+ *   - `feedback` → `reference`  (feedback is not inherently research-shaped;
+ *                  `reference` is the same safe default used for
+ *                  `question`/`clip` — [[HS-48ZZ-TASK]])
+ *   - unknown/missing kind → `reference` (safe default, never throws)
+ *
+ * `code-audit` has no capture `kind` that maps to it deterministically — it
+ * is reachable only via explicit human/agent selection, never inferred here.
+ */
+
+/** The 6-value capture `kind:` enum ([[entity-model]] §capture). */
+export const CAPTURE_KIND_VALUES = [
+  'idea',
+  'bug-fix',
+  'clip',
+  'reference',
+  'question',
+  'feedback',
+];
+
+/** The 5-value research `research_type:` enum ([[entity-model]] §research). */
+export const RESEARCH_TYPE_VALUES = [
+  'new-feature',
+  'enhancement',
+  'diagnose',
+  'code-audit',
+  'reference',
+];
+
+/** Safe fallback for an unknown/missing/unmapped capture `kind`. */
+export const DEFAULT_SUGGESTED_RESEARCH_TYPE = 'reference';
+
+/**
+ * @typedef {object} ResearchTypeSuggestion
+ * @property {string} primary - the single research_type a caller should default to.
+ * @property {string[]} alternatives - other plausible research_type values for this
+ *   kind, surfaced (not silently discarded) for a future UI to offer as a choice.
+ * @property {boolean} known - true when `kind` matched a known enum value;
+ *   false when it fell through to the safe default.
+ */
+
+/** @type {Record<string, { primary: string, alternatives: string[] }>} */
+const KIND_TO_RESEARCH_TYPE = {
+  'bug-fix': { primary: 'diagnose', alternatives: [] },
+  idea: { primary: 'new-feature', alternatives: ['enhancement'] },
+  reference: { primary: 'reference', alternatives: [] },
+  clip: { primary: 'reference', alternatives: [] },
+  question: { primary: 'reference', alternatives: [] },
+  feedback: { primary: 'reference', alternatives: [] },
+};
+
+/**
+ * Full suggestion (primary + alternatives + known-ness) for a capture `kind`.
+ * Pure and deterministic: same input always yields the same output, no I/O,
+ * never throws. An unrecognized/null/undefined `kind` returns the safe
+ * default (`reference`) with `known: false` rather than throwing, so callers
+ * never need a try/catch around it.
+ * @param {unknown} kind
+ * @returns {ResearchTypeSuggestion}
+ */
+export function suggestResearchTypesForKind(kind) {
+  if (typeof kind === 'string' && Object.prototype.hasOwnProperty.call(KIND_TO_RESEARCH_TYPE, kind)) {
+    const entry = KIND_TO_RESEARCH_TYPE[kind];
+    return { primary: entry.primary, alternatives: [...entry.alternatives], known: true };
+  }
+  return { primary: DEFAULT_SUGGESTED_RESEARCH_TYPE, alternatives: [], known: false };
+}
+
+/**
+ * Convenience accessor: just the single `research_type` value a caller
+ * should pre-fill/pass as `suggestedType` to `resolveResearchType()`.
+ * @param {unknown} kind
+ * @returns {string}
+ */
+export function suggestResearchType(kind) {
+  return suggestResearchTypesForKind(kind).primary;
+}

package/vendor/heyspex-mcp/resolution-focus.mjs

@@ -0,0 +1,45 @@
+/**
+ * Resolution-on-deck — the focus PIN for `/hs-resolve`.
+ * [[HS-EPIC-RMCP-hs-resolve-mcp-tool-and-skill]] · [[HS-EPIC-RSRF-resolution-surface-api-and-pin]]
+ *
+ * UNLIKE `review-focus.mjs` (which reads/writes `.heyspex/review-focus.yaml`),
+ * the resolution pin lives in Neon (`resolution_focus_pin`, keyed by the
+ * content-derived `item_key`). The vendor MCP has no Postgres client, so it
+ * reaches the pin ONLY through console HTTP — exactly as it reaches
+ * active-claims. There is ONE pin concept: this module and the console surface
+ * both go through `POST/GET/DELETE /api/resolution/focus`, never a second
+ * yaml writer. See [[no-fallbacks-by-default]] / [[console-unreachable-is-dev-only]].
+ *
+ * Every function takes the bound `consoleFetch` (from `makeConsoleFetch` in
+ * cli.mjs) so it stays unit-testable with a stub, and returns the raw
+ * `consoleFetch` result `{ ok, status, body, url, error?, errorKind? }` — the
+ * caller decides how to surface a transport failure.
+ */
+
+const FOCUS_PATH = '/api/resolution/focus';
+
+/**
+ * Read the current resolution focus pin.
+ * @returns the consoleFetch result; on success `result.body.pin` is the pin row
+ *   (or null when nothing is pinned).
+ */
+export function loadResolutionFocus(consoleFetch) {
+  return consoleFetch(FOCUS_PATH);
+}
+
+/**
+ * Pin a resolution item by its content-derived `itemKey`. POSTs to the SAME
+ * canonical writer the console surface uses.
+ * @param {(path: string, opts?: object) => Promise<object>} consoleFetch
+ * @param {{ itemKey: string, reason?: string }} input
+ */
+export function writeResolutionFocus(consoleFetch, { itemKey, reason } = {}) {
+  const body = { item_key: itemKey };
+  if (reason) body.reason = reason;
+  return consoleFetch(FOCUS_PATH, { method: 'POST', body });
+}
+
+/** Clear the resolution focus pin (reverts the surface to the top-ranked auto-pick). */
+export function clearResolutionFocus(consoleFetch) {
+  return consoleFetch(FOCUS_PATH, { method: 'DELETE' });
+}

package/vendor/heyspex-mcp/review-focus.mjs

@@ -0,0 +1,55 @@
+/**
+ * Review-on-deck — pin file (`.heyspex/review-focus.yaml`) and `/hs-review` flow.
+ * [[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]] · [[HS-RES-CLR4-close-out-review-screen-jtbd-architecture]] §J16/J17
+ *
+ * Mirrors `.heyspex/focus.yaml` (build pipeline) and `.heyspex/research-focus.yaml`
+ * (research pipeline). Honored unconditionally when present, same semantics as
+ * [[focus-yaml-always-wins-in-hs-next]].
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { parseSimpleFocusYaml } from './capture-focus.mjs';
+
+export function reviewFocusPath(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'review-focus.yaml');
+}
+
+export function loadReviewFocus(vaultRoot) {
+  const p = reviewFocusPath(vaultRoot);
+  if (!existsSync(p)) return null;
+  try {
+    return parseSimpleFocusYaml(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeReviewFocus(vaultRoot, { specId, reason }) {
+  if (!specId) {
+    return { error: 'MISSING_SPEC_ID', message: 'spec_id is required' };
+  }
+  const dir = join(vaultRoot, '.heyspex');
+  mkdirSync(dir, { recursive: true });
+  const lines = [
+    '# HeySpex review-on-deck — MCP /hs-review ([[HS-TASK-RVDC-heyspex-review-on-deck-mcp-and-hs-review]])',
+    `spec_id: ${specId}`,
+    `pinned_at: ${new Date().toISOString()}`,
+  ];
+  if (reason) lines.push(`reason: ${JSON.stringify(reason)}`);
+  writeFileSync(reviewFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+  return { success: true };
+}
+
+export function clearReviewFocus(vaultRoot) {
+  const p = reviewFocusPath(vaultRoot);
+  if (!existsSync(p)) return { existed: false };
+  rmSync(p);
+  return { existed: true };
+}

package/vendor/heyspex-mcp/review-rollup.mjs

@@ -0,0 +1,47 @@
+/**
+ * Parent rollup classification — JS mirror of `classifyParentRollup` in
+ * `spex-console/src/lib/review-mode.ts`. Keep in sync when changing grain rules.
+ */
+
+const KIND_RANK = { task: 0, epic: 1, milestone: 2 };
+
+const REVIEW_AWAITING = new Set(['in_review', 'review_pending']);
+
+export function reviewLevelForGrain(grain) {
+  if (grain === 'milestone' || grain === 'epic' || grain === 'task') return grain;
+  return 'task';
+}
+
+export function rollupOptsFromMvpState(mvp) {
+  const mvpEnabled = mvp?.enabled === true;
+  return { reviewLevel: reviewLevelForGrain(mvpEnabled ? mvp?.review_grain : undefined) };
+}
+
+export function isBelowReviewLevel(kind, reviewLevel) {
+  return (KIND_RANK[kind] ?? 0) < (KIND_RANK[reviewLevel] ?? 0);
+}
+
+export function isUnitComplete(childStatuses) {
+  if (!childStatuses.length) return false;
+  let closed = 0;
+  let reviewed = 0;
+  let openish = 0;
+  for (const raw of childStatuses) {
+    const s = String(raw ?? '').toLowerCase();
+    if (s === 'closed') closed++;
+    else if (REVIEW_AWAITING.has(s)) reviewed++;
+    else if (s === 'open' || s === 'in_progress') openish++;
+  }
+  if (closed === childStatuses.length) return true;
+  return openish === 0 && reviewed > 0;
+}
+
+export function classifyParentRollup(childStatuses, childKind, reviewLevel) {
+  if (isBelowReviewLevel(childKind, reviewLevel) && isUnitComplete(childStatuses)) {
+    return 'ready_for_close';
+  }
+  const hasAwaiting = childStatuses.some((s) =>
+    REVIEW_AWAITING.has(String(s ?? '').toLowerCase()),
+  );
+  return hasAwaiting ? 'reviewer_blocked' : 'ready_for_close';
+}

package/vendor/heyspex-mcp/run-front.mjs

@@ -0,0 +1,60 @@
+/**
+ * What's Next run-front tokens — shared by `heyspex_next_on_deck`, `hs next`,
+ * and slash-command parsers. Canonical values match the console `RunFront` type.
+ *
+ * @see [[whats-next-fronts-launch-grain]] · spex-console/src/hooks/use-run-front.ts
+ */
+
+/** @typedef {'handheld' | 'assisted' | 'autonomous'} RunFront */
+
+export const RUN_FRONTS = /** @type {const} */ (['handheld', 'assisted', 'autonomous']);
+
+/** @type {Record<string, RunFront>} */
+const FRONT_ALIASES = {
+  // Handheld — default /hs-next path (human in the loop, one task at a time).
+  handheld: 'handheld',
+  'hand-held': 'handheld',
+  // Assisted — dispatcher pauses at gates (human on the loop).
+  assisted: 'assisted',
+  assist: 'assisted',
+  // Autonomous — unattended dispatcher run (human over the loop).
+  autonomous: 'autonomous',
+  auto: 'autonomous',
+};
+
+/**
+ * Normalize a user-facing front token to a canonical `RunFront`.
+ * @param {string | undefined | null} token
+ * @returns {RunFront | null}
+ */
+export function normalizeRunFrontToken(token) {
+  if (token == null || token === '') return null;
+  const key = String(token).trim().toLowerCase();
+  return FRONT_ALIASES[key] ?? null;
+}
+
+/**
+ * @param {string | undefined | null} token
+ * @returns {boolean}
+ */
+export function isRunFrontToken(token) {
+  return normalizeRunFrontToken(token) != null;
+}
+
+/** @returns {string} */
+export function runFrontCliHint() {
+  return 'handheld (default) | assist | auto';
+}
+
+/**
+ * Whether `/hs-next` should skip the yes/proceed/confirm handshake and claim
+ * immediately. True for autonomous front (`/hs-next auto`, `/hs-next-auto`) and
+ * for explicit `auto_claim` (console launch injection / `--auto-claim` flag).
+ *
+ * @param {Record<string, unknown>} [args]
+ * @returns {boolean}
+ */
+export function shouldAutoClaimOnDeck(args = {}) {
+  if (args.auto_claim === true || args.auto_claim === 'true') return true;
+  return normalizeRunFrontToken(args.front) === 'autonomous';
+}