heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/submit-for-review.mjs

@@ -5,7 +5,8 @@
  * `/api/specs/:id/status` is SSOT (coercion, rollup, spec events). [[HS-DIAG-DOSH]]
  */
 
-import { parseAcceptanceSubsections } from './alignment-gate.mjs';
+import { extractSection, hasHeading, parseAcceptanceSubsections } from './alignment-gate.mjs';
+import { gatherCloseBranchReport } from './close-branch-report.mjs';
 import { readMvpModeState } from './mvp-mode.mjs';
 import { isBelowReviewLevel, reviewLevelForGrain } from './review-rollup.mjs';
 
@@ -18,12 +19,87 @@ export function resolveActiveReviewLevel(vaultRoot) {
   return reviewLevelForGrain(mvp?.review_grain);
 }
 
+const REVIEW_LEVELS = new Set(['task', 'epic', 'milestone']);
+
+/**
+ * Reconcile the grain this machine read with the grain the console reports it
+ * gated under ([[HS-A53F]]). The console's `review_level` wins when present —
+ * the status route decides the coercion, so its grain is the one that produced
+ * `effective_status`; the client's own read is kept beside it as
+ * `client_review_level` and the two are compared explicitly. An older console
+ * that reports no grain leaves the client's value in place (`source: client`).
+ */
+export function reviewLevelReport(clientReviewLevel, consoleBody) {
+  const serverLevel = consoleBody?.review_level;
+  const hasServer = typeof serverLevel === 'string' && REVIEW_LEVELS.has(serverLevel);
+  const reviewLevel = hasServer ? serverLevel : clientReviewLevel;
+  return {
+    review_level: reviewLevel,
+    review_level_source: hasServer ? (consoleBody?.review_level_source ?? 'server') : 'client',
+    client_review_level: clientReviewLevel,
+    review_level_mismatch: hasServer && serverLevel !== clientReviewLevel,
+  };
+}
+
 /** Count acceptance criteria the same way the close-out gate expects (flat bullets). */
 export function countAcceptanceCriteria(body) {
   const { sections } = parseAcceptanceSubsections(body ?? '');
   return sections.reduce((n, s) => n + (s.bullets?.length ?? 0), 0);
 }
 
+// Section anchors, mirrored from `parseAcceptanceSubsections` (alignment-gate.mjs)
+// so the checkbox reader below looks at EXACTLY the criteria that function counts.
+// The regexes are duplicated rather than imported because they are module-private
+// there; `submit-for-review.test.mjs` pins the two against each other over the
+// shared fixtures, so a drift is a red test rather than a silent disagreement.
+const ACCEPTANCE_HEADING_TITLE = /^acceptance(?:\s+criteria)?$/i;
+const ACCEPTANCE_HEADING_TITLE_ANY = /^acceptance/i;
+const DONE_WHEN_HEADING_TITLE_ALIAS = /^done\s+when\b/i;
+// Group 1 is the checkbox content when the item renders one; undefined otherwise.
+const CHECKBOX_LIST_ITEM = /^\s*(?:[-*]\s+(?:\[([ xX])\]\s+)?|\d+[.)]\s+)(.+?)\s*$/;
+
+/**
+ * Read the acceptance criteria's rendered checkboxes as REAL STATE
+ * ([[HS-LBNJ-6AT2-DIAG]] AC3).
+ *
+ * Before this, `[ ]` and `[x]` were matched and stripped identically by every
+ * parser on both runtimes — only a COUNT survived — so "progress" was always the
+ * agent's self-reported `acProgress` integer and never the document. A spec could
+ * render every box unchecked and still pass the AC gate. A rendered `- [ ]` that
+ * no code reads is worse than no checkbox at all, because every human and agent
+ * reads it as a verification signal.
+ *
+ * Returns `{ present, total, checked, unchecked }` where `unchecked` lists the
+ * 1-based positions still showing `[ ]`. `present: false` (no criterion renders a
+ * box — the 241 specs using numbered criteria) means the caller keeps its prior
+ * behavior exactly: this is additive, not a new requirement on every spec.
+ */
+export function readAcceptanceCheckboxes(body) {
+  const text = body ?? '';
+  let section = extractSection(text, ACCEPTANCE_HEADING_TITLE);
+  if (!section && !hasHeading(text, ACCEPTANCE_HEADING_TITLE_ANY)) {
+    section = extractSection(text, DONE_WHEN_HEADING_TITLE_ALIAS);
+  }
+  if (!section) return { present: false, total: 0, checked: 0, unchecked: [] };
+
+  let index = 0;
+  let total = 0;
+  let checked = 0;
+  const unchecked = [];
+  for (const line of section.split(/\r?\n/)) {
+    const m = line.match(CHECKBOX_LIST_ITEM);
+    if (!m || !m[2].trim()) continue;
+    index += 1;
+    // An item with no checkbox makes no claim either way — it can neither
+    // satisfy nor block the gate, so it is counted as a criterion but not as a box.
+    if (m[1] === undefined) continue;
+    total += 1;
+    if (m[1].toLowerCase() === 'x') checked += 1;
+    else unchecked.push(index);
+  }
+  return { present: total > 0, total, checked, unchecked };
+}
+
 /**
  * Post-close vault steps still required after the status API flip (HS-REV vs seed).
  */
