mandrel 2.36.0 → 2.37.0

package/.agents/scripts/lib/close-validation/telemetry.js

@@ -1,79 +0,0 @@
-/**
- * close-validation/telemetry.js — gh-spawn telemetry emitter.
- */
-
-import { writeFile as defaultWriteFile } from 'node:fs/promises';
-import path from 'node:path';
-import { storyTempDir } from '../config/temp-paths.js';
-import { getSpawnCount as defaultGetSpawnCount } from '../gh-exec.js';
-
-/**
- * Throw-away ghSpawnCount emitter (Story #1795 / Epic #1788).
- *
- * Writes the current `gh-exec` spawn counter to
- * `temp/run-<id>/stories/story-<sid>/gh-spawn-count.json`.
- *
- * Story #4545 — its reader is gone: `analyze-execution.js` consumed this file
- * to emit a `ghSpawnCount` field on the `story-perf-summary` payload, and both
- * that CLI and that payload were deleted with the execution-analysis surface.
- * The writer itself already had no production caller before that (the
- * `runPostMergeClose` orchestrator named below went in the v2.0.0 cutover), so
- * this module is production-dead and kept alive only by its own test — the
- * test-importer blind spot the dead-exports ratchet cannot see. It is left in
- * place rather than deleted because reviving spawn telemetry against the live
- * close path is a decision, not a sweep.
- *
- * @param {object} opts
- * @param {number|string} opts.epicId
- * @param {number|string} opts.storyId
- * @param {object} [opts.config] - Resolved config bag so `tempRoot`
- *   resolution honours the consumer's configured path.
- * @param {() => number} [opts.getSpawnCountFn=defaultGetSpawnCount] - Test seam.
- * @param {typeof defaultWriteFile} [opts.writeFileFn=defaultWriteFile] - Test seam.
- * @param {{ warn?: (s: string) => void }} [opts.logger] - Best-effort
- *   failure-path logger; never throws.
- * @returns {Promise<{ status: 'ok'|'failed', path?: string, ghSpawnCount?: number, reason?: string }>}
- */
-export async function emitGhSpawnCount({
-  epicId,
-  storyId,
-  config,
-  getSpawnCountFn = defaultGetSpawnCount,
-  writeFileFn = defaultWriteFile,
-  logger,
-} = {}) {
-  const eid = Number(epicId);
-  const sid = Number(storyId);
-  if (!Number.isInteger(eid) || eid < 1 || !Number.isInteger(sid) || sid < 1) {
-    return { status: 'failed', reason: 'invalid-ids' };
-  }
-  let ghSpawnCount;
-  try {
-    ghSpawnCount = getSpawnCountFn();
-  } catch (err) {
-    logger?.warn?.(
-      `[close-validation] gh-spawn-count read failed: ${err?.message ?? err}`,
-    );
-    return { status: 'failed', reason: 'counter-read-failed' };
-  }
-  const targetPath = path.join(
-    storyTempDir(eid, sid, config),
-    'gh-spawn-count.json',
-  );
-  const payload = {
-    kind: 'gh-spawn-count',
-    epicId: eid,
-    storyId: sid,
-    ghSpawnCount,
-    capturedAt: new Date().toISOString(),
-  };
-  try {
-    await writeFileFn(targetPath, JSON.stringify(payload, null, 2));
-    return { status: 'ok', path: targetPath, ghSpawnCount };
-  } catch (err) {
-    logger?.warn?.(
-      `[close-validation] gh-spawn-count emit failed: ${err?.message ?? err}`,
-    );
-    return { status: 'failed', reason: 'write-failed' };
-  }
-}

package/.agents/scripts/lib/orchestration/label-transitions.js

