mandrel 2.58.0 → 2.60.0

package/.agents/scripts/lib/orchestration/model-attribution.js

@@ -1,418 +0,0 @@
-/**
- * model-attribution.js — per-ticket model attribution comments + rollup
- * (Story #2813).
- *
- * Records which Claude model executed a given ticket as a structured comment
- * on that ticket. Epic-level mixes are computed at query time by walking the
- * child tickets' comments — no Epic-scope emission is written.
- *
- * Surface:
- *
- *   - {@link resolveModelIdentity} — pure resolver that picks an identity
- *     from the fallback chain (SDK metadata → env var → 'unknown'
- *     sentinel) and tags the source. Pure: no IO, no Date.now().
- *   - {@link buildModelAttributionPayload} — shape the canonical payload
- *     from a resolved identity + ticketId + timestamp.
- *   - {@link validateModelAttributionPayload} — hand-rolled validator
- *     matching `.agents/schemas/model-attribution.schema.json`. Returns
- *     `{ ok: true }` or `{ ok: false, errors: string[] }`.
- *   - {@link renderModelAttributionBody} — markdown body + fenced JSON
- *     block (same fence convention as the other structured comments in
- *     this repo so the shared `parseFencedJsonComment` can read it back).
- *   - {@link emitModelAttribution} — idempotent upsert against a Task
- *     ticket. Throws on validator failure (no comment written).
- *   - {@link parseModelAttributionComment} — readback helper for the
- *     rollup walker; returns `null` on missing/malformed payloads.
- *   - {@link rollupModelAttribution} — given a Story or Epic ticket id,
- *     walks `getSubTickets`, collects attribution comments, returns
- *     `{ totalChildren, byModel: {...}, missing: N }`.
- */
-
-import { parseFencedJsonComment } from './structured-comment-parser.js';
-import { findStructuredComment, upsertStructuredComment } from './ticketing.js';
-
-export const MODEL_ATTRIBUTION_TYPE = 'model-attribution';
-
-/**
- * Sentinel returned by {@link resolveModelIdentity} when neither the SDK
- * metadata nor the runtime env var supplied a model id. Exported so tests
- * and downstream consumers can compare without re-spelling the literal.
- */
-export const UNKNOWN_MODEL_ID = 'unknown';
-
-/**
- * Env vars consulted as the second-priority resolver source. Listed in
- * priority order — the first one set wins.
- */
-const ENV_VAR_CANDIDATES = Object.freeze(['CLAUDE_MODEL', 'ANTHROPIC_MODEL']);
-
-/**
- * Derive the coarse family label from a canonical model id. Used for the
- * rollup-friendly `family` field. Returns `null` when the id does not
- * match a recognised family pattern (the rollup helper falls back to the
- * full id in that case so unknown models still aggregate distinctly).
- *
- * Recognises Anthropic Claude families: Opus, Sonnet, Haiku.
- *
- * @param {string} id
- * @returns {string | null}
- */
-export function deriveFamily(id) {
-  if (typeof id !== 'string') return null;
-  const lower = id.toLowerCase();
-  if (lower.includes('opus')) return 'Opus';
-  if (lower.includes('sonnet')) return 'Sonnet';
-  if (lower.includes('haiku')) return 'Haiku';
-  return null;
-}
-
-/**
- * Resolve the active model identity using the documented fallback chain:
- *
- *   1. `sdkMetadata.modelId` (or `.model`) when present and non-empty.
- *   2. `CLAUDE_MODEL` / `ANTHROPIC_MODEL` env vars (first non-empty wins).
- *   3. The `UNKNOWN_MODEL_ID` sentinel.
- *
- * Pure: accepts the env bag as an injectable argument so tests can pin
- * the resolver without mutating `process.env`. Production callers default
- * to `process.env`.
- *
- * @param {object} [opts]
- * @param {object|null} [opts.sdkMetadata] — SDK response metadata.
- * @param {Record<string, string|undefined>} [opts.env=process.env]
- * @returns {{ id: string, family: string|null, source: 'sdk-metadata'|'env'|'unknown', sdkMetadata?: object }}
- */
-export function resolveModelIdentity(opts = {}) {
-  const { sdkMetadata = null, env = process.env } = opts;
-
-  const sdkId =
-    sdkMetadata && typeof sdkMetadata === 'object'
-      ? (typeof sdkMetadata.modelId === 'string' && sdkMetadata.modelId) ||
-        (typeof sdkMetadata.model === 'string' && sdkMetadata.model) ||
-        null
-      : null;
-  if (sdkId) {
-    return {
-      id: sdkId,
-      family: deriveFamily(sdkId),
-      source: 'sdk-metadata',
-      sdkMetadata,
-    };
-  }
-
-  for (const name of ENV_VAR_CANDIDATES) {
-    const value = env?.[name];
-    if (typeof value === 'string' && value.length > 0) {
-      return {
-        id: value,
-        family: deriveFamily(value),
-        source: 'env',
-      };
-    }
-  }
-
-  return {
-    id: UNKNOWN_MODEL_ID,
-    family: null,
-    source: 'unknown',
-  };
-}
-
-/**
- * Build the canonical payload object from a resolved identity. Separated
- * from {@link emitModelAttribution} so callers (and tests) can shape the
- * payload without triggering the upsert side-effect.
- *
- * @param {{
- *   ticketId: number,
- *   identity: ReturnType<typeof resolveModelIdentity>,
- *   recordedAt?: string,
- * }} args
- * @returns {object}
- */
-export function buildModelAttributionPayload(args) {
-  const { ticketId, identity, recordedAt } = args ?? {};
-  const payload = {
-    kind: MODEL_ATTRIBUTION_TYPE,
-    ticketId,
-    model: identity?.family
-      ? { id: identity.id, family: identity.family }
-      : { id: identity?.id },
-    source: identity?.source,
-    recordedAt: recordedAt ?? new Date().toISOString(),
-  };
-  if (identity?.sdkMetadata && typeof identity.sdkMetadata === 'object') {
-    payload.sdkMetadata = identity.sdkMetadata;
-  }
-  return payload;
-}
-
-const VALID_SOURCES = new Set(['sdk-metadata', 'env', 'unknown']);
-const ISO_8601_RE =
-  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
-
-/**
- * Per-field validators for {@link validateModelAttributionPayload}. Each
- * returns an array of error strings for its field (empty when the field is
- * valid), so the top-level validator collapses to a flat-map over the field
- * list — no per-field branching in the orchestrating body. Story #4075
- * (CLI-orchestration CC reduction): keeps each validator pure and
- * single-responsibility.
- */
-function validateKind(payload) {
-  return payload.kind === MODEL_ATTRIBUTION_TYPE
-    ? []
-    : [`kind must be "${MODEL_ATTRIBUTION_TYPE}"`];
-}
-
-function validateTicketId(payload) {
-  return Number.isInteger(payload.ticketId) && payload.ticketId > 0
-    ? []
-    : ['ticketId must be a positive integer'];
-}
-
-function validateModel(payload) {
-  const { model } = payload;
-  if (!model || typeof model !== 'object' || Array.isArray(model)) {
-    return ['model must be an object'];
-  }
-  const errors = [];
-  if (typeof model.id !== 'string' || model.id.length === 0) {
-    errors.push('model.id must be a non-empty string');
-  }
-  if (
-    model.family !== undefined &&
-    (typeof model.family !== 'string' || model.family.length === 0)
-  ) {
-    errors.push('model.family, when present, must be a non-empty string');
-  }
-  return errors;
-}
-
-function validateSource(payload) {
-  return typeof payload.source === 'string' && VALID_SOURCES.has(payload.source)
-    ? []
-    : [`source must be one of: ${[...VALID_SOURCES].join(', ')}`];
-}
-
-function validateRecordedAt(payload) {
-  return typeof payload.recordedAt === 'string' &&
-    ISO_8601_RE.test(payload.recordedAt)
-    ? []
-    : ['recordedAt must be an ISO-8601 timestamp string'];
-}
-
-function validateSdkMetadata(payload) {
-  const { sdkMetadata } = payload;
-  if (sdkMetadata === undefined) return [];
-  const valid =
-    sdkMetadata !== null &&
-    typeof sdkMetadata === 'object' &&
-    !Array.isArray(sdkMetadata);
-  return valid ? [] : ['sdkMetadata, when present, must be an object'];
-}
-
-const PAYLOAD_FIELD_VALIDATORS = Object.freeze([
-  validateKind,
-  validateTicketId,
-  validateModel,
-  validateSource,
-  validateRecordedAt,
-  validateSdkMetadata,
-]);
-
-/**
- * Hand-rolled validator matching
- * `.agents/schemas/model-attribution.schema.json`. Returns
- * `{ ok: true }` on success, `{ ok: false, errors: string[] }` on
- * failure. The error strings are stable enough to assert against in
- * tests.
- *
- * The codebase does not pull in `ajv` for runtime schema validation
- * (signals + structured comments use hand-rolled shape guards — see
- * `lib/signals/schema.js`). We follow the same pattern here so the
- * schema file stays the documented SSOT and the validator is the
- * runtime gate.
- *
- * @param {unknown} payload
- * @returns {{ ok: true } | { ok: false, errors: string[] }}
- */
-export function validateModelAttributionPayload(payload) {
-  if (
-    payload === null ||
-    typeof payload !== 'object' ||
-    Array.isArray(payload)
-  ) {
-    return { ok: false, errors: ['payload must be a plain object'] };
-  }
-  const errors = PAYLOAD_FIELD_VALIDATORS.flatMap((validate) =>
-    validate(payload),
-  );
-  return errors.length ? { ok: false, errors } : { ok: true };
-}
-
-/**
- * Render the markdown body that gets upserted as the structured comment.
- * Body is a one-line summary followed by the canonical payload inside a
- * fenced ```json``` block so downstream readers can use the shared
- * `parseFencedJsonComment` helper without bespoke parsing.
- *
- * @param {object} payload — already validated.
- * @returns {string}
- */
-export function renderModelAttributionBody(payload) {
-  const id = payload.model?.id ?? UNKNOWN_MODEL_ID;
-  const family = payload.model?.family ? ` (${payload.model.family})` : '';
-  const sourceLabel =
-    payload.source === 'sdk-metadata'
-      ? 'SDK metadata'
-      : payload.source === 'env'
-        ? 'env var'
-        : 'unknown source';
-  const header = `🤖 Model attribution: \`${id}\`${family} · via ${sourceLabel}`;
-  return [header, '', '```json', JSON.stringify(payload, null, 2), '```'].join(
-    '\n',
-  );
-}
-
-/**
- * Emit (idempotently) the model-attribution comment onto a Task ticket.
- * Validates the payload before any IO — a malformed payload throws and
- * writes nothing to the provider.
- *
- * @param {{
- *   provider: import('../ITicketingProvider.js').ITicketingProvider,
- *   ticketId: number,
- *   sdkMetadata?: object|null,
- *   env?: Record<string, string|undefined>,
- *   recordedAt?: string,
- * }} args
- * @returns {Promise<{ payload: object, body: string }>}
- */
-export async function emitModelAttribution(args) {
-  const { provider, ticketId, sdkMetadata, env, recordedAt } = args ?? {};
-  if (!provider || typeof provider.postComment !== 'function') {
-    throw new TypeError(
-      'emitModelAttribution requires a provider with postComment',
-    );
-  }
-  if (!Number.isInteger(ticketId) || ticketId <= 0) {
-    throw new TypeError(
-      'emitModelAttribution requires a positive integer ticketId',
-    );
-  }
-  const identity = resolveModelIdentity({ sdkMetadata, env });
-  const payload = buildModelAttributionPayload({
-    ticketId,
-    identity,
-    recordedAt,
-  });
-  const result = validateModelAttributionPayload(payload);
-  if (!result.ok) {
-    throw new Error(
-      `model-attribution payload failed validation: ${result.errors.join('; ')}`,
-    );
-  }
-  const body = renderModelAttributionBody(payload);
-  await upsertStructuredComment(
-    provider,
-    ticketId,
-    MODEL_ATTRIBUTION_TYPE,
-    body,
-  );
-  return { payload, body };
-}
-
-/**
- * Read back a model-attribution comment from a ticket. Returns the
- * parsed payload, or `null` when the comment is missing or its payload
- * fails validation (malformed payloads are treated as "no attribution"
- * so a single corrupt comment does not poison the whole rollup).
- *
- * @param {{
- *   provider: import('../ITicketingProvider.js').ITicketingProvider,
- *   ticketId: number,
- * }} args
- * @returns {Promise<object|null>}
- */
-export async function parseModelAttributionComment(args) {
-  const { provider, ticketId } = args ?? {};
-  const comment = await findStructuredComment(
-    provider,
-    ticketId,
-    MODEL_ATTRIBUTION_TYPE,
-  );
-  if (!comment) return null;
-  const parsed = parseFencedJsonComment(comment);
-  if (!parsed) return null;
-  const result = validateModelAttributionPayload(parsed);
-  return result.ok ? parsed : null;
-}
-
-/**
- * Walk the immediate child tickets of a parent (e.g. an Epic's Stories),
- * read each child's model-attribution comment (when present), and
- * aggregate per-model counts. Children with no attribution comment are
- * counted under `missing`.
- *
- * Rollup is keyed by `model.family` when present, otherwise by
- * `model.id` so unknown families still aggregate distinctly. The
- * envelope also exposes the per-id breakdown for callers that want a
- * finer-grained view.
- *
- * @param {{
- *   provider: import('../ITicketingProvider.js').ITicketingProvider,
- *   parentId: number,
- * }} args
- * @returns {Promise<{
- *   parentId: number,
- *   totalChildren: number,
- *   missing: number,
- *   byModel: Record<string, number>,
- *   byId: Record<string, number>,
- * }>}
- */
-export async function rollupModelAttribution(args) {
-  const { provider, parentId } = args ?? {};
-  if (!provider || typeof provider.getSubTickets !== 'function') {
-    throw new TypeError(
-      'rollupModelAttribution requires a provider with getSubTickets',
-    );
-  }
-  if (!Number.isInteger(parentId) || parentId <= 0) {
-    throw new TypeError(
-      'rollupModelAttribution requires a positive integer parentId',
-    );
-  }
-  const children = (await provider.getSubTickets(parentId)) ?? [];
-  const byModel = {};
-  const byId = {};
-  let missing = 0;
-  for (const child of children) {
-    const childId = Number(child?.id);
-    if (!Number.isInteger(childId) || childId <= 0) {
-      missing += 1;
-      continue;
-    }
-    const payload = await parseModelAttributionComment({
-      provider,
-      ticketId: childId,
-    });
-    if (!payload) {
-      missing += 1;
-      continue;
-    }
-    const familyKey =
-      payload.model?.family ?? payload.model?.id ?? UNKNOWN_MODEL_ID;
-    const idKey = payload.model?.id ?? UNKNOWN_MODEL_ID;
-    byModel[familyKey] = (byModel[familyKey] ?? 0) + 1;
-    byId[idKey] = (byId[idKey] ?? 0) + 1;
-  }
-  return {
-    parentId,
-    totalChildren: children.length,
-    missing,
-    byModel,
-    byId,
-  };
-}

