heyspex 0.1.0

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

@@ -0,0 +1,240 @@
+/**
+ * `heyspex_next_resolution` resolver — hands the agent the top open resolution
+ * item + a fix brief, mirroring `heyspex_next_review` for the Resolution lane.
+ * [[HS-EPIC-RMCP-hs-resolve-mcp-tool-and-skill]] · [[HS-EPIC-RSRF-resolution-surface-api-and-pin]]
+ *
+ * TRANSPORT: HTTP-only via `consoleFetch`. Resolution items are DERIVED by the
+ * console-side aggregator (the one detection path); the vendor MCP has no
+ * Postgres client and must NOT re-run a `.mjs` detector — that would reintroduce
+ * the stale/duplicate-detector problem the milestone exists to kill. Console
+ * unreachable → an honest CONSOLE_UNREACHABLE error telling the developer to
+ * start the dev server. See [[no-fallbacks-by-default]] /
+ * [[console-unreachable-is-dev-only]].
+ *
+ * Reads (never re-detects):
+ *   - GET /api/resolution/next            → server applies the Neon focus pin
+ *   - GET /api/resolution?status=open[&scope=] → ranked open list (item_key /
+ *                                           ignore_focus / deck-aware scope)
+ */
+
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+
+/** Bounded queue preview — keep the response within the MCP size budget. */
+const QUEUE_PREVIEW_LIMIT = 5;
+
+function transportError(result) {
+  return {
+    error: consoleErrorCode(result, 'RESOLUTION_FETCH_FAILED'),
+    message: consoleErrorMessage(
+      result,
+      `Resolution endpoint returned ${result.status}.`,
+    ),
+    status: result.status,
+    url: result.url,
+    console_response: result.body,
+  };
+}
+
+async function fetchOpenList(consoleFetch, scope) {
+  let path = '/api/resolution?status=open';
+  if (scope) path += `&scope=${encodeURIComponent(scope)}`;
+  return consoleFetch(path);
+}
+
+/**
+ * Resolve the next resolution item.
+ *
+ * @param {{ item_key?: string, ignore_focus?: boolean|string, scope?: string }} args
+ * @param {{ consoleFetch: Function }} deps
+ * @returns {Promise<{ result?: object, error?: object }>}
+ */
+export async function resolveNextResolutionPayload(args = {}, deps = {}) {
+  const { consoleFetch } = deps;
+  if (typeof consoleFetch !== 'function') {
+    return {
+      error: {
+        error: 'MISSING_DEPS',
+        message: 'resolveNextResolutionPayload requires deps { consoleFetch }',
+      },
+    };
+  }
+
+  const itemKey = typeof args.item_key === 'string' ? args.item_key.trim() : '';
+  const ignoreFocus = args.ignore_focus === true || args.ignore_focus === 'true';
+  const scope = typeof args.scope === 'string' ? args.scope.trim() : '';
+
+  let hero = null;
+  let queue = [];
+  let source = 'empty';
+  let openCount;
+
+  if (itemKey) {
+    // Explicit selection — find the item by key in the ranked open list.
+    const res = await fetchOpenList(consoleFetch, scope);
+    if (!res.ok) return { error: transportError(res) };
+    const items = Array.isArray(res.body?.items) ? res.body.items : [];
+    openCount = res.body?.openCount;
+    hero = items.find((i) => i.key === itemKey) || null;
+    if (!hero) {
+      return {
+        error: {
+          error: 'ITEM_NOT_FOUND',
+          message: `No open resolution item with key "${itemKey}". List it with heyspex_next_resolution (no args) or GET /api/resolution.`,
+        },
+      };
+    }
+    queue = items.filter((i) => i.key !== itemKey);
+    source = 'resolution_focus';
+  } else if (scope || ignoreFocus) {
+    // Deck-aware scope, or pin bypass — take the top-ranked open item directly.
+    const res = await fetchOpenList(consoleFetch, scope);
+    if (!res.ok) return { error: transportError(res) };
+    const items = Array.isArray(res.body?.items) ? res.body.items : [];
+    openCount = res.body?.openCount;
+    hero = items[0] || null;
+    queue = items.slice(1);
+    source = hero ? 'resolution_queue' : 'empty';
+  } else {
+    // Default — let the server apply the Neon focus pin (single pin authority).
+    const res = await consoleFetch('/api/resolution/next');
+    if (!res.ok) return { error: transportError(res) };
+    hero = res.body?.pinned || null;
+    queue = Array.isArray(res.body?.queue) ? res.body.queue : [];
+    source = res.body?.source || (hero ? 'resolution_queue' : 'empty');
+  }
+
+  if (!hero) {
+    return {
+      result: {
+        source: 'empty',
+        item: null,
+        queue_preview: [],
+        open_count: 0,
+        user_prompt_markdown: NOTHING_TO_RESOLVE_MD,
+        prompt_markdown: NOTHING_TO_RESOLVE_MD,
+        resolved_at: new Date().toISOString(),
+      },
+    };
+  }
+
+  const queuePreview = queue.slice(0, QUEUE_PREVIEW_LIMIT).map((i) => ({
+    key: i.key,
+    kind: i.kind,
+    severity: i.severity,
+    gating: i.gating,
+    title: i.title,
+  }));
+
+  const promptMarkdown = buildHsResolvePromptMarkdown({
+    item: hero,
+    source,
+    queue,
+  });
+
+  return {
+    result: {
+      source,
+      item: {
+        key: hero.key,
+        kind: hero.kind,
+        severity: hero.severity,
+        gating: hero.gating,
+        title: hero.title,
+        spec_id: hero.specId,
+        target_id: hero.targetId,
+      },
+      queue_preview: queuePreview,
+      ...(typeof openCount === 'number' ? { open_count: openCount } : {}),
+      user_prompt_markdown: promptMarkdown,
+      prompt_markdown: promptMarkdown,
+      resolved_at: new Date().toISOString(),
+    },
+  };
+}
+
+const NOTHING_TO_RESOLVE_MD = `## resolution — nothing to resolve 🎉
+
+No open resolution items in the vault. Conflicts, dangling refs, cycles,
+prerequisites, and validation issues are all clear (or already resolved /
+dismissed / deferred via the ledger).
+
+_Run \`/hs-next\` to pick up build work, or \`/hs-review\` for review-ready specs._`;
+
+function affectedLine(item) {
+  const parts = [];
+  if (item.specId) parts.push(`[[${item.specId}]]`);
+  if (item.targetId && item.targetId !== item.specId) parts.push(`→ [[${item.targetId}]]`);
+  return parts.length ? parts.join(' ') : '_(no specific spec — vault-level)_';
+}
+
+function renderSuggestedActions(item) {
+  if (!Array.isArray(item.suggestedActions) || item.suggestedActions.length === 0) return '';
+  const lines = item.suggestedActions.map((a) => `- ${a}`);
+  return `\n## Suggested actions\n\n${lines.join('\n')}\n`;
+}
+
+/**
+ * The resolution menu. A `prerequisite` gets the Do-this-first / Switch / Defer
+ * / Resolve ladder; a `stale_index` gets ONLY re-scan/clear (no edge mutation);
+ * a `bug` (derived diagnose row) leads with a pointer to
+ * [[resolution-diagnose-workflow]] before the resolve/dismiss/defer set;
+ * everything else gets the generic resolve/dismiss/defer set.
+ * Authority: re-scan is agent-autonomous; Switch / Defer / edge-removal /
+ * override require explicit user confirmation ([[on-deck-v2-design]] Pass 7).
+ */
+function renderResolutionMenu(item) {
+  if (item.kind === 'stale_index') {
+    return `\n## Resolution menu\n\n- **Re-scan / clear** — re-run detection; this item is index-only and has **no edge to mutate**. _(agent-autonomous)_\n`;
+  }
+
+  if (item.kind === 'prerequisite') {
+    const dependent = item.specId ? `[[${item.specId}]]` : 'the dependent';
+    const prereq = item.targetId ? `[[${item.targetId}]]` : 'the prerequisite';
+    const prereqId = item.targetId || 'the-prerequisite';
+    const dependentId = item.specId || 'the-dependent';
+    // When the prerequisite lives in a DIFFERENT milestone than the dependent,
+    // the deterministic cross-milestone paths apply ([[HS-EPIC-QQBD]]). All five
+    // run through one execution surface — `heyspex_resolve_prerequisite` (MCP) /
+    // `POST /api/focus/prereq` / `hs prereq` — so the choice is the same across
+    // the console overlay, the CLI, and here.
+    return `\n## Resolution menu (priority order)\n\nIf ${prereq} is in a **different milestone** than ${dependent}, these are the deterministic cross-milestone paths ([[HS-EPIC-QQBD]]); execute the chosen one with \`heyspex_resolve_prerequisite { blocked_id: "${dependentId}", prereq_id: "${prereqId}", path }\` (or \`POST /api/focus/prereq\` / \`hs prereq\`). Default = present the choice; nothing moves without you.\n\n1. **Do the prereq first** _(recommended)_ — \`path: "do_first"\` pins ${prereq} now and **auto re-pins ${dependent}'s milestone when ${prereq} closes** (\`auto_return: true\`, the default). Freeze-safe — the pin overlays the scheduler order and never rewrites a frozen milestone snapshot ([[HS-EPIC-FRZE-freeze-scheduler-order-per-active-milestone]]). Sub-option: \`path: "dispatch"\` hands ${prereq} to a **parallel agent** while you stay on ${dependent}. _(**requires your confirmation**)_\n2. **Switch to the prereq's milestone** — \`path: "switch_milestone"\` pins ${prereq}'s whole milestone; ${dependent}'s milestone stays in_progress and resurfaces next in line. _(requires your confirmation)_\n3. **Move the prereq into this milestone** — \`path: "move_in", confirm: true\` reparents ${prereq} under ${dependent}'s milestone (a reversible, change-logged roadmap mutation, [[destructive-action-checklist]]). Epics only. _(**requires your confirmation**)_\n4. **Defer** — \`path: "defer"\` (or \`POST /api/resolution/status { item_key: "${item.key}", status: "deferred", deferUntil }\`). _(requires your confirmation)_\n5. **Resolve / override** — if this is a **met-on-disk false positive**, re-scan/clear (no write); if the edge is genuinely obsolete, do a reversible, change-logged removal; else **override** with a logged reason. _(requires your confirmation)_\n`;
+  }
+
+  if (item.kind === 'bug') {
+    const diag = item.specId ? `[[${item.specId}]]` : 'the diagnose';
+    return `\n## Resolution menu\n\n- **Procedure** — follow [[resolution-diagnose-workflow]]: confirm the symptom/core layer, claim ${diag} as a leaf, fix it, **sweep for sibling bugs of the same type before close**, then flip the diagnose to in_review.\n- **Resolve** — \`POST /api/resolution/status { item_key: "${item.key}", status: "resolved" }\` once ${diag} is fixed on disk (the derived bug row drops on re-scan).\n- **Dismiss** — \`{ status: "dismissed" }\` (reversible — Undo re-appends \`status: "open"\`).\n- **Defer** — \`{ status: "deferred", deferUntil }\`. _(Switch / Dismiss / Defer require your confirmation.)_\n`;
+  }
+
+  return `\n## Resolution menu\n\n- **Resolve** — \`POST /api/resolution/status { item_key: "${item.key}", status: "resolved" }\` once the underlying issue is fixed on disk.\n- **Dismiss** — \`{ status: "dismissed" }\` (reversible — Undo re-appends \`status: "open"\`).\n- **Defer** — \`{ status: "deferred", deferUntil }\`. _(Switch / Dismiss / Defer require your confirmation.)_\n`;
+}
+
+function renderQueue(queue) {
+  if (!Array.isArray(queue) || queue.length === 0) {
+    return '\n## Queue\n\n_(empty — this is the only open item)_\n';
+  }
+  const shown = queue.slice(0, QUEUE_PREVIEW_LIMIT);
+  const lines = shown.map(
+    (i, n) => `${n + 1}. ${i.title} — \`${i.kind}\` (${i.severity}${i.gating ? ', gating' : ''})`,
+  );
+  const more = queue.length > shown.length ? `\n_…and ${queue.length - shown.length} more._` : '';
+  return `\n## Queue (next ${shown.length})\n\n${lines.join('\n')}${more}\n`;
+}
+
+/**
+ * Build the verbatim `/hs-resolve` brief for one resolution item.
+ */
+export function buildHsResolvePromptMarkdown({ item, source, queue = [] }) {
+  const header = source === 'resolution_focus' ? 'resolution_focus' : 'resolution_queue';
+  const gatingStr = item.gating ? 'yes' : 'no';
+  const detail = item.detail ? `\n${item.detail.trim()}\n` : '';
+
+  return `## ${header} — ${item.kind}
+
+**Item:** ${item.title}
+**Kind:** \`${item.kind}\` · **Severity:** ${item.severity} · **Gating:** ${gatingStr}
+**Affected:** ${affectedLine(item)}
+**Key:** \`${item.key}\`
+
+---
+${detail}${renderSuggestedActions(item)}${renderResolutionMenu(item)}${renderQueue(queue)}`;
+}