@@ -1,44 +0,0 @@
-/**
- * label-transitions.js — readability wrappers over `transitionTicketState`.
- *
- * These are deliberately thin: each helper names the *target* state and
- * forwards to the underlying SDK call. They exist so that init / close /
- * deliver-tail call sites read as prose ("toExecuting(provider, taskId)")
- * instead of forcing readers to parse the `STATE_LABELS.X` constant at
- * every call site.
- *
- * Not an abstraction — the underlying `transitionTicketState` remains the
- * authoritative single-ticket transition path. Opts are forwarded verbatim.
- */
-
-import { STATE_LABELS, transitionTicketState } from './ticketing.js';
-
-/** Transition a ticket to `agent::executing`. */
-export function toExecuting(provider, ticketId, opts) {
-  return transitionTicketState(
-    provider,
-    ticketId,
-    STATE_LABELS.EXECUTING,
-    opts,
-  );
-}
-
-/**
- * Transition an array of tickets to `agent::done`, in order. Each call
- * triggers its own cascade (via `transitionTicketState`). Failures for
- * individual tickets propagate — the loop aborts on the first error, so
- * callers that need per-ticket tolerance must catch around each id
- * themselves.
- *
- * @param {object} provider
- * @param {number[]} ticketIds
- * @param {object} [opts]
- */
-export async function toDone(provider, ticketIds, opts) {
-  if (!Array.isArray(ticketIds)) {
-    throw new TypeError('toDone: ticketIds must be an array');
-  }
-  for (const id of ticketIds) {
-    await transitionTicketState(provider, id, STATE_LABELS.DONE, opts);
-  }
-}

package/.agents/scripts/lib/orchestration/parked-follow-ons.js

