mandrel 2.59.0 → 2.61.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/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);
-}

package/.agents/scripts/lib/pinned-override-notes.js

@@ -1,88 +0,0 @@
-/**
- * pinned-override-notes.js — keep a load-bearing dependency note honest.
- *
- * `package.json` carries a `"//"` block of prose notes keyed by dotted config
- * path. Two of them are safety notes about a pinned `overrides` entry: they
- * record WHY the pin exists, which advisories removing it reintroduces, and
- * that the `overrides` range and the direct `dependencies` range MUST move in
- * lockstep because npm has no way to reference one from the other.
- *
- * A note like that is consulted precisely when someone is deciding whether a
- * bump is safe — so a stale version inside it hands out wrong premises about
- * a coupling the note itself calls a trap. Nothing enforced either claim, and
- * both had drifted: the note described `^4.2.0` while the pin had moved twice.
- *
- * This module derives the checks from the `"//"` keys themselves rather than
- * naming any package, so a second pinned override gets the same guarantee by
- * writing its note.
- */
-
-/** A `"//"` key that documents a pinned override, e.g. `overrides.js-yaml`. */
-const OVERRIDE_NOTE_KEY = /^overrides\.(.+)$/;
-
-import { resolvePin, scoreNote } from './pinned-override-resolve.js';
-
-/**
- * Audit one package document's pinned-override notes.
- *
- * Findings per documented override, each naming the drift rather than just
- * asserting a mismatch:
- *   - `lockstep` — `overrides.<name>` and `dependencies.<name>` disagree. The
- *     companion note declares they must not; a split silently gives the
- *     direct and transitive resolutions different floors.
- *   - `stale-note` — the note quotes at least one range but not the one in
- *     force, so its stated version is behind the pin it describes. A note
- *     quoting no range at all is not scored: prose that names no version
- *     cannot go stale.
- *   - `unsupported-shape` — the note's key resolves to something that is not a
- *     range (a nested override object, or a `$name` reference to a dependency
- *     that does not exist). Distinct from `orphan-note`: the pin is *there*,
- *     the note just does not name it, and telling an author to "delete the note
- *     or restore the pin" would be wrong advice.
- *
- * @param {{ '//'?: Record<string,string>, overrides?: Record<string,string>, dependencies?: Record<string,string> }} pkg
- * @returns {{ findings: Array<{ kind: string, name: string, detail: string }>, checked: string[] }}
- */
-export function auditPinnedOverrideNotes(pkg) {
-  const overrides = pkg?.overrides ?? {};
-  const dependencies = pkg?.dependencies ?? {};
-  const findings = [];
-  const checked = [];
-
-  for (const { key, name, text } of documentedOverrides(pkg)) {
-    const resolved = resolvePin({ overrides, dependencies, name });
-    if (isCheckable(resolved)) checked.push(name);
-    findings.push(
-      ...scoreNote({ key, name, text, resolved, direct: dependencies[name] }),
-    );
-  }
-
-  return { findings, checked };
-}
-
-/**
- * The `"//"` entries that document an override, as `{ key, name, text }`.
- * Every other note in the block — a peer-dependency rationale, say — is not
- * this gate's business and is skipped rather than scored.
- *
- * @param {object} pkg
- * @returns {Array<{ key: string, name: string, text: unknown }>}
- */
-function documentedOverrides(pkg) {
-  return Object.entries(pkg?.['//'] ?? {})
-    .map(([key, text]) => ({ key, text, match: OVERRIDE_NOTE_KEY.exec(key) }))
-    .filter((entry) => entry.match !== null)
-    .map(({ key, text, match }) => ({ key, text, name: match[1] }));
-}
-
-/**
- * Was the note's override resolved to a range at all? Only then does the name
- * belong in `checked` — the list is what tells a caller which pins this gate
- * actually stands behind.
- *
- * @param {{ kind: string }} resolved
- * @returns {boolean}
- */
-function isCheckable(resolved) {
-  return resolved.kind !== 'missing' && resolved.kind !== 'unsupported';
-}