package/.agents/scripts/lib/orchestration/split-policy-validator.js

@@ -1,188 +0,0 @@
-/**
- * v2 split-policy validator — the plan-time "one-owner-AC" split rejector.
- *
- * Under the v2 default-single split policy (`docs/roadmap.md` § v2.0.0), a
- * plan authors **one Story by default**; it splits into N>1 Stories only when
- * the pieces have near-zero overlap or sit across an architectural seam. This
- * validator is the deterministic guardrail on that policy: **every acceptance
- * criterion must belong to exactly one Story.** An identical AC appearing in
- * two Stories is evidence the split coupled what should have stayed one Story,
- * so the plan is refused rather than reconciled at delivery time (there is no
- * epic-level acceptance reconcile in v2).
- *
- * Scope of the deterministic check:
- *   - **Cross-Story duplication** (always): the same normalized AC text must
- *     not appear in more than one Story.
- *   - **Full coverage** (optional, when a plan-level `acceptance` manifest is
- *     supplied): every manifest AC is claimed by exactly one Story, and no
- *     Story claims an AC absent from the manifest.
- *
- * Semantic overlap between differently-worded ACs is **not** caught here — it
- * is a gate-#2 review call. This validator only sees identical (normalized)
- * text, keeping it deterministic and false-positive-free.
- *
- * Normalization for comparison: trim, collapse internal whitespace, and
- * lower-case. Reporting always uses the first-seen original text.
- */
-
-/**
- * Normalize an acceptance string for equality comparison. Trims, collapses
- * runs of whitespace to a single space, and lower-cases. Non-strings and
- * empty/whitespace-only strings normalize to `null` (ignored).
- *
- * @param {unknown} ac
- * @returns {string | null}
- */
-export function normalizeAcceptance(ac) {
-  if (typeof ac !== 'string') return null;
-  const norm = ac.trim().replace(/\s+/g, ' ').toLowerCase();
-  return norm === '' ? null : norm;
-}
-
-/**
- * @typedef {object} StorySlice
- * @property {string} [id]        Story identifier for reporting (slug or #id).
- * @property {string} [slug]      Alternate identifier (used when `id` absent).
- * @property {string[]} acceptance Acceptance criteria this Story claims.
- */
-
-/**
- * @typedef {object} SplitPolicyViolation
- * @property {'cross-story-duplicate'|'orphan-ac'|'unclaimed-manifest-ac'} kind
- * @property {string} acceptance The original (first-seen) AC text.
- * @property {string[]} [stories] Story ids sharing a duplicated AC (`cross-story-duplicate`).
- * @property {string}   [story]   Story id owning an AC absent from the manifest (`orphan-ac`).
- */
-
-/**
- * Resolve a Story's reporting id.
- *
- * @param {StorySlice} story
- * @param {number} index
- * @returns {string}
- */
-function storyId(story, index) {
-  if (story && typeof story.id === 'string' && story.id.trim() !== '') {
-    return story.id;
-  }
-  if (story && typeof story.slug === 'string' && story.slug.trim() !== '') {
-    return story.slug;
-  }
-  return `story[${index}]`;
-}
-
-/**
- * Validate that acceptance criteria partition cleanly across Stories.
- *
- * @param {StorySlice[]} stories The plan's Stories, each with `acceptance[]`.
- * @param {object} [opts]
- * @param {string[]} [opts.planAcceptance] Optional plan-level acceptance
- *   manifest. When supplied, coverage is enforced (every manifest AC claimed
- *   exactly once; no Story claims an off-manifest AC).
- * @returns {{ ok: boolean, violations: SplitPolicyViolation[] }}
- */
-export function validateAcceptancePartition(stories, opts = {}) {
-  const violations = [];
-  const list = Array.isArray(stories) ? stories : [];
-
-  // normalized AC → { original, owners: Set<storyId> }
-  const owners = new Map();
-  list.forEach((story, index) => {
-    const id = storyId(story, index);
-    const acceptance = Array.isArray(story?.acceptance) ? story.acceptance : [];
-    for (const ac of acceptance) {
-      const norm = normalizeAcceptance(ac);
-      if (norm === null) continue;
-      const existing = owners.get(norm);
-      if (existing) {
-        existing.owners.add(id);
-      } else {
-        owners.set(norm, { original: ac.trim(), owners: new Set([id]) });
-      }
-    }
-  });
-
-  // Cross-Story duplication: any AC owned by more than one Story.
-  for (const { original, owners: set } of owners.values()) {
-    if (set.size > 1) {
-      violations.push({
-        kind: 'cross-story-duplicate',
-        acceptance: original,
-        stories: [...set],
-      });
-    }
-  }
-
-  // Optional coverage check against a plan-level manifest.
-  const manifest = Array.isArray(opts.planAcceptance)
-    ? opts.planAcceptance
-    : null;
-  if (manifest !== null) {
-    const manifestNorms = new Map();
-    for (const ac of manifest) {
-      const norm = normalizeAcceptance(ac);
-      if (norm !== null && !manifestNorms.has(norm)) {
-        manifestNorms.set(norm, ac.trim());
-      }
-    }
-    // Every manifest AC must be claimed by exactly one Story.
-    for (const [norm, original] of manifestNorms) {
-      if (!owners.has(norm)) {
-        violations.push({
-          kind: 'unclaimed-manifest-ac',
-          acceptance: original,
-        });
-      }
-    }
-    // No Story may claim an AC absent from the manifest.
-    for (const [norm, { original, owners: set }] of owners) {
-      if (!manifestNorms.has(norm)) {
-        violations.push({
-          kind: 'orphan-ac',
-          acceptance: original,
-          story: [...set][0],
-        });
-      }
-    }
-  }
-
-  return { ok: violations.length === 0, violations };
-}
-
-/**
- * Render a single violation as a human-readable line.
- *
- * @param {SplitPolicyViolation} v
- * @returns {string}
- */
-function formatViolation(v) {
-  switch (v.kind) {
-    case 'cross-story-duplicate':
-      return `acceptance criterion appears in ${v.stories.length} Stories (${v.stories.join(', ')}) — a coupled split; keep it one Story: "${v.acceptance}"`;
-    case 'unclaimed-manifest-ac':
-      return `plan acceptance criterion is claimed by no Story: "${v.acceptance}"`;
-    case 'orphan-ac':
-      return `Story ${v.story} claims an acceptance criterion absent from the plan manifest: "${v.acceptance}"`;
-    default:
-      return `unknown split-policy violation: "${v.acceptance}"`;
-  }
-}
-
-/**
- * Throwing wrapper for the persist path: throws a single batched error when
- * the acceptance criteria do not partition cleanly, otherwise returns
- * `stories` unchanged. Wired into `plan-persist` in Stage 3.
- *
- * @param {StorySlice[]} stories
- * @param {object} [opts] See {@link validateAcceptancePartition}.
- * @returns {StorySlice[]}
- */
-export function assertAcceptancePartition(stories, opts = {}) {
-  const { ok, violations } = validateAcceptancePartition(stories, opts);
-  if (ok) return stories;
-  throw new Error(
-    `[split-policy] ${violations.length} acceptance-partition violation(s) — the plan splits coupled work; refuse:\n${violations
-      .map((v) => `  - ${formatViolation(v)}`)
-      .join('\n')}`,
-  );
-}