@@ -67,7 +143,13 @@ function findClaimAcProgress(claimsBody, specId) {
 /**
  * @param {{ vaultRoot: string, consoleFetch: Function, postClaimEndpoint?: Function, args?: Record<string, unknown> }} ctx
  */
-export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClaimEndpoint, args = {} }) {
+export async function executeSubmitForReview({
+  vaultRoot,
+  consoleFetch,
+  postClaimEndpoint,
+  args = {},
+  gatherBranchReport = gatherCloseBranchReport,
+}) {
   const specId = typeof args.spec_id === 'string' ? args.spec_id.trim() : '';
   if (!specId) {
     return { error: 'INVALID_ARGS', message: 'spec_id is required' };
@@ -75,6 +157,12 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
 
   const skipAcCheck = args.skip_ac_check === true;
   const releaseClaim = args.release_claim !== false;
+  // Historical token calibration (HS-HBD2): forward the caller's real
+  // context-window spend, when known, so the console pairs it with the
+  // pre-build estimate on the build-complete spec event. Only a genuine
+  // finite number is forwarded — the console PATCH route is the source of
+  // truth for range validation (>= 0), this just avoids sending junk types.
+  const hasActualTokens = typeof args.actual_tokens === 'number' && Number.isFinite(args.actual_tokens);
 
   const specRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
   if (!specRes.ok) {
@@ -115,8 +203,28 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
     claimInfo = findClaimAcProgress(claimsRes.body, specId);
   }
 
+  const checkboxes = readAcceptanceCheckboxes(spec.body);
+
   if (!skipAcCheck && criteriaCount > 0) {
     const progress = claimInfo.found ? claimInfo.acProgress : undefined;
+    // Checkbox-authoritative ([[HS-LBNJ-6AT2-DIAG]] AC3): where the spec renders
+    // criteria checkboxes, THEY are the state — an unchecked box refuses the
+    // hand-off no matter what the self-reported integer says. Where it renders
+    // none, the acProgress rule below is unchanged.
+    if (checkboxes.present && checkboxes.unchecked.length > 0) {
+      return {
+        error: 'AC_CHECKBOXES_UNCHECKED',
+        message:
+          `Acceptance criteria ${checkboxes.unchecked.join(', ')} are still rendered unchecked ` +
+          `(${checkboxes.checked} of ${checkboxes.total} boxes ticked in ${specId}). ` +
+          `Tick the boxes you actually verified — the document is the record, not the progress count — ` +
+          `or pass skip_ac_check: true with a reason in notes.`,
+        criteria_count: criteriaCount,
+        ac_progress: progress ?? null,
+        checkboxes,
+        claim_found: claimInfo.found,
+      };
+    }
     if (progress === undefined || progress < criteriaCount) {
       return {
         error: 'AC_PROGRESS_INCOMPLETE',
@@ -124,6 +232,7 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
           `Acceptance criteria progress is ${progress ?? 'unknown'} of ${criteriaCount}. Call heyspex_report_progress after each criterion, or pass skip_ac_check: true with a reason in notes.`,
         criteria_count: criteriaCount,
         ac_progress: progress ?? null,
+        checkboxes,
         claim_found: claimInfo.found,
       };
     }
@@ -140,16 +249,32 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
 
   const statusRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}/status`, {
     method: 'PATCH',
-    body: { status: 'in_review' },
+    body: {
+      status: 'in_review',
+      ...(hasActualTokens ? { actual_tokens: args.actual_tokens } : {}),
+    },
   });
 
   if (!statusRes.ok) {
+    // The server names the grain it gated under ([[HS-A53F]]); put it beside the
+    // grain THIS machine read so a 409 under a disagreeing grain is legible as a
+    // resolver mismatch, not as "the agent tried to close".
+    const grainReport = reviewLevelReport(reviewLevel, statusRes.body);
     return {
       error: 'STATUS_PATCH_FAILED',
       message: `PATCH /api/specs/${specId}/status returned ${statusRes.status}`,
       status: statusRes.status,
       console_response: statusRes.body,
       attempted: { requested_status: 'in_review' },
+      ...grainReport,
+      ...(grainReport.review_level_mismatch
+        ? {
+            hint:
+              `This machine's config.yaml says review_grain "${reviewLevel}" but the console ` +
+              `decided "${grainReport.review_level}" (source: ${grainReport.review_level_source}). ` +
+              `The server is authoritative; align the cloud setting via PUT /api/mvp-mode { review_grain }.`,
+          }
+        : {}),
     };
   }
 
