heyspex 0.1.0

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

@@ -0,0 +1,190 @@
+/**
+ * `heyspex_submit_for_review` — grain-aware build→review close-out via the status API.
+ *
+ * Agents must not hand-edit frontmatter `status:` for close-out; PATCH
+ * `/api/specs/:id/status` is SSOT (coercion, rollup, spec events). [[HS-DIAG-DOSH]]
+ */
+
+import { parseAcceptanceSubsections } from './alignment-gate.mjs';
+import { readMvpModeState } from './mvp-mode.mjs';
+import { isBelowReviewLevel, reviewLevelForGrain } from './review-rollup.mjs';
+
+const TRACKABLE_KINDS = new Set(['task', 'epic', 'milestone', 'diagnose', 'review']);
+const NON_CLOSE_KINDS = new Set(['research', 'capture', 'memory-lesson', 'memory-decision', 'memory-reference', 'memory-ui-pattern', 'protocol']);
+
+/** Active review level from `.heyspex/config.yaml` MVP block (task when MVP off). */
+export function resolveActiveReviewLevel(vaultRoot) {
+  const mvp = readMvpModeState(vaultRoot);
+  return reviewLevelForGrain(mvp?.review_grain);
+}
+
+/** 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);
+}
+
+/**
+ * Post-close vault steps still required after the status API flip (HS-REV vs seed).
+ */
+export function buildCloseOutGuidance({ specKind, reviewLevel, effectiveStatus, isReviewUnit }) {
+  const grain = reviewLevel;
+  if (isReviewUnit) {
+    return {
+      review_unit: true,
+      effective_status: effectiveStatus,
+      hs_rev: 'required',
+      review_back_link: 'required',
+      change_log: 'required',
+      summary:
+        `Review unit at ${grain} grain — append change-log, file HS-REV companion, add ## Review back-link (session-close-protocol steps 2–4).`,
+    };
+  }
+  return {
+    review_unit: false,
+    effective_status: effectiveStatus,
+    hs_rev: 'skip',
+    review_back_link: 'skip',
+    change_log: 'review_seed_only',
+    summary:
+      `Below ${grain} review grain — no per-spec HS-REV. Append a one-line review/roll-up seed to ## Change log only (MVP milestone or steady-state epic grain).`,
+  };
+}
+
+function findClaimAcProgress(claimsBody, specId) {
+  const claims = Array.isArray(claimsBody?.claims) ? claimsBody.claims : [];
+  const hit = claims.find((c) => String(c?.specId ?? c?.spec_id ?? '') === specId);
+  if (!hit) return { found: false, acProgress: undefined };
+  const ac =
+    typeof hit.acProgress === 'number'
+      ? hit.acProgress
+      : typeof hit.ac_progress === 'number'
+        ? hit.ac_progress
+        : undefined;
+  return { found: true, acProgress: ac };
+}
+
+/**
+ * @param {{ vaultRoot: string, consoleFetch: Function, postClaimEndpoint?: Function, args?: Record<string, unknown> }} ctx
+ */
+export async function executeSubmitForReview({ vaultRoot, consoleFetch, postClaimEndpoint, args = {} }) {
+  const specId = typeof args.spec_id === 'string' ? args.spec_id.trim() : '';
+  if (!specId) {
+    return { error: 'INVALID_ARGS', message: 'spec_id is required' };
+  }
+
+  const skipAcCheck = args.skip_ac_check === true;
+  const releaseClaim = args.release_claim !== false;
+
+  const specRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`);
+  if (!specRes.ok) {
+    return {
+      error: 'SPEC_FETCH_FAILED',
+      message: `GET /api/specs/${specId} returned ${specRes.status}`,
+      status: specRes.status,
+      console_response: specRes.body,
+    };
+  }
+
+  const spec = specRes.body?.spec ?? null;
+  if (!spec) {
+    return { error: 'NOT_FOUND', message: `Spec ${specId} not found` };
+  }
+
+  const specKind = String(spec.type ?? spec.frontmatter?.type ?? '').toLowerCase();
+  if (NON_CLOSE_KINDS.has(specKind)) {
+    return {
+      error: 'NOT_CLOSEABLE',
+      message: `${specId} has type "${specKind}" — research/memory/protocol specs do not participate in build→review close-out.`,
+    };
+  }
+  if (!TRACKABLE_KINDS.has(specKind)) {
+    return {
+      error: 'UNKNOWN_KIND',
+      message: `${specId} has unrecognized type "${specKind}" — cannot submit for review.`,
+    };
+  }
+
+  const reviewLevel = resolveActiveReviewLevel(vaultRoot);
+  const isReviewUnit = !isBelowReviewLevel(specKind, reviewLevel);
+  const criteriaCount = countAcceptanceCriteria(spec.body);
+
+  let claimInfo = { found: false, acProgress: undefined };
+  const claimsRes = await consoleFetch('/api/control/active-claims');
+  if (claimsRes.ok) {
+    claimInfo = findClaimAcProgress(claimsRes.body, specId);
+  }
+
+  if (!skipAcCheck && criteriaCount > 0) {
+    const progress = claimInfo.found ? claimInfo.acProgress : undefined;
+    if (progress === undefined || progress < criteriaCount) {
+      return {
+        error: 'AC_PROGRESS_INCOMPLETE',
+        message:
+          `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,
+        claim_found: claimInfo.found,
+      };
+    }
+  }
+
+  const currentStatus = String(spec.status ?? spec.frontmatter?.status ?? '').toLowerCase();
+  if (currentStatus === 'closed') {
+    return {
+      error: 'ALREADY_CLOSED',
+      message: `${specId} is already closed.`,
+      spec_id: specId,
+    };
+  }
+
+  const statusRes = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}/status`, {
+    method: 'PATCH',
+    body: { status: 'in_review' },
+  });
+
+  if (!statusRes.ok) {
+    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' },
+    };
+  }
+
+  const transition = statusRes.body ?? {};
+  const effectiveStatus = String(
+    transition.spec?.frontmatter?.status ?? transition.spec?.status ?? 'in_review',
+  ).toLowerCase();
+  const coercedTo = transition.coerced_to ?? transition.coercedTo ?? null;
+
+  let claimReleased;
+  if (releaseClaim && typeof postClaimEndpoint === 'function') {
+    const rel = await postClaimEndpoint('DELETE', specId);
+    claimReleased = rel.ok;
+  }
+
+  const guidance = buildCloseOutGuidance({
+    specKind,
+    reviewLevel,
+    effectiveStatus,
+    isReviewUnit,
+  });
+
+  return {
+    spec_id: specId,
+    requested_status: 'in_review',
+    effective_status: effectiveStatus,
+    coerced_to: coercedTo,
+    review_level: reviewLevel,
+    is_review_unit: isReviewUnit,
+    criteria_count: criteriaCount,
+    ac_progress: claimInfo.acProgress ?? null,
+    rolled_up: transition.rolledUp ?? transition.rolled_up ?? undefined,
+    propagated: transition.propagated ?? undefined,
+    claim_released: claimReleased,
+    close_out: guidance,
+    console_response: transition,
+  };
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Shared `summary:` authoring contract — the single source of truth for how a
+ * coding agent should write a spec's plain-language `summary:` frontmatter field.
+ *
+ * This module is plain ESM with no imports so BOTH ends of the TS/JS boundary can
+ * consume it without drift:
+ *   - the MCP server (`vendor/heyspex-mcp/cli.mjs`) imports it as a sibling `.mjs`
+ *     to surface the authoring prompt inline in the `/hs-next` brief when an
+ *     on-deck spec has no summary yet, and
+ *   - the spex-console app (`spex-console/src/lib/agent-work-prompts.ts`) re-exports it
+ *     through `MISSING_FIELD_CONTRACTS.summary` / `buildFieldFillInPrompt`, the
+ *     contract its detail-drawer "fill in missing field" buttons already use.
+ *
+ * It MUST live under vendor/ (not spex-console/) because the MCP server is a separate
+ * process that must never import from spex-console/. Keeping one copy here eliminates
+ * the contract-drift class between the two app surfaces.
+ *
+ * The CANONICAL authoring procedure lives in the vault at
+ * `specs/protocols/spec-summary-authoring.md` (HS-PROTO-spec-summary-authoring),
+ * fetchable via `heyspex_get_procedure({ name: "spec-summary-authoring" })`. The
+ * `SUMMARY_CONTRACT` below is a SNAPSHOT of that procedure's "The contract" section so
+ * the generated prompt is self-contained; the prompt also tells the agent to fetch the
+ * latest version. When the procedure changes, update this snapshot in the same change so
+ * the two never drift. Wording policy is owned by
+ * [[HS-EPIC-Q3HK-spec-frontmatter-summary-field-policy-an]] /
+ * [[HS-TASK-W8FN-spec-summary-schema-and-protocol-docs]].
+ */
+
+/**
+ * The contract a filled-in `summary:` value must satisfy. Markdown bullet lines —
+ * rendered under a "What good looks like" heading in the authoring prompt.
+ */
+/** Kinds that must carry `summary:` when filed via `heyspex_file_spec` / POST /api/specs. */
+export const SUMMARY_REQUIRED_FILE_SPEC_TYPES = new Set(['milestone', 'epic', 'task']);
+
+const SUMMARY_AUTHORING_MOMENT = {
+  milestone:
+    'in the planning phase when the milestone is filed (with epics — never alongside tasks)',
+  epic:
+    'in the planning phase when the epic is filed (with milestones — never alongside tasks)',
+  task:
+    "from the What's Next Launch `/hs-next` breakdown only — not during plan ingest and never co-filed with epics",
+};
+
+/**
+ * MCP hard-block payload when `heyspex_file_spec` omits `summary` for milestone/epic/task.
+ * @param {string} type
+ */
+export function buildSummaryRequiredMcpError(type) {
+  const moment =
+    SUMMARY_AUTHORING_MOMENT[type] ||
+    'at the same time as the rest of the spec is authored';
+  return {
+    error: 'summary_required',
+    message: `type "${type}" requires a plain-language \`summary\` ${moment} — pass the \`summary\` parameter (or frontmatter.summary) per spec-summary-authoring. Fetch the contract: heyspex_get_procedure({ name: "spec-summary-authoring" }).`,
+    procedure: 'spec-summary-authoring',
+  };
+}
+
+/**
+ * Soft API warning when POST /api/specs creates milestone/epic/task without summary.
+ * @param {string} type
+ */
+export function buildSummaryMissingApiWarning(type) {
+  const moment =
+    SUMMARY_AUTHORING_MOMENT[type] ||
+    'when the spec is authored';
+  return {
+    code: 'summary_missing',
+    message: `type "${type}" was filed without a plain-language \`summary:\` — author one ${moment} per spec-summary-authoring (heyspex_get_procedure({ name: "spec-summary-authoring" })).`,
+    procedure: 'spec-summary-authoring',
+  };
+}
+
+/**
+ * Render `summary:` as a YAML block scalar for hand-built frontmatter writers.
+ * @param {string} summary
+ * @returns {string|null}
+ */
+export function formatSummaryFrontmatterField(summary) {
+  const trimmed = String(summary || '').trim();
+  if (!trimmed) return null;
+  const lines = trimmed.split(/\r?\n/);
+  return `summary: |\n${lines.map((l) => `  ${l}`).join('\n')}`;
+}
+
+/**
+ * Resolve a non-empty summary from a top-level field and/or nested override.
+ * @param {unknown} topLevel
+ * @param {unknown} [alt]
+ * @returns {string|null}
+ */
+export function resolveAuthoredSummaryValue(topLevel, alt) {
+  const top = typeof topLevel === 'string' ? topLevel.trim() : '';
+  const nested = typeof alt === 'string' ? alt.trim() : '';
+  return top || nested || null;
+}
+
+export const SUMMARY_CONTRACT = `- The **opening sentence** must be ONE complete, standalone sentence (target ≤160 chars) — list rows and cards render only this sentence.
+- **If this spec has a parent** (a task's parent epic, an epic's parent milestone): the opening sentence must convey two things in one plain sentence — what THIS spec delivers (the *what*) AND the parent's goal it serves (the *why*). A reader should grasp both from that one sentence. Put them in whichever order reads naturally when you say it out loud — often the easiest is the plain action first, then the goal it serves. Do NOT use a rigid "So that …, this …" template, and do NOT stack a long purpose clause in front of the subject before the reader knows what the thing is.
+- **If this spec has no parent** (a top-level milestone): the opening sentence is a standalone, plain-language summary of the spec itself.
+- The **full value** may add a sentence or two of nuance/context after the opening (target ≤400 chars total).
+- Write the WHOLE summary in plain, everyday language a twelve-year-old who has never heard of this project could understand — including the parent's goal. No project-invented jargon anywhere; no unnecessary tech/AI words (e.g. "moat", "seam", "wedge"); no examples, metaphors, or analogies. Only reach for a technical or project term when there is genuinely no plain word for the thing.
+- Write it as a YAML block scalar (\`summary: |\`) so multi-line prose stays readable.
+- Derive this spec's contribution from its own body and the parent's goal from the parent context provided — do not invent scope that isn't in the files.
+- **This is a snapshot of the canonical summary-authoring procedure.** Before writing, fetch the authoritative, latest version and follow it if it has changed: \`heyspex_get_procedure({ name: "spec-summary-authoring" })\` (or read \`specs/protocols/spec-summary-authoring.md\`). Field policy: [[HS-EPIC-Q3HK-spec-frontmatter-summary-field-policy-an]] / [[HS-TASK-W8FN-spec-summary-schema-and-protocol-docs]].`;
+
+/**
+ * Build a deterministic prompt instructing a coding agent to add a missing
+ * `summary:` frontmatter field to a named spec. Mirrors the structure of the
+ * generic `buildFieldFillInPrompt` in spex-console, specialized to `summary` (the only
+ * registered field contract today).
+ *
+ * When `parent` is supplied (the spec's immediate parent — a task's epic, an epic's
+ * milestone), the prompt instructs the agent to fuse the parent's goal into the opening
+ * sentence so the summary reads in context of the work it serves. When `parent` is null
+ * (a top-level milestone) the prompt asks for a standalone summary of the spec itself.
+ *
+ * @param {{ specId: string, name: string, type: string, relPath: string,
+ *   parent?: { id: string, kind?: string, title?: string, goal?: string|null, relPath?: string|null } | null }} input
+ * @returns {string}
+ */
+export function buildSummaryFillInPrompt({ specId, name, type, relPath, parent = 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${parent.relPath ? ` — open \`${parent.relPath}\` and read its \`## Goal\` / body` : ''} 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 readStep = parent && parent.id
+    ? `1. Open \`${relPath}\` and read the spec body to understand its scope, and review the parent context above so your opening sentence carries the parent's goal.`
+    : `1. Open \`${relPath}\` and read the spec body to understand its scope.`;
+  return `You are a coding agent working in the HeySpex workflow-protocol repository. The system of record is the git-tracked markdown vault under specs/.
+
+## Goal
+The vault spec **${specId}** (${name}) is missing a \`summary:\` frontmatter field. Add it.
+
+## Target spec
+- **Spec ID:** ${specId}
+- **Title:** ${name}
+- **Entity type:** ${type}
+- **Vault path:** ${relPath}
+- **Missing field:** \`summary\`${parentBlock}
+
+## What good looks like
+${SUMMARY_CONTRACT}
+
+## What to do
+${readStep}
+2. Add a \`summary:\` field to the YAML frontmatter that satisfies the contract above. Do **not** modify any other frontmatter field or the body.
+3. Keep frontmatter valid YAML and preserve the existing field ordering/style of sibling specs.
+
+Make only this one change; ask only if the spec body is too thin to summarize honestly.`;
+}

package/vendor/heyspex-mcp/test-helpers.mjs

@@ -0,0 +1,43 @@
+/**
+ * Shared test helpers for the vendor MCP round-trip suites.
+ */
+
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Mirror into a temp vault every real-repo file that
+ * `scripts/validate-vault-ids.mjs` needs to run in isolation.
+ *
+ * The validator resolves the rule set from `scripts/`'s sibling spex-console module
+ * `spex-console/src/lib/indexer/vault-rules.mjs` via a path relative to its OWN
+ * location (the VRUL shared-rule-engine seam — one rule set, two consumers).
+ * When a test copies only `scripts/` into a temp dir and runs the copied script,
+ * that relative import resolves to `<temp>/spex-console/src/lib/indexer/vault-rules.mjs`
+ * — which must exist or the import dangles with MODULE_NOT_FOUND. `vault-rules.mjs`
+ * additionally imports its sibling `vault-naming-rules.generated.mjs` (the ZGWR
+ * id-suffix-shape rule, compiled from protocol frontmatter), so that file must be
+ * mirrored too or the engine import dangles.
+ *
+ * Single source of truth: the next dependency the validator grows is a one-line
+ * add here, not a silent breakage in every round-trip test.
+ *
+ * @param {string} repoRoot Absolute path to the real repo root.
+ * @param {string} root Absolute path to the temp vault being assembled.
+ */
+export function mirrorValidatorDeps(repoRoot, root) {
+  cpSync(join(repoRoot, 'scripts'), join(root, 'scripts'), { recursive: true });
+
+  const indexerRel = join('spex-console', 'src', 'lib', 'indexer');
+  mkdirSync(join(root, indexerRel), { recursive: true });
+  for (const file of [
+    'vault-rules.mjs',
+    'vault-naming-rules.generated.mjs',
+    // validate-vault-ids.mjs imports handoff-envelope.mjs (split/defer lineage rule).
+    'handoff-envelope.mjs',
+  ]) {
+    const rel = join(indexerRel, file);
+    const src = join(repoRoot, rel);
+    if (existsSync(src)) cpSync(src, join(root, rel));
+  }
+}