package/.agents/scripts/lib/orchestration/story-plan-state.js

@@ -1,33 +0,0 @@
-/**
- * story-plan-state.js — read the v2 Story planning checkpoint.
- *
- * `plan-persist.js` upserts one `story-plan-state` structured comment per
- * created Story carrying the persist receipt (when the plan completed, how many
- * Stories it created, and their ids). Story #4542 removed the risk fields it
- * used to carry: the planner-authored verdict, the envelope derived from it,
- * and the review routing computed from that envelope. Nothing read any of them
- * back — review depth is now derived from the diff at close time
- * (`review-depth.js#deriveChangeLevel`), so no checkpoint read sits on the
- * delivery path at all.
- */
-
-import { parseFencedJsonComment } from './structured-comment-parser.js';
-import { findStructuredComment } from './ticketing.js';
-
-/**
- * Read the v2 Story planning checkpoint. Missing/malformed comments degrade
- * to null — an unplanned Story simply has no persist receipt.
- */
-export async function readStoryPlanState({
-  provider,
-  storyId,
-  findCommentFn = findStructuredComment,
-}) {
-  const comment = await findCommentFn(
-    provider,
-    Number(storyId),
-    'story-plan-state',
-  );
-  const state = parseFencedJsonComment(comment);
-  return state && typeof state === 'object' ? state : null;
-}