@@ -1,147 +0,0 @@
-/**
- * Classify Stories that exist under an Epic but are absent from the frozen
- * dispatch manifest. Two cases:
- *
- *   - "recut"  — the Story carries a `<!-- recut-of: #N -->` marker whose
- *                parent ID matches a manifest entry. These are attributable
- *                to a manifest Story and must be satisfied alongside it.
- *
- *   - "parked" — the Story is genuinely outside the manifest (carved off
- *                mid-sprint, no recut lineage). The operator should explicitly
- *                adopt it into the current Epic or defer it. Surfaced as a
- *                structured comment so `/deliver` has a single checkpoint.
- *
- * Both categories are informational at the wave-completeness gate — they do
- * not fail closure by themselves. The gate continues to enforce that every
- * manifest Story is closed; recuts and parked follow-ons are additional
- * transparency.
- */
-
-import { parseRecutMarker } from './recut.js';
-
-/**
- * Partition Stories under an Epic into manifest, recut, and parked buckets.
- *
- * @param {number[]} manifestStoryIds  IDs present in the dispatch manifest.
- * @param {Array<{ id: number, title?: string, body?: string, state?: string, labels?: string[] }>} storiesUnderEpic
- *   All `type::story` tickets under the Epic.
- * @returns {{
- *   manifest: Array<object>,
- *   recuts: Array<{ storyId: number, parentId: number, title: string, state: string }>,
- *   parked: Array<{ storyId: number, title: string, state: string }>,
- * }}
- */
-export function classifyStoriesAgainstManifest(
-  manifestStoryIds,
-  storiesUnderEpic,
-) {
-  const manifestSet = new Set(manifestStoryIds.map(Number));
-  const manifest = [];
-  const recuts = [];
-  const parked = [];
-
-  for (const story of storiesUnderEpic) {
-    if (manifestSet.has(story.id)) {
-      manifest.push(story);
-      continue;
-    }
-    const marker = parseRecutMarker(story.body);
-    if (marker && manifestSet.has(marker.parentStoryId)) {
-      recuts.push({
-        storyId: story.id,
-        parentId: marker.parentStoryId,
-        title: story.title ?? '',
-        state: story.state ?? 'open',
-      });
-    } else {
-      parked.push({
-        storyId: story.id,
-        title: story.title ?? '',
-        state: story.state ?? 'open',
-      });
-    }
-  }
-
-  return { manifest, recuts, parked };
-}
-
-/**
- * Render the structured `parked-follow-ons` comment body for an Epic.
- * Idempotent: the same input produces identical output, so repeated upserts
- * don't churn comment revisions.
- *
- * @param {number} epicId
- * @param {ReturnType<typeof classifyStoriesAgainstManifest>} classification
- * @returns {string}
- */
-export function renderParkedFollowOnsComment(epicId, classification) {
-  const { recuts, parked } = classification;
-
-  const lines = [
-    `## 🪝 Parked Follow-Ons & Recuts — Epic #${epicId}`,
-    '',
-    'Stories created under this Epic that are **not** in the frozen dispatch',
-    'manifest. Surfaced here so `/deliver` can gate on them at the',
-    'completeness check.',
-    '',
-    `- **Recuts** (attributable to a manifest Story): ${recuts.length}`,
-    `- **Parked follow-ons** (no manifest lineage): ${parked.length}`,
-    '',
-  ];
-
-  if (recuts.length > 0) {
-    lines.push('### Recuts');
-    lines.push('');
-    lines.push('| Story | Recut-of | State | Title |');
-    lines.push('| :--- | :--- | :--- | :--- |');
-    for (const r of recuts) {
-      lines.push(
-        `| #${r.storyId} | #${r.parentId} | ${r.state} | ${r.title} |`,
-      );
-    }
-    lines.push('');
-  }
-
-  if (parked.length > 0) {
-    lines.push('### Parked Follow-Ons');
-    lines.push('');
-    lines.push('| Story | State | Title |');
-    lines.push('| :--- | :--- | :--- |');
-    for (const p of parked) {
-      lines.push(`| #${p.storyId} | ${p.state} | ${p.title} |`);
-    }
-    lines.push('');
-    lines.push(
-      '> **Action required**: adopt each Story into the current Epic (by',
-      '> re-running the dispatcher so the manifest is refreshed), or explicitly',
-      '> defer by closing the Story with `state_reason=not_planned`.',
-    );
-    lines.push('');
-  }
-
-  if (recuts.length === 0 && parked.length === 0) {
-    lines.push(
-      '✅ No out-of-manifest Stories detected — every Story under this Epic is in the dispatch manifest.',
-    );
-    lines.push('');
-  }
-
-  lines.push('```json');
-  lines.push(
-    JSON.stringify(
-      {
-        recuts: recuts.map((r) => ({
-          storyId: r.storyId,
-          parentId: r.parentId,
-          state: r.state,
-        })),
-        parked: parked.map((p) => ({ storyId: p.storyId, state: p.state })),
-      },
-      null,
-      2,
-    ),
-  );
-  lines.push('```');
-
-  return lines.join('\n');
-}

package/.agents/scripts/lib/orchestration/phase-runner.js

