heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/filing-tools.mjs

@@ -0,0 +1,723 @@
+// Filing and plan tools: heyspex_file_spec, register_spec, push_plan, ground_plan,
+// plan_review, plan_qc, validate_linkage, validate_user_skills. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { buildGatewayReport } from '../../scripts/gateway-skills-lib.mjs';
+import { resolveSpecIdForMutation, wrapDesignResult } from './tool-helpers.mjs';
+import { validateLinkage } from './validate-linkage.mjs';
+import { runPlanQc, runPlanReview } from './plan-review.mjs';
+import { injectNeonFocusPin, writeFocusSelectionVendor } from './focus-tools.mjs';
+import { executeGroundPlan } from './plan-ground.mjs';
+import { executePushPlanCloudAware } from './plan-push.mjs';
+import { registerSpecViaMode } from './register-spec.mjs';
+import { SUMMARY_REQUIRED_FILE_SPEC_TYPES, buildSummaryRequiredMcpError } from './summary-contract.mjs';
+import { buildCaptureStageRefusal, decideCaptureStageGate } from './capture-stage-gate.mjs';
+import { resolveLiveActiveCapture } from './capture-tools.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+import { randomUUID } from 'node:crypto';
+import { consoleFetch, enrichConsoleFailurePayloadAsync } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { resolveReadTier } from './read-path.mjs';
+import {
+  buildDeferredPayload,
+  deferredToolResponse,
+  drainAndSummarize,
+  isOutageClassResult,
+  stashIfOutage,
+} from './write-outbox.mjs';
+import { join } from 'node:path';
+import { statSync, existsSync } from 'node:fs';
+import { importDevModeCore } from './dev-mode-core.mjs';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// scripts/lib/dev-mode.mjs is a CODE-repo artifact that ships with this
+// package — since the repo split (2026-08-31) the vault root no longer holds
+// it, so resolve it relative to THIS file's checkout first and fall back to
+// the vault root only for pre-split layouts where they were the same repo.
+// `HS_PKG_ROOT` wins when set (same precedence as dev-tools.mjs's
+// CHECKOUT_ROOT / plan-review.mjs's resolveCodeAuditRoots).
+const CHECKOUT_ROOT = resolveCodeRoot({ packageRoot: PACKAGE_ROOT });
+
+/**
+ * heyspex_validate_linkage — scan the vault for orphan specs, broken wikilinks,
+ * missing manifest refs, and parent/child mismatches ([[HS-TASK-0U1F]]).
+ * Core lives in validate-linkage.mjs; this is the MCP face.
+ */
+export function handleValidateLinkage(vaultRoot, args = {}) {
+  const result = validateLinkage(vaultRoot, {
+    spec_id: typeof args.spec_id === 'string' && args.spec_id.trim() ? args.spec_id.trim() : null,
+    includeWarnings: args.include_warnings !== false,
+  });
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/**
+ * heyspex_validate_user_skills — validate user-authored gateway skills and
+ * their scope coverage (HS-WEC3). Core lives in scripts/gateway-skills-lib.mjs;
+ * this is the MCP face (CLI face: `hs gateway validate`; doctor face:
+ * `hs doctor --check-gateway`). Read-only by contract.
+ */
+export function handleValidateUserSkills(vaultRoot, args = {}) {
+  const report = buildGatewayReport(vaultRoot);
+  const slug = typeof args.skill === 'string' && args.skill.trim() ? args.skill.trim() : null;
+  const result = slug
+    ? {
+        ...report,
+        skills: { ...report.skills, skills: report.skills.skills.filter((s) => s.slug === slug) },
+        orphans: { ...report.orphans, orphans: report.orphans.orphans.filter((o) => o.slug === slug) },
+      }
+    : report;
+  if (slug && result.skills.skills.length === 0) {
+    return wrapDesignResult({ error: 'skill_not_found', message: `No user skill named "${slug}" under ${report.skills.root}.` });
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+/**
+ * heyspex_register_spec — link an orphan/mismatched spec into the roadmap
+ * hierarchy ([[HS-TASK-5K13]]). Core lives in register-spec.mjs; this is the
+ * MCP face. The fix counterpart to heyspex_validate_linkage.
+ */
+export async function handleRegisterSpec(vaultRoot, args = {}) {
+  const registerResolved = await resolveSpecIdForMutation(args.spec_id);
+  if (registerResolved.response) return registerResolved.response;
+  // Cloud-aware entry ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]
+  // sweep): resolves `resolveVaultWriteMode()` ONCE and either runs the
+  // untouched synchronous disk path (`local`) or sends each touched spec
+  // through `PUT /api/specs/:id` (`cloud`). Awaiting is safe in both — the
+  // local branch delegates straight to `registerSpec` and returns the same
+  // plain object it always did.
+  const result = await registerSpecViaMode(vaultRoot, {
+    spec_id: registerResolved.specId,
+    parent_id: typeof args.parent_id === 'string' && args.parent_id.trim() ? args.parent_id.trim() : null,
+    roadmap_id: typeof args.roadmap_id === 'string' && args.roadmap_id.trim() ? args.roadmap_id.trim() : undefined,
+    position: typeof args.position === 'string' && args.position.trim() ? args.position.trim() : undefined,
+    dryRun: args.dry_run === true,
+  });
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+/**
+ * File a NEW spec of any non-capture kind ([[HS-EPIC-1EM0]] / [[HS-TASK-B6DG]]).
+ * Thin forwarder to console `POST /api/specs` — the server owns id allocation,
+ * canonical-template frontmatter, parent-array linkage, and per-kind validation
+ * (all extended by [[HS-TASK-U13O]]). The client contract is preserved verbatim
+ * ({ type, name, frontmatter?, body? }); no kind/title rename. POST errors
+ * (invalid parent, `type: capture` rejection, etc.) surface verbatim so the
+ * agent sees the server's guidance (e.g. "use heyspex_active_capture").
+ */
+export function resolveFileSpecSummary(args = {}) {
+  const top = typeof args.summary === 'string' ? args.summary.trim() : '';
+  const fromFm =
+    args.frontmatter && typeof args.frontmatter.summary === 'string'
+      ? args.frontmatter.summary.trim()
+      : '';
+  return top || fromFm;
+}
+
+/**
+ * The only top-level `heyspex_file_spec` arguments the tool actually reads
+ * ([[tool-catalog.mjs]]'s declared inputSchema `properties`, kept in
+ * lockstep by `file-spec-artifact-field.test.mjs`). Parent/milestone linkage
+ * is NOT a top-level argument — it goes inside `frontmatter.parent` /
+ * `frontmatter.milestone` (the schema description says so), but nothing
+ * enforced that at runtime.
+ */
+export const FILE_SPEC_ACCEPTED_ARGS = [
+  'type',
+  'name',
+  'summary',
+  'frontmatter',
+  'body',
+  'recipe_context',
+  'checks',
+  'expect_tier',
+];
+
+/** Top-level keys a caller plausibly means for frontmatter linkage — used only to tailor the refusal message. */
+const FILE_SPEC_FRONTMATTER_HINT_KEYS = new Set(['parent', 'milestone', 'pillar', 'severity', 'id']);
+
+/**
+ * Pure verdict on a `heyspex_file_spec` argument bag: refuses an unrecognized
+ * top-level key BY NAME instead of letting it silently vanish before
+ * `buildFileSpecPostBody` even runs — the same failure mode
+ * [[additionalproperties-false-in-an-mcp]] documents for
+ * `heyspex_update_capture` (`updateCaptureArgsVerdict`), and the exact shape
+ * of [[HS-XQMK-A1QE-DIAG-heyspex-file-spec-drops-the-parent]]: a top-level
+ * `parent:` argument passed the declared `additionalProperties: false`
+ * schema (never enforced at runtime by the MCP transport), then vanished
+ * silently because `buildFileSpecPostBody` never read `args.parent` — every
+ * filed task landed orphaned with no error anywhere. Call this at the
+ * handler's first hop, before any other validation or the POST.
+ */
+export function fileSpecArgsVerdict(args = {}) {
+  const unknown = Object.keys(args).filter((k) => !FILE_SPEC_ACCEPTED_ARGS.includes(k));
+  if (unknown.length > 0) {
+    const hinted = unknown.filter((k) => FILE_SPEC_FRONTMATTER_HINT_KEYS.has(k));
+    const hint =
+      hinted.length > 0
+        ? ` Spec-kind linkage/overrides go inside frontmatter, not top-level: pass frontmatter: { ${hinted
+            .map((k) => `${k}: ...`)
+            .join(', ')} } instead.`
+        : '';
+    return {
+      ok: false,
+      error: {
+        error: 'UNKNOWN_FIELD',
+        message: `heyspex_file_spec does not accept: ${unknown.join(', ')}. NOTHING WAS FILED — re-send using only the accepted arguments.${hint}`,
+        field: unknown[0],
+        unknown_fields: unknown,
+        accepted_fields: FILE_SPEC_ACCEPTED_ARGS,
+      },
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Build the POST /api/specs request body from heyspex_file_spec args. Pure and
+ * exported so the field-forwarding contract is unit-testable without a live
+ * console. `recipe_context` (the heyspex_start_recipe start context) is
+ * forwarded verbatim when it is a non-null object — the server reads recipe_id
+ * + tool_scope from it and stamps recipe provenance ([[HS-98G6-TASK]] /
+ * [[HS-5G0P-EPIC]] AC5); it is omitted entirely when absent so non-recipe
+ * filings are byte-identical to before.
+ */
+export function buildFileSpecPostBody(args = {}, actingAgent = null) {
+  const authoredSummary = resolveFileSpecSummary(args);
+  return {
+    type: args.type,
+    name: args.name,
+    ...(authoredSummary ? { summary: authoredSummary } : {}),
+    ...(args.frontmatter && typeof args.frontmatter === 'object'
+      ? { frontmatter: args.frontmatter }
+      : {}),
+    ...(typeof args.body === 'string' ? { body: args.body } : {}),
+    ...(actingAgent ? { acting_agent: actingAgent } : {}),
+    ...(args.recipe_context && typeof args.recipe_context === 'object' && !Array.isArray(args.recipe_context)
+      ? { recipe_context: args.recipe_context }
+      : {}),
+    // The frozen checks manifest ([[checks-manifest-authoring]]). Forwarded only
+    // when the caller authored rows, so filings that pass none stay byte-identical
+    // to before and pick up the server's `no_checks_manifest` warning instead.
+    ...(Array.isArray(args.checks) && args.checks.length > 0 ? { checks: args.checks } : {}),
+  };
+}
+
+/**
+ * Local host names whose console owns THIS machine's disk. A write posted to
+ * one of these landed (or should have landed) in the local clone; anything
+ * else is a cloud console with no access to it.
+ */
+export const LOCAL_CONSOLE_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '[::1]', '::1']);
+
+/** True when a console origin points at this machine. Never throws. */
+export function isLocalConsoleOrigin(url) {
+  if (typeof url !== 'string' || !url) return false;
+  try {
+    return LOCAL_CONSOLE_HOSTS.has(new URL(url).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * WHERE DID THE WRITE LAND — the pure verdict ([[HS-IOJW-5YDH-DIAG]]).
+ *
+ * The bug this closes: a vault write reported plain success whether the bytes
+ * reached a file in this clone or only a Neon row on another machine. Two
+ * sessions lost work to it on 2026-08-21 and recovered it only by re-reading
+ * the file out of habit.
+ *
+ * Inputs are all MEASURED by the caller, never assumed:
+ *   consoleUrl        the origin the POST actually went to (consoleFetch result.url)
+ *   consoleWrite      the console's own `write` block when it is new enough to send one
+ *   relPath           vault-relative path the console says it wrote
+ *   vaultRoot         this session's clone, or null when there is none
+ *   absPath           the absolute path actually written, when the console reports one
+ *   localFileExists   a real stat of that path; null when unmeasurable
+ *   devMode           { mode, reliance, source, updated_at } from ~/.heyspex/dev-mode.json
+ *   expectTier        the caller's declared expectation: "disk" | "cloud" | undefined
+ *
+ * Returns { landed, error } — `error` non-null means the tool must answer
+ * isError, WITH the spec id still attached so nobody re-files a duplicate.
+ */
+export function fileSpecLandingVerdict({
+  consoleUrl = null,
+  consoleWrite = null,
+  relPath = null,
+  vaultRoot = null,
+  localFileExists = null,
+  devMode = null,
+  expectTier = null,
+  absPath = null,
+} = {}) {
+  // Tier: prefer what the console measured; fall back to the origin we posted
+  // to, so this still works against a deployed console that predates the
+  // `write` block.
+  let tier;
+  let reportedBy;
+  if (consoleWrite?.mode === 'local' || consoleWrite?.mode === 'cloud') {
+    tier = consoleWrite.mode === 'local' ? 'disk' : 'cloud';
+    reportedBy = 'console';
+  } else {
+    tier = isLocalConsoleOrigin(consoleUrl) ? 'disk' : 'cloud';
+    reportedBy = 'inferred_from_console_url';
+  }
+
+  const landed = {
+    tier,
+    reported_by: reportedBy,
+    console_url: consoleUrl,
+    rel_path: relPath,
+    // The console's own absolute path wins. Its vault root is the SPECS dir,
+    // not the repo root, and `relPath` is relative to THAT — joining it onto
+    // the MCP's vaultRoot points at a file that never existed. Caught live on
+    // the first real filing through this code.
+    abs_path: absPath ?? (vaultRoot && relPath ? join(vaultRoot, relPath) : null),
+    in_local_vault: localFileExists,
+    vault_root: vaultRoot,
+    console_write: consoleWrite ?? null,
+    dev_mode: devMode
+      ? {
+          mode: devMode.mode ?? null,
+          reliance: devMode.reliance ?? null,
+          set_by: devMode.source ?? null,
+          set_at: devMode.updated_at ?? null,
+        }
+      : null,
+  };
+
+  const modeNote = landed.dev_mode?.mode
+    ? ` Mode is ${landed.dev_mode.mode}/${landed.dev_mode.reliance}, last set by ${landed.dev_mode.set_by ?? 'unknown'} at ${landed.dev_mode.set_at ?? 'unknown time'}.`
+    : '';
+
+  // 1. The caller said where it wanted the write and it went elsewhere.
+  if (expectTier && tier !== expectTier) {
+    return {
+      landed,
+      error: {
+        error: 'WRITE_TIER_MISMATCH',
+        message:
+          `The spec was created, but on ${tier} — you asked for ${expectTier}.${modeNote} ` +
+          'The spec id below is real; do NOT file it again. Switch the mode with ' +
+          'heyspex_dev_mode and re-check, or pass expect_tier to match where you want it.',
+      },
+    };
+  }
+
+  // 2. Undeclared cloud landing while this session has a clone in front of it.
+  //    This is the exact shape that lost work: agent believes it is writing
+  //    files, the mode was flipped underneath it, nothing appears on disk.
+  if (!expectTier && tier === 'cloud' && vaultRoot) {
+    return {
+      landed,
+      error: {
+        error: 'WRITE_LANDED_OFF_DISK',
+        message:
+          `The spec was created in the cloud index, NOT as a file in this clone (${vaultRoot}).${modeNote} ` +
+          'The spec id below is real; do NOT file it again. Either switch back with ' +
+          'heyspex_dev_mode({ action: "set", mode: "local" }) and re-file, or pass ' +
+          'expect_tier: "cloud" to say you meant it.',
+      },
+    };
+  }
+
+  // 3. It claims disk, and the file is not there. A write that reports success
+  //    over a missing file is the defect itself.
+  if (tier === 'disk' && localFileExists === false) {
+    return {
+      landed,
+      error: {
+        error: 'WRITE_NOT_ON_DISK',
+        message:
+          `The console answered success but no file exists at ${landed.abs_path ?? relPath}.${modeNote} ` +
+          'The spec id below may still be real in the index — check it before re-filing, and ' +
+          'read the console logs for a swallowed disk error.',
+      },
+    };
+  }
+
+  return { landed, error: null };
+}
+
+/**
+ * Shell around {@link fileSpecLandingVerdict}: reads the machine-local dev-mode
+ * record and stats the file. Never throws — a landing report that fails must
+ * not fail the write it reports on.
+ */
+export async function measureFileSpecLanding({ consoleUrl, consoleBody, relPath, vaultRoot, expectTier }) {
+  let devMode = null;
+  try {
+    if (vaultRoot) {
+      // Bundler-safe loader (see dev-mode-core.mjs): the runtime paths first,
+      // then a static specifier. Without the fallback the bundled remote
+      // endpoint skipped the landing probe entirely.
+      const mod = await importDevModeCore([
+        join(CHECKOUT_ROOT, 'scripts', 'lib', 'dev-mode.mjs'),
+        join(vaultRoot, 'scripts', 'lib', 'dev-mode.mjs'),
+      ]);
+      devMode = mod.readLocalDevModeRecord()?.record ?? null;
+    }
+  } catch {
+    devMode = null;
+  }
+  // Which absolute path to stat. The console's own `absPath` is authoritative
+  // when it sent one — its vault root is <repo>/specs, so `relPath` alone is
+  // NOT resolvable against the MCP's repo root. Without it, try both roots
+  // rather than guessing one and reporting a phantom missing file.
+  const consoleWrite = consoleBody?.write ?? null;
+  const candidates = [];
+  if (typeof consoleWrite?.absPath === 'string' && consoleWrite.absPath) {
+    candidates.push(consoleWrite.absPath);
+  } else if (vaultRoot && relPath) {
+    candidates.push(join(vaultRoot, relPath), join(vaultRoot, 'specs', relPath));
+  }
+  let localFileExists = candidates.length > 0 ? false : null;
+  let absPath = candidates[0] ?? null;
+  for (const candidate of candidates) {
+    try {
+      if (statSync(candidate).isFile()) {
+        localFileExists = true;
+        absPath = candidate;
+        break;
+      }
+    } catch {
+      // keep looking
+    }
+  }
+  return fileSpecLandingVerdict({
+    consoleUrl,
+    consoleWrite,
+    relPath,
+    vaultRoot,
+    localFileExists,
+    devMode,
+    expectTier,
+    absPath,
+  });
+}
+
+export async function handleFileSpec(args = {}, vaultRoot = null) {
+  // First hop: refuse an unrecognized top-level arg (e.g. a top-level
+  // `parent:`) BY NAME instead of letting it silently vanish before
+  // buildFileSpecPostBody even runs [[HS-XQMK-A1QE-DIAG-heyspex-file-spec-drops-the-parent]].
+  const argsVerdict = fileSpecArgsVerdict(args);
+  if (!argsVerdict.ok) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(argsVerdict.error, null, 2) }],
+    };
+  }
+  if (!args.type || typeof args.type !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'type is required' }) }],
+    };
+  }
+  if (!args.name || typeof args.name !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'name is required' }) }],
+    };
+  }
+  // Summary required at filing — planning phase (milestone/epic) or execution
+  // phase (task via What's Next `/hs-next` only). Never co-file epics and tasks.
+  if (SUMMARY_REQUIRED_FILE_SPEC_TYPES.has(args.type) && !resolveFileSpecSummary(args)) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify(buildSummaryRequiredMcpError(args.type), null, 2),
+      }],
+    };
+  }
+  // Capture-stage rule ([[capture-stage-gate]]): an open capture must not become
+  // an epic/task/milestone. Checked HERE, before the POST, because the hook that
+  // used to own this could not read the live pin and could be switched off by a
+  // file. Runs on its own resolution failure as "allow" — a gate that refuses on
+  // its own uncertainty is worse than no gate.
+  const captureStageVerdict = decideCaptureStageGate({
+    toolArgs: args,
+    activeCapture: vaultRoot ? await resolveLiveActiveCapture(vaultRoot) : null,
+  });
+  if (captureStageVerdict.decision === 'refuse') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(buildCaptureStageRefusal(captureStageVerdict), null, 2) }],
+    };
+  }
+
+  // Acting agent for `assisted_by` auto-stamp ([[HS-EPIC-IKIM-authorship-provenance-frontmatter-owner]]
+  // AC #2). Env-detected (same source as claim_spec); the console seeds
+  // `assisted_by: [acting_agent]` on the new spec, omit-when-empty if unset.
+  const actingAgent = detectAgentIdentity(args.agent, args.session_id).agent;
+  const body = buildFileSpecPostBody(args, actingAgent);
+  // Idempotency key ([[HS-70TD-DIAG]]): generated ONCE per logical file_spec call
+  // and reused across the transport's timeout-retry (the header lives on the
+  // shared `init`), so a slow-console retry replays the first create server-side
+  // instead of double-allocating a second byte-identical spec.
+  const idempotencyKey = randomUUID();
+  // Degrade-don't-die: replay anything queued by an earlier outage first (the
+  // drain never stashes, and is failure-safe).
+  const outboxNote = vaultRoot ? await drainAndSummarize(vaultRoot, consoleFetch) : {};
+  const result = await consoleFetch('/api/specs', {
+    method: 'POST',
+    body,
+    headers: { 'idempotency-key': idempotencyKey },
+    // [[HS-2FQY]] double-mint guard: against a REMOTE console the blind
+    // timeout-retry can land on a different serverless instance, where the
+    // in-memory idempotency registry cannot replay the first create — the
+    // retry mints a SECOND id for the same spec (observed: HS-2FQY + HS-K70K,
+    // identical content, one call). Loopback keeps the retry (single process,
+    // registry replays). On a remote timeout, check before re-filing (below).
+    retryOnTimeout: false,
+  });
+  if (!result.ok) {
+    // Outage class (status 0 / timeout / 5xx) in CLOUD reliance: queue the create
+    // with its idempotency key and answer truthfully "deferred" — never isError,
+    // never a claim it landed. 4xx / 401 / sign-in problems keep their loud envelope.
+    if (vaultRoot && isOutageClassResult(result) && (await resolveReadTier()) === 'neon') {
+      const stashed = stashIfOutage(
+        result,
+        {
+          op: 'create',
+          route: '/api/specs',
+          method: 'POST',
+          request_body: body,
+          idempotency_key: idempotencyKey,
+          acting_agent: actingAgent,
+          session_id: args.session_id ?? null,
+        },
+        vaultRoot,
+      );
+      if (stashed) {
+        return deferredToolResponse({
+          ...buildDeferredPayload(stashed, vaultRoot, { attempted: { type: args.type, name: args.name } }),
+          ...(outboxNote.drained ? { drained: outboxNote.drained } : {}),
+        });
+      }
+    }
+    const payload = await enrichConsoleFailurePayloadAsync(result, {
+      error: consoleErrorCode(result, 'FILE_SPEC_FAILED'),
+      message: consoleErrorMessage(result, `POST /api/specs returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { type: args.type, name: args.name },
+      ...(result.errorKind === 'timeout'
+        ? {
+            hint:
+              'The create may still have completed server-side after this client timed out. '
+              + 'Search for a spec with this exact name before re-filing — a blind re-file can mint a duplicate id ([[HS-2FQY]]).',
+          }
+        : {}),
+    });
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  // POST returns { spec: { id, ... } }; surface the canonical { spec_id, path }
+  // contract alongside the full created spec for callers that want more.
+  const spec = result.body?.spec ?? null;
+  const relPath = spec?.relPath ?? spec?.path ?? null;
+  // [[HS-H227-MCPC-TASK]]: a caller that passed no `expect_tier` at all used
+  // to fall through to `WRITE_LANDED_OFF_DISK` the moment this session's own
+  // reliance is cloud (fileSpecLandingVerdict's rule 2 — "undeclared cloud
+  // landing while a clone is in front of us") even though a cloud-reliant
+  // session filing into the cloud index is exactly the intended shape, not a
+  // surprise. Default to "cloud" from the SAME tier verdict every other read
+  // in this file already trusts (`resolveReadTier`) — only when the caller
+  // passed nothing; an explicit `expect_tier` (including an explicit "disk")
+  // is never overridden, so local-reliance behavior is untouched.
+  let expectTier = args.expect_tier === 'disk' || args.expect_tier === 'cloud' ? args.expect_tier : null;
+  if (!expectTier) {
+    const tier = await resolveReadTier();
+    if (tier === 'neon') expectTier = 'cloud';
+  }
+  // WHERE IT LANDED ([[HS-IOJW-5YDH-DIAG]]) — measured, not assumed. A write
+  // that reports on the request instead of the result is the defect; this
+  // stats the file and names the console it went to.
+  const { landed, error: landingError } = await measureFileSpecLanding({
+    consoleUrl: result.url,
+    consoleBody: result.body,
+    relPath,
+    vaultRoot,
+    expectTier,
+  });
+  const payload = {
+    spec_id: spec?.id ?? null,
+    path: relPath,
+    landed,
+    spec,
+    console_response: result.body,
+    ...outboxNote,
+  };
+  if (landingError) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ ...landingError, ...payload }, null, 2) }],
+    };
+  }
+  // Warn rung of the capture-stage gate: the filing went through, and the reason
+  // it would otherwise have been refused rides along on the response.
+  if (captureStageVerdict.decision === 'warn') {
+    payload.capture_stage_warning = buildCaptureStageRefusal(captureStageVerdict);
+  }
+  // Non-coercive post-create suggestion ([[HS-TASK-FWPC]] / [[HS-EPIC-MNBD]]):
+  // a freshly-filed milestone has no epics yet, so suggest filing the first one.
+  // The agent decides whether to act — the MCP layer NEVER auto-executes the
+  // follow-on (CLAUDE.md autonomy boundary). Skipping leaves the milestone in
+  // `epics: []`, where MCEP/RCNB/VWSE surface it.
+  if (args.type === 'milestone' && spec?.id) {
+    payload.suggested_next_action = 'file_epic';
+    payload.suggested_next_action_args = { milestone_id: spec.id };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+export function handlePlanReview(vaultRoot, args = {}) {
+  // Map the snake_case MCP args onto the executor's camelCase contract.
+  const result = runPlanReview({
+    vaultRoot,
+    planPath: typeof args.plan_path === 'string' ? args.plan_path : undefined,
+    planContent: typeof args.plan_content === 'string' ? args.plan_content : undefined,
+    scope: args.scope === 'breakdown' ? 'breakdown' : 'plan',
+    epicId: typeof args.epic_id === 'string' ? args.epic_id : undefined,
+    epicName: typeof args.epic_name === 'string' ? args.epic_name : undefined,
+    proposedTasks: Array.isArray(args.proposed_tasks) ? args.proposed_tasks : undefined,
+    qualityPass: args.quality_pass === true,
+    agentQualityFindings: Array.isArray(args.quality_findings) ? args.quality_findings : undefined,
+  });
+  return wrapDesignResult(result);
+}
+
+export function handlePlanQc(vaultRoot, args = {}) {
+  const result = runPlanQc({
+    vaultRoot,
+    planPath: typeof args.plan_path === 'string' ? args.plan_path : undefined,
+    planContent: typeof args.plan_content === 'string' ? args.plan_content : undefined,
+    findingsSummary: typeof args.findings_summary === 'string' ? args.findings_summary : undefined,
+    axisBUserConfirmed: args.axis_b_user_confirmed === true,
+    axisBConfirmationNote:
+      typeof args.axis_b_confirmation_note === 'string' ? args.axis_b_confirmation_note : undefined,
+  });
+  return wrapDesignResult(result);
+}
+
+/**
+ * `heyspex_push_plan`. `deps.writeFocusSelection` is the injection seam (idiom
+ * from fleet-queue-tools.mjs) so a test can drive the failed-pin path without a
+ * console; cli.mjs calls with two args and gets the real Neon writer.
+ */
+export async function handlePushPlan(vaultRoot, args, deps = {}) {
+  const { writeFocusSelection = writeFocusSelectionVendor } = deps;
+  // Cloud-aware entry ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]
+  // sweep): resolves `resolveVaultWriteMode()` ONCE and either runs the
+  // untouched synchronous disk path (`local`) or files the epic through
+  // `POST /api/specs` (`cloud`). Awaiting is safe in both — the local branch
+  // still returns the same plain object it always did.
+  const result = await executePushPlanCloudAware(vaultRoot, args);
+  if (result.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+  }
+  // executePushPlan no longer writes focus itself (it is sync); do it here so the
+  // selection can reach Neon. Neon XOR file via `writeFocusSelectionVendor`.
+  //
+  // REPORT THE RESULT, NOT THE REQUEST ([[HS-IOJW-5YDH-DIAG]] sweep). The return
+  // boolean used to be discarded and `focus_written` came straight off the
+  // `on_deck` request flag, so a console that could not be reached — the one case
+  // `writeFocusSelectionVendor` is documented to fail in, with NO focus.yaml
+  // fallback — produced `success: true, focus_written: true` over a pin that was
+  // never stored, and sent the agent to /hs-next against nothing. The next
+  // session's entire run hangs off that pin.
+  if (result.on_deck && result.epic?.spec_path) {
+    const pinned = await writeFocusSelection(
+      vaultRoot,
+      result.epic.spec_path,
+      result.focus_reason,
+    );
+    result.focus_written = pinned === true;
+    if (!result.focus_written) {
+      // A failed pin is a LOUD FAILURE, never a field inside a success.
+      //
+      // It does NOT fail the whole push, and it must not: the epic markdown and
+      // the milestone mirror-update are already on disk and are correct. Erroring
+      // the push away would strand a filed epic behind a red tool call and invite
+      // a re-push that mints a SECOND epic for the same plan. So the filed facts
+      // are preserved verbatim in the payload (same shape as the `landingError`
+      // merge in handleFileSpec above) while `isError` + `success: false` stop any
+      // caller from reading this as a pinned epic. The only thing that failed is
+      // recoverable by re-running the pin — which is what `pin_recovery` says.
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ...result,
+            success: false,
+            error: 'FOCUS_PIN_NOT_WRITTEN',
+            epic_filed: true,
+            message:
+              `The epic WAS filed (${result.epic.spec_path}) but the on-deck focus pin was NOT written. ` +
+              'Neon is the only focus store (no .heyspex/focus.yaml fallback), so NOTHING is pinned — ' +
+              'do NOT run /hs-next expecting this epic, it will resolve to whatever was pinned before. ' +
+              'Do NOT re-run heyspex_push_plan: that would file a second epic for the same plan.',
+            pin_recovery: {
+              spec_path: result.epic.spec_path,
+              reason: result.focus_reason,
+              how: 'Check heyspex_dev_server_status, then re-pin: PUT /api/control/focus-selection ' +
+                '{ spec_path, kind: "epic", picked_by: "human", reason } — or re-run heyspex_push_plan ' +
+                'with on_deck once the console is reachable ONLY if the epic above was not filed.',
+            },
+          }, null, 2),
+        }],
+      };
+    }
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}
+
+export async function handleGroundPlan(vaultRoot, args) {
+  // Resolve the Neon focus selection (layer-2 `spec_path`) at the async boundary
+  // and thread it into the sync grounding engine, so /hs-ground's focused-epic
+  // conflict scan reads the same Neon selection the console does — not the dormant
+  // file. `injectNeonFocusPin` adds `neon_selection_spec_path` (best-effort; an
+  // unreachable console / free-tier 402 leaves args untouched → file fallback).
+  // [[HS-TASK-FSEL]] residual / [[HS-TASK-FSKP]] session of [[HS-EPIC-FRTR]].
+  const resolvedArgs = await injectNeonFocusPin(args);
+  // Retrieval is remote and bounded since
+  // [[HS-YIR1-8KK5-TASK-planning-grounding-retrieves-through]] — the grounding
+  // engine issues `GET /api/search` calls of its own, so it is awaited here.
+  const result = await executeGroundPlan(vaultRoot, resolvedArgs);
+  if (result.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+    };
+  }
+  // Bounded report mode: emit the capped markdown directly so /hs-ground pastes it
+  // verbatim — no JSON envelope for the agent to unpack or over-read.
+  if (result._report) {
+    const footer = `\n\n---\n_grounded ${result.grounded_at} · ~${result.token_estimate}/${result.max_tokens} tok${result.truncated ? ' (truncated to fit)' : ''} · conflicts: ${result.conflict_count}${result.has_blocking_conflicts ? ' (BLOCKING — resolve first)' : ''}_`;
+    return {
+      content: [{ type: 'text', text: `${result.report_markdown}${footer}` }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}