package/.agents/scripts/lib/orchestration/structured-comment-parser.js

@@ -1,67 +0,0 @@
-/**
- * structured-comment-parser.js — shared parser for fenced-JSON structured
- * comments.
- *
- * Several callers (the deleted epic-runner Checkpointer/ProgressReporter,
- * `parseStoryRunProgressComment` / `parsePhaseTimingsComment`, wave-gate's
- * local `extractJsonBlock`) need to extract the `{...}` payload from the
- * fenced ```json``` block of a structured comment body. They had each open-
- * coded the same `/```json\s*\n([\s\S]*?)\n```/` regex + `JSON.parse` +
- * try/catch dance — small enough to copy, large enough to drift.
- *
- * This helper centralizes that single regex so a future change to the
- * fence format (e.g. tolerating CRLF, surrounding whitespace, alternate
- * fence languages) lives in exactly one place. The functions are
- * deliberately permissive about input shape: anything that isn't the
- * expected type returns `null` rather than throwing, matching what the
- * existing callers already do — they all treat parse failure as "no
- * payload available" and fall back to a default state.
- *
- * Acceptance contract for this helper:
- *   - returns the parsed JSON value when the body contains a valid fenced
- *     ```json``` block;
- *   - returns `null` for missing comment, missing body, missing fence, or
- *     malformed JSON inside the fence;
- *   - never throws.
- */
-
-const JSON_FENCE_RE = /```json\s*\n([\s\S]*?)\n```/;
-
-/**
- * Extract the parsed JSON object from the first fenced ```json``` block in
- * a raw string. Returns `null` for any malformed or missing input — callers
- * treat that as "no payload" and fall back.
- *
- * Use this variant when the caller already holds the raw comment body as a
- * string (e.g. after extracting `.body` themselves). Use
- * `parseFencedJsonComment` when working with a comment-like object.
- *
- * @param {unknown} text — the raw string to scan.
- * @returns {unknown | null} the parsed JSON value (typically an object),
- *   or `null` when extraction fails.
- */
-export function parseFencedJson(text) {
-  if (typeof text !== 'string') return null;
-  const match = text.match(JSON_FENCE_RE);
-  if (!match) return null;
-  try {
-    return JSON.parse(match[1]);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract the parsed JSON object from the first fenced ```json``` block in
- * a structured comment's `body`. Returns `null` for any malformed or
- * missing input — callers treat that as "no payload" and fall back.
- *
- * @param {{ body?: unknown } | null | undefined} comment — a comment-like
- *   object. Only the string `body` field is consulted.
- * @returns {unknown | null} the parsed JSON value (typically an object),
- *   or `null` when extraction fails.
- */
-export function parseFencedJsonComment(comment) {
-  if (!comment || typeof comment.body !== 'string') return null;
-  return parseFencedJson(comment.body);
-}