heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/cloud-vault-writes.mjs

@@ -0,0 +1,602 @@
+#!/usr/bin/env node
+/**
+ * cloud-vault-writes.mjs — the WRITE-side twin of `read-path.mjs`.
+ *
+ * `read-path.mjs` decides `disk` vs `neon` for every vault READ the MCP
+ * server makes. This module is the single place every vault WRITE goes when
+ * `resolveVaultWriteMode()` says `cloud`: a create becomes
+ * `POST /api/specs` (the console mints the id, the family and the filename),
+ * an edit of an existing spec becomes `PUT /api/specs/:id`, and a listing
+ * needed to build either becomes `GET /api/specs?type=…`.
+ *
+ * Why this exists: a disk write in cloud mode is a SPLIT BRAIN — a markdown
+ * file on a machine the console's index has never heard of, on a machine that
+ * may not even hold a clone of the vault. `handleSaveResearch`
+ * (research-handlers.mjs) and `handleFileSpec` (filing-tools.mjs) already
+ * file through the console; this module gives every OTHER writer (the
+ * promotion helpers, plan-push, register-spec, spec_edit, capture-focus) the
+ * same two verbs without each re-deriving the request shape, the
+ * idempotency-key rule, or the failure envelope.
+ *
+ * Transport-free by design, like read-path.mjs: callers inject
+ * `consoleFetch`. The module never imports console-transport.mjs, so every
+ * test drives it with a recorder and never opens a socket.
+ *
+ * Failure contract: every failure throws {@link CloudWriteUnreachableError},
+ * whose `message` STARTS WITH `CONSOLE_UNREACHABLE_CLOUD_MODE` and names the
+ * route and the console — the same string shape `readViaSelector` produces on
+ * the read side, so one `catch` in a handler can render either. There is no
+ * disk fallback: a cloud-reliant session that cannot reach its console fails
+ * loudly rather than leaving bytes behind that nothing indexes.
+ *
+ * There is deliberately NO rollback. `commitWrites`'s disk transaction can
+ * restore a snapshot; the console has no "un-create". Instead
+ * {@link commitWritesViaConsole} stops at the FIRST failure and reports which
+ * step failed and which steps already landed, so the caller can say exactly
+ * what state the vault is in ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]] AC5).
+ */
+
+import { randomUUID } from 'node:crypto';
+import { walkSpecListPages } from './list-tools.mjs';
+import { parseFrontmatter } from './vault-io.mjs';
+import {
+  buildDeferredPayload,
+  drainAndSummarize,
+  getWriteOutboxRoot,
+  isOutageClassResult,
+  stashIfOutage,
+  stashWrite,
+  failureOf,
+  DEFERRED_RECEIPT,
+} from './write-outbox.mjs';
+
+/**
+ * Raised when a `cloud`-mode write fails. Mirrors
+ * `ConsoleUnreachableCloudModeError` (read-path.mjs) exactly — same `name`,
+ * same message prefix — so callers that already render one render both.
+ */
+export class CloudWriteUnreachableError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'CONSOLE_UNREACHABLE_CLOUD_MODE';
+    Object.assign(this, details);
+  }
+}
+
+/**
+ * Raised INSTEAD of a plain {@link CloudWriteUnreachableError} when the write hit
+ * an outage (status 0 / timeout / 5xx) and was queued to the write outbox
+ * ([[heyspex-is-online-only-no-offline]] 2026-08-20 amendment). It extends the
+ * unreachable error so every existing `catch` still works, but it carries
+ * `deferred: true` + the truthful receipt: the write did NOT land yet, and it is
+ * NOT lost. Callers that can return a tool response render
+ * {@link deferredPayloadFromError}; callers that need the new spec's id/basename
+ * (promotion chains) cannot continue and surface it as before.
+ */
+export class CloudWriteDeferredError extends CloudWriteUnreachableError {
+  constructor(message, details = {}) {
+    super(message, details);
+    this.deferred = true;
+  }
+}
+
+/** The `{ status: 'deferred', … }` tool payload for a deferred error, or null. */
+export function deferredPayloadFromError(err) {
+  if (!err?.deferred || !err.outbox_id) return null;
+  return {
+    status: 'deferred',
+    outbox_id: err.outbox_id,
+    pending_sync: err.pending_sync ?? 1,
+    receipt: err.receipt ?? DEFERRED_RECEIPT,
+    ...(err.completed_steps ? { completed_steps: err.completed_steps } : {}),
+  };
+}
+
+/** Details carrying the replayable request for a no-stash caller (commitWritesViaConsole). */
+function outageRequest(noStash, result, entry) {
+  return noStash && isOutageClassResult(result)
+    ? { outage_request: { ...entry, failure: failureOf(result) } }
+    : {};
+}
+
+function deferredError(routeLabel, consoleUrl, stashed, vaultRoot, details = {}) {
+  const payload = buildDeferredPayload(stashed, vaultRoot);
+  return new CloudWriteDeferredError(
+    `CONSOLE_UNREACHABLE_CLOUD_MODE: route "${routeLabel}" failed against console ${consoleUrl ?? '<unknown console>'} — ${DEFERRED_RECEIPT} (outbox_id ${payload.outbox_id})`,
+    { route: routeLabel, console_url: consoleUrl ?? null, ...details, outbox_id: payload.outbox_id, pending_sync: payload.pending_sync, receipt: payload.receipt },
+  );
+}
+
+/** Build the canonical failure error for a route + console + detail. */
+export function cloudWriteFailure(routeLabel, consoleUrl, detail, details = {}) {
+  return new CloudWriteUnreachableError(
+    `CONSOLE_UNREACHABLE_CLOUD_MODE: route "${routeLabel}" failed against console ${consoleUrl ?? '<unknown console>'} — ${detail}`,
+    { route: routeLabel, console_url: consoleUrl ?? null, ...details },
+  );
+}
+
+/** One-line summary of a consoleFetch failure result, for the message above. */
+function describeResult(result) {
+  if (!result) return 'no response';
+  const bodyText =
+    result.error ||
+    (result.body ? JSON.stringify(result.body).slice(0, 400) : '') ||
+    '';
+  return `${result.status ?? '?'}${bodyText ? ` ${bodyText}` : ''}`;
+}
+
+/**
+ * Fields the SERVER mints and a create request must therefore never carry.
+ * `id`/`file_id` are the file key itself (server-minted since 2026-07-10 —
+ * a locally minted key in a file-less vault collides with a cloud-side one);
+ * `created`/`updated`/`created_tz`/`updated_tz` are stamped by `createSpec`.
+ * `family` is NOT stripped: an explicit family is a legal, meaningful
+ * override (`createSpec` honours it over parent inheritance).
+ */
+export const SERVER_MINTED_FIELDS = Object.freeze([
+  'id',
+  'file_id',
+  'created',
+  'updated',
+  'created_tz',
+  'updated_tz',
+]);
+
+/**
+ * The status the console seeds on every non-ADR create (`createSpec` in
+ * spex-console/src/lib/vault.ts). Sending it on a POST asks for nothing.
+ */
+export const DEFAULT_INITIAL_STATUS = 'open';
+
+/** True when `value` is the default initial status (case/whitespace-insensitive). */
+export function isDefaultInitialStatus(value) {
+  return typeof value === 'string' && value.trim().toLowerCase() === DEFAULT_INITIAL_STATUS;
+}
+
+/** Copy of `frontmatter` with every server-minted field removed. */
+export function stripServerMintedFields(frontmatter = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(frontmatter ?? {})) {
+    if (SERVER_MINTED_FIELDS.includes(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Split a raw `.md` file (the shape every disk writer already builds) into the
+ * `{ frontmatter, body }` pair both console write routes take. Reuses
+ * `parseFrontmatter` from vault-io.mjs so the YAML dialect the vault writes is
+ * the YAML dialect this reads — no second parser to drift.
+ */
+export function splitRawSpec(raw) {
+  const { frontmatter, body } = parseFrontmatter(String(raw ?? ''));
+  return { frontmatter: frontmatter ?? {}, body: body ?? '' };
+}
+
+/** Basename (no extension) from a console-returned relPath. */
+export function basenameFromRelPath(relPath) {
+  if (!relPath) return null;
+  return String(relPath)
+    .split(/[\\/]/)
+    .pop()
+    .replace(/\.md$/i, '');
+}
+
+/**
+ * `POST /api/specs` — create one spec through the console.
+ *
+ * The request shape is `buildFileSpecPostBody`'s (filing-tools.mjs), down to
+ * the per-call `idempotency-key` header and `retryOnTimeout: false` (the
+ * [[HS-2FQY]] double-mint guard: a blind retry against a REMOTE console can
+ * land on a different serverless instance whose in-memory idempotency
+ * registry cannot replay the first create, minting a second id for one spec).
+ *
+ * Returns `{ specId, relPath, basename, spec, consoleWrite, warnings }`. The
+ * BASENAME is the load-bearing return value for promotion flows: every
+ * sibling write references the new document by `[[basename]]`, and in cloud
+ * mode that basename is only knowable after this call returns — which is why
+ * cloud-mode promotion is create-first, link-second.
+ */
+export async function createSpecViaConsole({
+  consoleFetch,
+  consoleUrl = null,
+  type,
+  name,
+  summary = null,
+  frontmatter = null,
+  body = null,
+  actingAgent = null,
+  idempotencyKey = null,
+  routeLabel = 'POST /api/specs',
+  vaultRoot = null,
+  noStash = false,
+}) {
+  const outboxRoot = noStash ? null : vaultRoot ?? getWriteOutboxRoot();
+  if (typeof consoleFetch !== 'function') {
+    throw cloudWriteFailure(routeLabel, consoleUrl, 'no consoleFetch dependency was injected');
+  }
+  if (typeof type !== 'string' || !type.trim()) {
+    throw cloudWriteFailure(routeLabel, consoleUrl, 'a spec `type` is required to create through the console');
+  }
+  if (typeof name !== 'string' || !name.trim()) {
+    throw cloudWriteFailure(routeLabel, consoleUrl, 'a spec `name` is required to create through the console');
+  }
+  const cleanedFm = stripServerMintedFields(frontmatter ?? {});
+  // `name`/`type`/`summary` ride at the TOP level of the request (the route's
+  // contract); leaving duplicates inside `frontmatter` lets the two disagree.
+  delete cleanedFm.name;
+  delete cleanedFm.type;
+  // [[HS-ISZP]]: `status:` is owned by the status route — the create route
+  // refuses it out of band (`out_of_band_status_write`). The DEFAULT initial
+  // value is not a transition (the server seeds `open` itself), so it is
+  // dropped here for every disk-template-derived body (research stub,
+  // diagnose, epic/task stubs). Any OTHER value is deliberately left in so the
+  // server refuses it loudly rather than this client silently downgrading it.
+  if (isDefaultInitialStatus(cleanedFm.status)) delete cleanedFm.status;
+  const requestBody = {
+    type: type.trim(),
+    name: name.trim(),
+    ...(summary ? { summary } : {}),
+    ...(Object.keys(cleanedFm).length > 0 ? { frontmatter: cleanedFm } : {}),
+    ...(typeof body === 'string' ? { body } : {}),
+    ...(actingAgent ? { acting_agent: actingAgent } : {}),
+  };
+
+  // One key per LOGICAL call: the stash below stores THIS key so a replay is the
+  // same create, never a second mint ([[HS-2FQY]]).
+  const createKey = idempotencyKey ?? randomUUID();
+  const createEntry = {
+    op: 'create',
+    kind: 'create',
+    route: '/api/specs',
+    method: 'POST',
+    request_body: requestBody,
+    idempotency_key: createKey,
+    acting_agent: actingAgent,
+  };
+  if (outboxRoot) await drainAndSummarize(outboxRoot, consoleFetch);
+  let result;
+  try {
+    result = await consoleFetch('/api/specs', {
+      method: 'POST',
+      body: requestBody,
+      headers: { 'idempotency-key': createKey },
+      retryOnTimeout: false,
+    });
+  } catch (err) {
+    if (outboxRoot) {
+      const stashed = stashWrite(outboxRoot, {
+        ...createEntry,
+        failure: { status: 0, errorKind: 'network', message: String(err?.message ?? err).slice(0, 500) },
+      });
+      if (stashed) throw deferredError(routeLabel, consoleUrl, stashed, outboxRoot, { attempted: { type: requestBody.type, name: requestBody.name } });
+    }
+    throw cloudWriteFailure(routeLabel, consoleUrl, String(err?.message ?? err), {
+      attempted: { type: requestBody.type, name: requestBody.name },
+      ...outageRequest(noStash, { ok: false, status: 0, errorKind: 'network', error: String(err?.message ?? err) }, createEntry),
+    });
+  }
+  if (!result?.ok) {
+    const stashed = outboxRoot
+      ? stashIfOutage(result, createEntry, outboxRoot)
+      : null;
+    if (stashed) {
+      throw deferredError(routeLabel, result?.url ?? consoleUrl, stashed, outboxRoot, {
+        status: result?.status ?? null,
+        attempted: { type: requestBody.type, name: requestBody.name },
+      });
+    }
+    throw cloudWriteFailure(routeLabel, result?.url ?? consoleUrl, describeResult(result), {
+      status: result?.status ?? null,
+      console_response: result?.body ?? null,
+      attempted: { type: requestBody.type, name: requestBody.name },
+      ...outageRequest(noStash, result, createEntry),
+      ...(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 retrying — a blind retry can mint a duplicate id ([[HS-2FQY]]).',
+          }
+        : {}),
+    });
+  }
+  const spec = result.body?.spec ?? null;
+  const specId = typeof spec?.id === 'string' && spec.id ? spec.id : null;
+  const relPath = spec?.relPath ?? spec?.path ?? null;
+  if (!specId) {
+    throw cloudWriteFailure(
+      routeLabel,
+      result.url ?? consoleUrl,
+      `answered ${result.status} but carried no spec.id — treat the spec as UNCREATED and check the console before retrying`,
+      { status: result.status, console_response: result.body ?? null },
+    );
+  }
+  return {
+    specId,
+    relPath,
+    basename: basenameFromRelPath(relPath) ?? specId,
+    spec,
+    consoleWrite: result.body?.write ?? null,
+    warnings: Array.isArray(result.body?.warnings) ? result.body.warnings : [],
+    consoleUrl: result.url ?? consoleUrl,
+  };
+}
+
+/**
+ * `PUT /api/specs/:id` — replace an existing spec's frontmatter + body.
+ *
+ * The route takes `{ frontmatter: object, body: string }` and answers 404 for
+ * an id it cannot resolve (a real answer: the spec is not in this caller's
+ * vault), which is surfaced here as a distinct `notFound: true` failure so a
+ * caller can tell "unreachable console" from "no such spec".
+ */
+export async function updateSpecViaConsole({
+  consoleFetch,
+  consoleUrl = null,
+  specId,
+  frontmatter,
+  body,
+  routeLabel = null,
+  vaultRoot = null,
+  noStash = false,
+}) {
+  const route = routeLabel ?? `PUT /api/specs/${specId}`;
+  const outboxRoot = noStash ? null : vaultRoot ?? getWriteOutboxRoot();
+  if (typeof consoleFetch !== 'function') {
+    throw cloudWriteFailure(route, consoleUrl, 'no consoleFetch dependency was injected');
+  }
+  if (typeof specId !== 'string' || !specId.trim()) {
+    throw cloudWriteFailure(route, consoleUrl, 'a spec id is required to update through the console');
+  }
+  if (typeof frontmatter !== 'object' || frontmatter === null) {
+    throw cloudWriteFailure(route, consoleUrl, 'PUT /api/specs/:id requires a frontmatter object');
+  }
+  const putPath = `/api/specs/${encodeURIComponent(specId)}`;
+  const putBody = { frontmatter, body: typeof body === 'string' ? body : '' };
+  const updateEntry = {
+    op: 'update',
+    kind: 'update',
+    route: putPath,
+    method: 'PUT',
+    request_body: putBody,
+    spec_id: specId,
+    // The cloud copy this edit was based on; replay refuses (cloud_newer)
+    // when the cloud has moved on since.
+    pre_image_updated: frontmatter?.updated ?? null,
+  };
+  const stashUpdate = (result) => (outboxRoot ? stashIfOutage(result, updateEntry, outboxRoot) : null);
+  if (outboxRoot) await drainAndSummarize(outboxRoot, consoleFetch);
+  let result;
+  try {
+    result = await consoleFetch(putPath, { method: 'PUT', body: putBody });
+  } catch (err) {
+    const stashed = stashUpdate({ ok: false, status: 0, errorKind: 'network', error: String(err?.message ?? err) });
+    if (stashed) throw deferredError(route, consoleUrl, stashed, outboxRoot, { spec_id: specId });
+    throw cloudWriteFailure(route, consoleUrl, String(err?.message ?? err), {
+      spec_id: specId,
+      ...outageRequest(noStash, { ok: false, status: 0, errorKind: 'network', error: String(err?.message ?? err) }, updateEntry),
+    });
+  }
+  if (!result?.ok) {
+    const stashed = stashUpdate(result);
+    if (stashed) throw deferredError(route, result?.url ?? consoleUrl, stashed, outboxRoot, { status: result?.status ?? null, spec_id: specId });
+    throw cloudWriteFailure(route, result?.url ?? consoleUrl, describeResult(result), {
+      status: result?.status ?? null,
+      console_response: result?.body ?? null,
+      spec_id: specId,
+      ...outageRequest(noStash, result, updateEntry),
+      ...(result?.status === 404 ? { notFound: true } : {}),
+    });
+  }
+  const spec = result.body?.spec ?? null;
+  const relPath = spec?.relPath ?? spec?.path ?? null;
+  return {
+    specId: spec?.id ?? specId,
+    relPath,
+    basename: basenameFromRelPath(relPath) ?? spec?.id ?? specId,
+    spec,
+    consoleUrl: result.url ?? consoleUrl,
+  };
+}
+
+/**
+ * `GET /api/specs?type=…` — the cloud twin of a `readdirSync(specs/<folder>)`
+ * scan. The keyset walk itself is {@link walkSpecListPages} (list-tools.mjs),
+ * the dependency-free primitive every other cloud listing in this package
+ * already uses — reused rather than re-implemented so there is exactly one
+ * place that knows the `next_cursor` contract. This wrapper only adds the
+ * `type`/`status`/`tag` filter and the shared failure envelope, so a listing
+ * that fails reads identically to a create or an edit that fails.
+ *
+ * Returns the raw summary rows (`{ id, basename, type, status, … }`) the route
+ * already emits — no reshaping, so callers keep whatever fields they read.
+ */
+export async function listSpecsViaConsole({
+  consoleFetch,
+  consoleUrl = null,
+  type = null,
+  status = null,
+  tag = null,
+  limit = 500,
+  maxPages = 50,
+}) {
+  const routeLabel = `GET /api/specs${type ? `?type=${type}` : ''}`;
+  if (typeof consoleFetch !== 'function') {
+    throw cloudWriteFailure(routeLabel, consoleUrl, 'no consoleFetch dependency was injected');
+  }
+  const params = new URLSearchParams();
+  if (type) params.set('type', type);
+  if (status) params.set('status', status);
+  if (tag) params.set('tag', tag);
+  const query = params.toString();
+  try {
+    return await walkSpecListPages(consoleFetch, `/api/specs${query ? `?${query}` : ''}`, {
+      limit,
+      maxPages,
+    });
+  } catch (err) {
+    throw cloudWriteFailure(routeLabel, consoleUrl, String(err?.message ?? err));
+  }
+}
+
+/**
+ * The cloud twin of `commitWrites` (promotion-helpers.mjs).
+ *
+ * Takes the SAME `{ kind: 'create' | 'update', absPath, content }` descriptors
+ * the disk path takes, so a caller switches paths with one `if` and never
+ * builds two different write plans. Cloud metadata that cannot be derived from
+ * the markdown may ride along on an optional `cloud` property:
+ *   `{ cloud: { type, name, summary, specId } }`.
+ * When absent it is derived from the content's own frontmatter (`type:`,
+ * `name:`, `summary:`, `id:`) — which every vault document already carries.
+ *
+ * Writes run IN ORDER and stop at the first failure. Nothing is rolled back
+ * (the console has no un-create); the returned error names the failing step
+ * and lists the ones that already landed, so the caller reports the real state
+ * rather than implying a clean abort.
+ *
+ * Returns `{ ok: true, results }` where each result is
+ * `{ kind, absPath, specId, basename, relPath }`, or
+ * `{ ok: false, error, completed }` — the same `{ ok }`-shaped verdict
+ * `commitWrites` returns, so callers branch identically.
+ */
+export async function commitWritesViaConsole(writes, { consoleFetch, consoleUrl = null, actingAgent = null, vaultRoot = null } = {}) {
+  const results = [];
+  const outboxRoot = vaultRoot ?? getWriteOutboxRoot();
+  if (outboxRoot && typeof consoleFetch === 'function') await drainAndSummarize(outboxRoot, consoleFetch);
+  for (let i = 0; i < (writes ?? []).length; i++) {
+    const w = writes[i];
+    const { frontmatter, body } = splitRawSpec(w.content);
+    const meta = w.cloud ?? {};
+    try {
+      if (w.kind === 'create') {
+        const type = meta.type ?? frontmatter.type ?? null;
+        const name = meta.name ?? frontmatter.name ?? null;
+        const summary = meta.summary ?? frontmatter.summary ?? null;
+        const created = await createSpecViaConsole({
+          consoleFetch,
+          consoleUrl,
+          type,
+          name,
+          summary,
+          frontmatter,
+          body,
+          actingAgent: meta.actingAgent ?? actingAgent,
+          noStash: true,
+        });
+        results.push({
+          kind: 'create',
+          absPath: w.absPath ?? null,
+          specId: created.specId,
+          basename: created.basename,
+          relPath: created.relPath,
+        });
+      } else if (w.kind === 'update') {
+        const specId =
+          meta.specId ?? frontmatter.id ?? (w.absPath ? basenameFromRelPath(w.absPath) : null);
+        const updated = await updateSpecViaConsole({
+          consoleFetch,
+          consoleUrl,
+          specId,
+          frontmatter,
+          body,
+          noStash: true,
+        });
+        results.push({
+          kind: 'update',
+          absPath: w.absPath ?? null,
+          specId: updated.specId,
+          basename: updated.basename,
+          relPath: updated.relPath,
+        });
+      } else {
+        throw cloudWriteFailure(
+          'commitWritesViaConsole',
+          consoleUrl,
+          `unknown write kind "${w.kind}" (expected "create" | "update")`,
+        );
+      }
+    } catch (err) {
+      err.failed_step = { index: i, kind: w.kind, abs_path: w.absPath ?? null };
+      err.completed_steps = results;
+      // Outage on step i: queue steps i..n-1 as ONE ordered batch (each step keeps
+      // its own idempotency key) so the remainder replays in order.
+      const failedReq = err.outage_request;
+      if (outboxRoot && failedReq) {
+        const steps = [failedReq];
+        for (let j = i + 1; j < writes.length; j++) {
+          const planned = planBatchStep(writes[j], actingAgent);
+          if (!planned) break;
+          steps.push(planned);
+        }
+        if (steps.length === writes.length - i) {
+          const stashed = stashWrite(outboxRoot, {
+            op: 'batch',
+            route: failedReq.route,
+            method: failedReq.method,
+            request_body: null,
+            acting_agent: actingAgent,
+            failure: failedReq.failure,
+            steps,
+            completed_steps: results,
+          });
+          if (stashed) {
+            const deferred = deferredError('commitWritesViaConsole', consoleUrl, stashed, outboxRoot, {
+              status: err.status ?? null,
+              failed_step: err.failed_step,
+              completed_steps: results,
+            });
+            return { ok: false, error: deferred, completed: results, deferred: true };
+          }
+        }
+      }
+      return { ok: false, error: err, completed: results };
+    }
+  }
+  return { ok: true, results };
+}
+
+/** Build a replayable batch step for a write that was never attempted. */
+function planBatchStep(w, actingAgent) {
+  const { frontmatter, body } = splitRawSpec(w.content);
+  const meta = w.cloud ?? {};
+  if (w.kind === 'create') {
+    const type = meta.type ?? frontmatter.type ?? null;
+    const name = meta.name ?? frontmatter.name ?? null;
+    if (!type || !name) return null;
+    const cleaned = stripServerMintedFields(frontmatter);
+    delete cleaned.name;
+    delete cleaned.type;
+    if (isDefaultInitialStatus(cleaned.status)) delete cleaned.status;
+    const summary = meta.summary ?? frontmatter.summary ?? null;
+    const agent = meta.actingAgent ?? actingAgent;
+    return {
+      kind: 'create',
+      route: '/api/specs',
+      method: 'POST',
+      request_body: {
+        type: String(type).trim(),
+        name: String(name).trim(),
+        ...(summary ? { summary } : {}),
+        ...(Object.keys(cleaned).length > 0 ? { frontmatter: cleaned } : {}),
+        body,
+        ...(agent ? { acting_agent: agent } : {}),
+      },
+      idempotency_key: randomUUID(),
+    };
+  }
+  if (w.kind === 'update') {
+    const specId = meta.specId ?? frontmatter.id ?? (w.absPath ? basenameFromRelPath(w.absPath) : null);
+    if (!specId) return null;
+    return {
+      kind: 'update',
+      route: `/api/specs/${encodeURIComponent(specId)}`,
+      method: 'PUT',
+      request_body: { frontmatter, body },
+      spec_id: specId,
+      pre_image_updated: frontmatter?.updated ?? null,
+    };
+  }
+  return null;
+}

package/vendor/heyspex-mcp/config-seed.yaml

@@ -0,0 +1,15 @@
+# .heyspex/config.yaml — HeySpex workflow settings for this vault.
+# Seeded by `hs init` (ADR-0009 §1: the file lives at the VAULT root and is git-tracked).
+# Field reference: specs/protocols/agent-settings-protocol.md. Change values with
+# `hs settings set <key> <value>` or heyspex_settings_set — never by hand.
+
+mvp_mode:
+  enabled: true
+  review_grain: epic
+  review_backlog_never_blocks: true
+
+pricing_tier:
+  tier: free
+
+agent_behaviors:
+  ask_forgiveness_not_permission: true