@@ -1,88 +0,0 @@
-/**
- * phase-runner.js — Lightweight wrappers for "named phase" error handling.
- *
- * Many orchestration entry points (`single-story-init.js`,
- * `single-story-close.js`, and other phase modules) repeat the same
- * `try { ... } catch (err) {
- * logger.error('[phase=foo] ' + err.message); ... }` block. These two
- * helpers consolidate that pattern.
- *
- *   - `runPhase(name, fn, opts)`: Run `fn()`. On error, log with a
- *     `[phase=<name>]` prefix. If `fatal: true`, rethrow; otherwise
- *     return `opts.fallback` (default `undefined`) so the caller can
- *     continue.
- *
- *   - `runSafely(fn, opts)`: Run `fn()` and swallow any error after
- *     logging it. Convenience for unnamed best-effort cleanup steps.
- *
- * Both helpers handle sync and async `fn`s — the return value is always
- * a Promise that resolves to the function's value (or `fallback`).
- */
-
-import { NOOP_LOGGER } from '../Logger.js';
-
-/**
- * @typedef {object} PhaseLogger
- * @property {(msg: string) => void} [error]
- * @property {(msg: string) => void} [warn]
- */
-
-function pickLogger(logger) {
-  if (!logger) return NOOP_LOGGER;
-  return {
-    error:
-      typeof logger.error === 'function'
-        ? logger.error.bind(logger)
-        : NOOP_LOGGER.error,
-    warn:
-      typeof logger.warn === 'function'
-        ? logger.warn.bind(logger)
-        : NOOP_LOGGER.warn,
-  };
-}
-
-/**
- * Run `fn` under a named phase. On error:
- *   - logs `[phase=<name>] <message>` via `logger.error`
- *   - if `fatal` is true, rethrows the original error
- *   - otherwise returns `fallback`
- *
- * @template T
- * @param {string} name - Phase name (used in the log prefix).
- * @param {() => (T | Promise<T>)} fn
- * @param {{ logger?: PhaseLogger, fallback?: T, fatal?: boolean }} [opts]
- * @returns {Promise<T | undefined>}
- */
-export async function runPhase(name, fn, opts = {}) {
-  const logger = pickLogger(opts.logger);
-  const fatal = opts.fatal === true;
-  try {
-    return await fn();
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    logger.error(`[phase=${name}] ${message}`);
-    if (fatal) throw err;
-    return opts.fallback;
-  }
-}
-
-/**
- * Run `fn` and swallow errors after logging. Equivalent to
- * `runPhase('safe', fn, { logger, fatal: false })` but without requiring
- * the caller to invent a phase name.
- *
- * @template T
- * @param {() => (T | Promise<T>)} fn
- * @param {{ logger?: PhaseLogger }} [opts]
- * @returns {Promise<T | undefined>}
- */
-export async function runSafely(fn, opts = {}) {
-  const logger = pickLogger(opts.logger);
-  try {
-    return await fn();
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    logger.warn(`[phase=safe] ${message}`);
-    return undefined;
-  }
-}

package/.agents/scripts/lib/orchestration/recut.js

@@ -1,56 +0,0 @@
-/**
- * Recut markers track when a Story is carved off mid-sprint from another
- * Story that is already in the dispatch manifest. The marker is an HTML
- * comment embedded in the new Story's body:
- *
- *     <!-- recut-of: #641 -->
- *
- * Downstream consumers (the wave-completeness gate, the sprint retro)
- * read the marker to attribute the new Story back to its ancestor so
- * counts line up with the frozen manifest.
- */
-
-const MARKER_RE = /<!--\s*recut-of:\s*#?(\d+)\s*-->/i;
-
-/**
- * Parse a recut marker out of a Story body.
- *
- * @param {string | null | undefined} body
- * @returns {{ parentStoryId: number, raw: string } | null}
- */
-export function parseRecutMarker(body) {
-  if (typeof body !== 'string') return null;
-  const match = body.match(MARKER_RE);
-  if (!match) return null;
-  return { parentStoryId: Number.parseInt(match[1], 10), raw: match[0] };
-}
-
-/**
- * Format a recut marker for a given parent Story ID.
- *
- * @param {number} parentStoryId
- * @returns {string}
- */
-export function formatRecutMarker(parentStoryId) {
-  return `<!-- recut-of: #${parentStoryId} -->`;
-}
-
-/**
- * Return a body with the recut marker present. Replaces any existing
- * marker so the parent reference is always up to date; appends a fresh
- * marker when none is present.
- *
- * @param {string | null | undefined} body
- * @param {number} parentStoryId
- * @returns {string}
- */
-export function injectRecutMarker(body, parentStoryId) {
-  const marker = formatRecutMarker(parentStoryId);
-  const existing = parseRecutMarker(body);
-  if (existing) {
-    if (existing.parentStoryId === parentStoryId) return body ?? '';
-    return (body ?? '').replace(MARKER_RE, marker);
-  }
-  const trimmed = (body ?? '').replace(/\s+$/, '');
-  return trimmed.length > 0 ? `${trimmed}\n\n${marker}\n` : `${marker}\n`;
-}