@@ -158,6 +283,11 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
     transition.spec?.frontmatter?.status ?? transition.spec?.status ?? 'in_review',
   ).toLowerCase();
   const coercedTo = transition.coerced_to ?? transition.coercedTo ?? null;
+  const grainReport = reviewLevelReport(reviewLevel, transition);
+  // The SERVER's grain drives the close-out guidance when it was reported — the
+  // server is what actually coerced (or did not coerce) the status.
+  const effectiveReviewLevel = grainReport.review_level;
+  const effectiveIsReviewUnit = !isBelowReviewLevel(specKind, effectiveReviewLevel);
 
   let claimReleased;
   if (releaseClaim && typeof postClaimEndpoint === 'function') {
@@ -167,20 +297,33 @@ export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClai
 
   const guidance = buildCloseOutGuidance({
     specKind,
-    reviewLevel,
+    reviewLevel: effectiveReviewLevel,
     effectiveStatus,
-    isReviewUnit,
+    isReviewUnit: effectiveIsReviewUnit,
   });
 
+  // Name the branch each half of the session landed on, and whether they
+  // match ([[HS-PPX7-CWPX-TASK-session-close-names-the-branch-each]]).
+  // Best-effort: a failure here never blocks the close-out.
+  try {
+    const report = await gatherBranchReport({ consoleFetch });
+    guidance.branch_report = report;
+  } catch {
+    guidance.branch_report = { status: 'unknown', matches: false, lines: ['Branch report unavailable.'] };
+  }
+
   return {
     spec_id: specId,
     requested_status: 'in_review',
     effective_status: effectiveStatus,
     coerced_to: coercedTo,
-    review_level: reviewLevel,
-    is_review_unit: isReviewUnit,
+    ...grainReport,
+    is_review_unit: effectiveIsReviewUnit,
     criteria_count: criteriaCount,
     ac_progress: claimInfo.acProgress ?? null,
+    // Reported on success too, so a caller can see WHICH signal cleared the gate
+    // — the document's boxes or the unverified self-report count.
+    checkboxes,
     rolled_up: transition.rolledUp ?? transition.rolled_up ?? undefined,
     propagated: transition.propagated ?? undefined,
     claim_released: claimReleased,

package/vendor/heyspex-mcp/summary-contract.mjs

@@ -160,3 +160,108 @@ ${readStep}
 
 Make only this one change; ask only if the spec body is too thin to summarize honestly.`;
 }
+
+/** Target lengths from the contract above — soft, surfaced as warnings by the writer. */
+export const SUMMARY_OPENING_SENTENCE_TARGET_CHARS = 160;
+export const SUMMARY_TOTAL_TARGET_CHARS = 400;
+
+/**
+ * Validate an authored `summary` value BEFORE it is written anywhere (the
+ * console row via `heyspex_author_summary`, or a vault file). One validator
+ * for both destinations so the cloud write is held to exactly the rules the
+ * on-disk `summary: |` block is. Pure.
+ *
+ * Hard failures (nothing is written): not a string, empty after trim, a
+ * pasted YAML field (`summary: |` / `summary:` prefix — the writer adds the
+ * field itself), or a frontmatter fence. Soft findings come back as
+ * `warnings` — the contract's ≤160 / ≤400 targets are targets, not gates.
+ *
+ * @param {unknown} raw
+ * @returns {{ ok: true, summary: string, warnings: string[] } | { ok: false, error: string, message: string }}
+ */
+export function validateAuthoredSummary(raw) {
+  if (typeof raw !== 'string') {
+    return { ok: false, error: 'INVALID_SUMMARY', message: '`summary` must be a string of plain-language prose.' };
+  }
+  const normalized = raw.replace(/\r\n?/g, '\n').trim();
+  if (!normalized) {
+    return { ok: false, error: 'INVALID_SUMMARY', message: '`summary` is empty — author the plain-language summary per spec-summary-authoring, then pass it.' };
+  }
+  if (/^summary\s*:/i.test(normalized)) {
+    return {
+      ok: false,
+      error: 'INVALID_SUMMARY',
+      message: 'Pass the summary PROSE only — no `summary:` / `summary: |` YAML prefix. The writer stores it as the frontmatter field itself.',
+    };
+  }
+  if (/^---\s*$/m.test(normalized)) {
+    return { ok: false, error: 'INVALID_SUMMARY', message: '`summary` must not contain a frontmatter fence (`---`).' };
+  }
+  const warnings = [];
+  const opening = (normalized.match(/^[\s\S]*?[.!?](?=\s|$)/) || [normalized])[0].trim();
+  if (opening.length > SUMMARY_OPENING_SENTENCE_TARGET_CHARS) {
+    warnings.push(
+      `opening sentence is ${opening.length} chars (target ≤${SUMMARY_OPENING_SENTENCE_TARGET_CHARS}) — list rows and cards render only this sentence.`,
+    );
+  }
+  if (normalized.length > SUMMARY_TOTAL_TARGET_CHARS) {
+    warnings.push(`summary is ${normalized.length} chars (target ≤${SUMMARY_TOTAL_TARGET_CHARS} total).`);
+  }
+  return { ok: true, summary: normalized, warnings };
+}
+
+/**
+ * Cloud-reliance twin of {@link buildSummaryFillInPrompt}
+ * ([[HS-T41O-NZ8S-DIAG]]): when the console's Neon row is the source of record
+ * (prod / cloud dev-mode reliance, or a spec that exists only in Neon and not
+ * in this machine's vault clone), the agent must NOT edit a vault file — the
+ * console never reads it back. This prompt names the console write instead:
+ * `heyspex_author_summary { spec_id, summary }` → `PUT /api/specs/:id`.
+ * It deliberately carries NO on-disk path and no "open the file" step.
+ *
+ * @param {{ specId: string, name: string, type: string,
+ *   parent?: { id: string, kind?: string, title?: string, goal?: string|null } | null,
+ *   consoleUrl?: string|null }} input
+ * @returns {string}
+ */
+export function buildSummaryConsoleWritePrompt({ specId, name, type, parent = null, consoleUrl = null }) {
+  const parentKind = (parent && parent.kind) || 'parent';
+  const parentBlock =
+    parent && parent.id
+      ? `
+
+## Parent context
+This ${type} rolls up to ${parentKind} **${parent.id}**${parent.title ? ` — ${parent.title}` : ''}.
+${
+  parent.goal && String(parent.goal).trim()
+    ? `Its goal, in the parent's own words:\n> ${String(parent.goal).replace(/\s+/g, ' ').trim()}`
+    : `The parent has no \`summary:\` yet — read its body from the console (\`GET /api/specs/${parent.id}\`, or \`heyspex_next_on_deck { spec_id: "${parent.id}", summary: true }\`) to state the parent's goal in plain words.`
+}
+Your opening sentence MUST fuse that goal with what THIS ${type} delivers toward it, in whichever order reads naturally when said out loud (no rigid "So that …, this …" template, no long purpose clause stacked in front of the subject). Keep it plain enough for a twelve-year-old who's never heard of this project.`
+      : '';
+  const where = consoleUrl ? ` (${consoleUrl})` : '';
+  const toolArgs = `{ spec_id: "${specId}", summary: "<your summary>" }`;
+  return `You are a coding agent working in the HeySpex workflow. This session is CLOUD-reliant: the console's record for the spec${where} is the source of record. Do NOT edit a vault file on disk for this — your clone may not hold the spec, and the console never reads that file back.
+
+## Goal
+The spec **${specId}** (${name}) is missing a \`summary:\` field. Author it, then write it through the console.
+
+## Target spec
+- **Spec ID:** ${specId}
+- **Title:** ${name}
+- **Entity type:** ${type}
+- **Source of record:** the console row (\`GET /api/specs/${specId}\`) — not a file
+- **Missing field:** \`summary\`${parentBlock}
+
+## What good looks like
+${SUMMARY_CONTRACT}
+- For the console write, pass the PROSE only as the \`summary\` argument — no \`summary: |\` YAML wrapper; the console stores it as the frontmatter field.
+
+## What to do
+1. Read the spec's scope from the brief above (or \`GET /api/specs/${specId}\` on the console)${parent && parent.id ? ', and review the parent context above so your opening sentence carries the parent\'s goal' : ''}.
+2. Author a \`summary\` that satisfies the contract above.
+3. Write it through the console: \`heyspex_load_tools { names: ["heyspex_author_summary"] }\` (it is a deferred tool), then \`heyspex_author_summary ${toolArgs}\`. CLI fallback: \`hs mcp call heyspex_author_summary --args '{"spec_id":"${specId}","summary":"<your summary>"}' --json\`. The tool changes ONLY \`summary\` (\`PUT /api/specs/:id\` with the row's other frontmatter and body preserved).
+4. Re-run \`heyspex_next_on_deck { summary: true }\` — the brief now shows the summary and asks to claim.
+
+Make only this one change; ask only if the spec body is too thin to summarize honestly.`;
+}

package/vendor/heyspex-mcp/summary-write-tools.mjs

@@ -0,0 +1,228 @@
+/**
+ * `heyspex_author_summary` — write a spec's plain-language `summary:` field
+ * where the session's source of record actually lives ([[HS-T41O-NZ8S-DIAG]]).
+ *
+ * The `/hs-next` brief's `author_summary_then_claim` phase used to tell every
+ * agent to `Edit` the vault file on disk. In cloud reliance (prod, or dev-mode
+ * `reliance: cloud`) the console's Neon row is the source of record: a spec
+ * filed there may not exist in this machine's clone at all, and a file edit is
+ * never read back. This tool is the write the brief now names there:
+ *
+ *   - `cloud` write mode — `GET /api/specs/:id` for the row's current
+ *     frontmatter + body, set `summary`, `PUT /api/specs/:id` through
+ *     {@link updateSpecViaConsole}. Nothing touches this machine's disk.
+ *   - `local` write mode — the vault file on disk is the source of record, so
+ *     the `summary: |` block scalar is upserted into that file's frontmatter
+ *     (the same shape a hand `Edit` produces); every other field and the body
+ *     are byte-preserved.
+ *
+ * Both destinations run the SAME validator ({@link validateAuthoredSummary})
+ * and change ONLY `summary`. The write mode is resolved ONCE at handler entry
+ * from `resolveVaultWriteMode()` (the write twin of the read tier), exactly as
+ * `handleEditFile` does.
+ *
+ * Transport-free by design: `deps.consoleFetch` / `deps.resolveWriteMode` /
+ * `deps.consoleUrl` are injection seams so tests never open a socket.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { deferredPayloadFromError, updateSpecViaConsole } from './cloud-vault-writes.mjs';
+import { consoleFetch, controlOk } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { getConsoleUrl } from './mcp-config.mjs';
+import { resolveVaultWriteMode } from './read-path.mjs';
+import { formatSummaryFrontmatterField, validateAuthoredSummary } from './summary-contract.mjs';
+import { findSpecFile } from './vault-io.mjs';
+
+export const AUTHOR_SUMMARY_TOOL_NAME = 'heyspex_author_summary';
+
+/** The follow-up every success names, so the agent completes the phase without guessing. */
+const NEXT_STEP = 'Re-run heyspex_next_on_deck { summary: true } — the brief now shows the summary and asks to claim.';
+
+function errorResult(payload) {
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+/**
+ * Upsert `summary` into a raw spec document's YAML frontmatter as a block
+ * scalar (`summary: |`), replacing an existing `summary:` field (single-line
+ * or block/folded scalar) in place, else appending it as the last frontmatter
+ * field. Every other byte — other fields, their order, the body, the file's
+ * line-ending style — is preserved. Pure.
+ *
+ * @param {string} raw
+ * @param {string} summary already validated, non-empty prose
+ * @returns {{ ok: true, raw: string, replaced: boolean } | { ok: false, error: string, message: string }}
+ */
+export function upsertSummaryInRawSpec(raw, summary) {
+  const text = String(raw ?? '');
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== '---') {
+    return { ok: false, error: 'NO_FRONTMATTER', message: 'The spec file has no YAML frontmatter block to add `summary:` to.' };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return { ok: false, error: 'NO_FRONTMATTER', message: 'The spec file\'s frontmatter block is not closed with `---`.' };
+  }
+  const field = formatSummaryFrontmatterField(summary).split('\n');
+
+  let start = -1;
+  for (let i = 1; i < end; i += 1) {
+    if (/^summary\s*:/.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) {
+    const next = [...lines.slice(0, end), ...field, ...lines.slice(end)];
+    return { ok: true, raw: next.join(eol), replaced: false };
+  }
+  // Extent of the existing field: continuation lines are indented (block /
+  // folded scalar bodies) or blank-but-followed-by-indented. Never swallow the
+  // frontmatter fence or the next top-level `key:`.
+  let stop = start + 1;
+  while (stop < end && /^(\s+\S.*|\s*)$/.test(lines[stop])) stop += 1;
+  while (stop > start + 1 && lines[stop - 1].trim() === '') stop -= 1;
+  const next = [...lines.slice(0, start), ...field, ...lines.slice(stop)];
+  return { ok: true, raw: next.join(eol), replaced: true };
+}
+
+/**
+ * Handler for `heyspex_author_summary`.
+ *
+ * @param {string} vaultRoot
+ * @param {{ spec_id?: string, summary?: string }} args
+ * @param {{ consoleFetch?: Function, consoleUrl?: string, resolveWriteMode?: () => Promise<string|null> }} [deps]
+ */
+export async function handleAuthorSummary(vaultRoot, args = {}, deps = {}) {
+  const specId = typeof args.spec_id === 'string' ? args.spec_id.trim() : '';
+  if (!specId) {
+    return errorResult({ error: 'INVALID_ARGS', message: 'spec_id is required (the spec whose `summary:` you authored).' });
+  }
+  const verdict = validateAuthoredSummary(args.summary);
+  if (!verdict.ok) {
+    return errorResult({ error: verdict.error, message: verdict.message, spec_id: specId, written: false });
+  }
+  const { summary, warnings } = verdict;
+
+  let writeMode = 'local';
+  try {
+    writeMode = (await (deps.resolveWriteMode ?? resolveVaultWriteMode)()) ?? 'local';
+  } catch {
+    writeMode = 'local';
+  }
+
+  if (writeMode === 'cloud') {
+    const fetchDep = deps.consoleFetch ?? consoleFetch;
+    const consoleUrl = deps.consoleUrl ?? getConsoleUrl();
+    const read = await fetchDep(`/api/specs/${encodeURIComponent(specId)}`);
+    if (!read?.ok) {
+      return errorResult({
+        error: read?.status === 404 ? 'SPEC_NOT_FOUND' : consoleErrorCode(read, 'CONSOLE_UNREACHABLE_CLOUD_MODE'),
+        message:
+          read?.status === 404
+            ? `Spec ${specId} is not in this caller's vault on the console (${consoleUrl}). NOTHING WAS WRITTEN.`
+            : consoleErrorMessage(read, `GET /api/specs/${specId} returned ${read?.status ?? 'no response'}`),
+        spec_id: specId,
+        write_mode: 'cloud',
+        on_disk: false,
+        written: false,
+        console_url: consoleUrl,
+        ...(read?.body ? { console_response: read.body } : {}),
+      });
+    }
+    const spec = read.body?.spec;
+    if (!spec || typeof spec !== 'object') {
+      return errorResult({
+        error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+        message: `GET /api/specs/${specId} answered without a spec payload — cannot merge \`summary\` safely. NOTHING WAS WRITTEN.`,
+        spec_id: specId,
+        write_mode: 'cloud',
+        on_disk: false,
+        written: false,
+      });
+    }
+    const frontmatter = { ...(spec.frontmatter && typeof spec.frontmatter === 'object' ? spec.frontmatter : {}), summary };
+    const body = typeof spec.body === 'string' ? spec.body : '';
+    const rowId = typeof spec.id === 'string' && spec.id.trim() ? spec.id.trim() : specId;
+    let written;
+    try {
+      written = await updateSpecViaConsole({ consoleFetch: fetchDep, consoleUrl, specId: rowId, frontmatter, body });
+    } catch (err) {
+      const deferred = deferredPayloadFromError(err);
+      if (deferred) {
+        return controlOk({ ...deferred, written: false, spec_id: rowId, summary, write_mode: 'cloud', on_disk: false });
+      }
+      return errorResult({
+        error: err?.notFound ? 'SPEC_NOT_FOUND' : 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+        message: String(err?.message ?? err),
+        spec_id: rowId,
+        write_mode: 'cloud',
+        on_disk: false,
+        written: false,
+      });
+    }
+    return controlOk({
+      written: true,
+      spec_id: written.specId,
+      summary,
+      warnings,
+      write_mode: 'cloud',
+      on_disk: false,
+      route: `PUT /api/specs/${written.specId}`,
+      rel_path: written.relPath,
+      console_url: written.consoleUrl,
+      next: NEXT_STEP,
+    });
+  }
+
+  // Local write mode — the vault file is the source of record.
+  const relPath = findSpecFile(vaultRoot, specId);
+  const absPath = relPath ? join(vaultRoot, relPath) : null;
+  if (!absPath || !existsSync(absPath)) {
+    return errorResult({
+      error: 'SPEC_NOT_FOUND',
+      message: `Spec ${specId} was not found on disk under ${vaultRoot}. NOTHING WAS WRITTEN.`,
+      spec_id: specId,
+      write_mode: 'local',
+      written: false,
+    });
+  }
+  const raw = readFileSync(absPath, 'utf8');
+  const patched = upsertSummaryInRawSpec(raw, summary);
+  if (!patched.ok) {
+    return errorResult({ error: patched.error, message: patched.message, spec_id: specId, file_path: absPath, write_mode: 'local', written: false });
+  }
+  try {
+    writeFileSync(absPath, patched.raw, 'utf8');
+  } catch (err) {
+    return errorResult({
+      error: 'WRITE_FAILED',
+      message: `Failed to write ${absPath}: ${err?.message ?? err}`,
+      spec_id: specId,
+      file_path: absPath,
+      write_mode: 'local',
+      written: false,
+    });
+  }
+  return controlOk({
+    written: true,
+    spec_id: specId,
+    summary,
+    warnings,
+    write_mode: 'local',
+    on_disk: true,
+    file_path: absPath,
+    rel_path: String(relPath).replace(/\\/g, '/'),
+    replaced_existing: patched.replaced,
+    next: NEXT_STEP,
+  });
+}