mandrel 2.35.0 → 2.37.0

package/.agents/scripts/generate-lifecycle-docs.js

@@ -1,237 +0,0 @@
-#!/usr/bin/env node
-/**
- * .agents/scripts/generate-lifecycle-docs.js — Schema-backed lifecycle docs table
- *
- * Renders a bounded region inside `docs/LIFECYCLE.md` from every
- * `.agents/schemas/lifecycle/*.schema.json`. The region is delimited by:
- *
- *     <!-- BEGIN GENERATED:lifecycle-events -->
- *     ...generated table...
- *     <!-- END GENERATED:lifecycle-events -->
- *
- * Columns: | Event | Schema | Description | Required fields |
- *
- *   - Event             = schema filename minus `.schema.json`
- *   - Schema            = relative markdown link to the schema file
- *   - Description       = the schema's top-level `description` property
- *   - Required fields   = comma-joined list from the schema's `required` array
- *                         (rendered as inline code; "—" when empty/absent)
- *
- * Skips `README.md`. The `ledger-record.schema.json` file is a record
- * envelope rather than a lifecycle event, but to keep this generator
- * literal-schema driven we still emit a row for it — the surrounding doc
- * already calls out the distinction.
- *
- * Modes:
- *   (default)  — rewrites the bounded region in place.
- *   --check    — exits 0 when the on-disk region matches the freshly
- *                generated content, exits 1 with a diff hint otherwise.
- *
- * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable
- * failures surface via `throw new Error(...)` so `runAsCli` can map the
- * throw to `process.exit(1)` deterministically (no `Logger.fatal`).
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import { Logger } from './lib/Logger.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const SCHEMA_DIR = path.join(PROJECT_ROOT, '.agents', 'schemas', 'lifecycle');
-const DOC_PATH = path.join(PROJECT_ROOT, 'docs', 'LIFECYCLE.md');
-const REGION_BEGIN = '<!-- BEGIN GENERATED:lifecycle-events -->';
-const REGION_END = '<!-- END GENERATED:lifecycle-events -->';
-
-/**
- * Read and parse every `*.schema.json` under the lifecycle schema dir, in
- * ASCII-sorted filename order. The sort is intentional — it produces a
- * stable diff regardless of the host filesystem's enumeration order, which
- * is what makes `--check` reliable across platforms.
- *
- * @param {string} dir Absolute path to the schema directory.
- * @returns {Array<{event:string, file:string, description:string, required:string[]}>}
- */
-function readLifecycleSchemas(dir) {
-  if (!fs.existsSync(dir)) {
-    throw new Error(`Lifecycle schema directory not found: ${dir}`);
-  }
-  const entries = fs
-    .readdirSync(dir)
-    .filter((name) => name.endsWith('.schema.json'))
-    .sort();
-  if (entries.length === 0) {
-    throw new Error(`No *.schema.json files found in ${dir}`);
-  }
-  return entries.map((file) => {
-    const abs = path.join(dir, file);
-    const raw = fs.readFileSync(abs, 'utf8');
-    let json;
-    try {
-      json = JSON.parse(raw);
-    } catch (err) {
-      throw new Error(`Failed to parse JSON schema ${file}: ${err.message}`);
-    }
-    const event = file.replace(/\.schema\.json$/, '');
-    const description =
-      typeof json.description === 'string' && json.description.trim().length > 0
-        ? json.description.trim()
-        : '';
-    const required = Array.isArray(json.required) ? [...json.required] : [];
-    return { event, file, description, required };
-  });
-}
-
-/**
- * Escape pipe characters so they survive Markdown table cell parsing.
- *
- * @param {string} text
- * @returns {string}
- */
-function escapeCell(text) {
-  return text.replace(/\|/g, '\\|');
-}
-
-/**
- * Render the bounded-region body (the generated content between the two
- * comment markers, exclusive of the markers themselves).
- *
- * @param {ReturnType<typeof readLifecycleSchemas>} rows
- * @returns {string}
- */
-function renderTable(rows) {
-  const header = '| Event | Schema | Description | Required fields |';
-  const sep = '| --- | --- | --- | --- |';
-  const body = rows.map((row) => {
-    const eventCell = `\`${row.event}\``;
-    const schemaLink = `[\`${row.file}\`](../.agents/schemas/lifecycle/${row.file})`;
-    const description = escapeCell(row.description || '—');
-    const requiredCell =
-      row.required.length === 0
-        ? '—'
-        : row.required.map((field) => `\`${field}\``).join(', ');
-    return `| ${eventCell} | ${schemaLink} | ${description} | ${requiredCell} |`;
-  });
-  // Surround with blank lines so the markers + table read as a separate block.
-  return ['', header, sep, ...body, ''].join('\n');
-}
-
-/**
- * Substitute the bounded region inside `original`. Throws if either marker
- * is missing, or if `BEGIN` appears after `END`. Idempotent — a re-run on
- * the same input yields byte-identical output.
- *
- * @param {string} original
- * @param {string} body Region body, already including leading/trailing blank
- *                      lines (as produced by `renderTable`).
- * @returns {string}
- */
-function spliceRegion(original, body) {
-  const beginIdx = original.indexOf(REGION_BEGIN);
-  const endIdx = original.indexOf(REGION_END);
-  if (beginIdx === -1) {
-    throw new Error(
-      `Missing region marker "${REGION_BEGIN}" in ${DOC_PATH}. ` +
-        'Insert the marker pair before re-running the generator.',
-    );
-  }
-  if (endIdx === -1) {
-    throw new Error(
-      `Missing region marker "${REGION_END}" in ${DOC_PATH}. ` +
-        'Insert the marker pair before re-running the generator.',
-    );
-  }
-  if (endIdx < beginIdx) {
-    throw new Error(
-      `Region markers out of order in ${DOC_PATH}: END appears before BEGIN.`,
-    );
-  }
-  const before = original.slice(0, beginIdx + REGION_BEGIN.length);
-  const after = original.slice(endIdx);
-  return `${before}\n${body}\n${after}`;
-}
-
-/**
- * Build the canonical post-generation file content for `docs/LIFECYCLE.md`.
- *
- * @param {string} schemaDir
- * @param {string} docPath
- * @returns {{ generated: string, original: string }}
- */
-function buildExpected(schemaDir, docPath) {
-  if (!fs.existsSync(docPath)) {
-    throw new Error(`Target doc not found: ${docPath}`);
-  }
-  const original = fs.readFileSync(docPath, 'utf8');
-  const rows = readLifecycleSchemas(schemaDir);
-  const body = renderTable(rows);
-  const generated = spliceRegion(original, body);
-  return { generated, original };
-}
-
-/**
- * @param {string[]} argv
- */
-async function main(argv = process.argv.slice(2)) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      check: { type: 'boolean', default: false },
-    },
-    allowPositionals: false,
-  });
-
-  const { generated, original } = buildExpected(SCHEMA_DIR, DOC_PATH);
-
-  if (values.check) {
-    if (generated === original) {
-      Logger.info(
-        `generate-lifecycle-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} is up to date.`,
-      );
-      return;
-    }
-    const hint =
-      `${path.relative(PROJECT_ROOT, DOC_PATH)} is out of date. ` +
-      'Run `node .agents/scripts/generate-lifecycle-docs.js` to regenerate the bounded region.';
-    throw new Error(hint);
-  }
-
-  if (generated === original) {
-    Logger.info(
-      `generate-lifecycle-docs: ${path.relative(PROJECT_ROOT, DOC_PATH)} already current — no write.`,
-    );
-    return;
-  }
-  fs.writeFileSync(DOC_PATH, generated, 'utf8');
-  Logger.info(
-    `generate-lifecycle-docs: wrote bounded region into ${path.relative(PROJECT_ROOT, DOC_PATH)}.`,
-  );
-}
-
-export {
-  buildExpected,
-  REGION_BEGIN,
-  REGION_END,
-  readLifecycleSchemas,
-  renderTable,
-  spliceRegion,
-};
-
-runAsCli(import.meta.url, main, {
-  source: 'generate-lifecycle-docs',
-  usage: {
-    invocation: 'node .agents/scripts/generate-lifecycle-docs.js [--check]',
-    summary:
-      'Regenerate the lifecycle-event table in docs/LIFECYCLE.md from the event schemas. Writes only when the generated content differs.',
-    flags: [
-      [
-        '--check',
-        'Verify the doc is current and fail if stale; write nothing.',
-      ],
-    ],
-  },
-});

package/.agents/scripts/lib/audit-suite/frontmatter-lint.js

@@ -1,32 +0,0 @@
-/**
- * lib/audit-suite/frontmatter-lint.js — workflow frontmatter linter.
- *
- * Lives next to `frontmatter.js` but stays in its own module so adding
- * lints doesn't drag the summary helper's maintainability score down.
- * Pure: no IO, no provider calls, safe to unit-test in isolation.
- *
- * Story #1324, Epic #1185 — Dispatch performance pass.
- *
- * Story #2824, Epic #2815 — Model-hint frontmatter was removed from
- * every workflow and from the validator's field list. The function is
- * retained as a no-op safety net so callers (and any future frontmatter
- * lints) keep a stable entry point.
- */
-
-import { extractFrontmatter } from './frontmatter.js';
-
-/**
- * Pure: lint a frontmatter map (or raw workflow content). Currently a
- * no-op — no frontmatter fields are validated after the model-hint
- * removal. The signature is preserved so future field-level lints can
- * slot in without churning callers.
- *
- * @param {string | Record<string, string>} input
- * @returns {{ ok: boolean, errors: Array<{ field: string, value: string, message: string }> }}
- */
-export function validateFrontmatter(input) {
-  // Extract so callers still pay the same "is this parseable?" cost as
-  // before; we just have no field-level rules to enforce right now.
-  if (typeof input === 'string') extractFrontmatter(input);
-  return { ok: true, errors: [] };
-}

package/.agents/scripts/lib/baselines/maintainability-baseline-save.js

@@ -1,37 +0,0 @@
-import path from 'node:path';
-import {
-  write as writeBaselineEnvelope,
-  writeFile as writeBaselineFile,
-} from './writer.js';
-
-/**
- * Saves a new maintainability baseline to disk at `baselinePath`.
- *
- * Accepts the legacy flat `{ path: mi }` shape for backwards compatibility
- * with existing callers (`regenerateMainFromTree`, refresh helpers). The
- * map is transformed into the canonical envelope shape (`$schema`,
- * `kernelVersion`, `generatedAt`, `rollup`, `rows`) via the shared
- * `lib/baselines/writer.js` pipeline before being persisted, so every
- * write produces a file that round-trips through `lib/baselines/reader.js`
- * without schema errors.
- *
- * @param {Record<string, number>} baseline  path→MI flat map.
- * @param {string} baselinePath  Required — caller supplies via getBaselines().
- */
-export function saveBaseline(baseline, baselinePath) {
-  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
-    throw new TypeError(
-      'maintainability-utils.saveBaseline: baselinePath is required.',
-    );
-  }
-  const abs = path.isAbsolute(baselinePath)
-    ? baselinePath
-    : path.resolve(process.cwd(), baselinePath);
-
-  const rows = Object.entries(baseline ?? {}).map(([p, mi]) => ({
-    path: p,
-    mi,
-  }));
-  const envelope = writeBaselineEnvelope({ kind: 'maintainability', rows });
-  writeBaselineFile(abs, envelope);
-}

package/.agents/scripts/lib/cli/parse-numeric.js

@@ -1,60 +0,0 @@
-/**
- * parse-numeric.js — shared CLI integer-flag validators (Story #2993).
- *
- * Extracted from `lifecycle-emit-story-dispatch.js` so future scripts that
- * need a strict positive-integer or non-negative-integer flag value share
- * a single validator instead of hand-rolling another `Number.parseInt`
- * dance. Both helpers throw with a clear "required" / "must be …" message
- * shape so a `runAsCli` boundary surfaces a clean exit-1.
- *
- * Contract:
- *   - Empty / `null` / `undefined` raw values throw "is required".
- *   - Non-integer or out-of-range values throw "must be a … integer".
- *   - A leading `#` on the raw value is stripped (matches the ticket-ID
- *     ergonomic on the rest of the framework).
- *
- * @module lib/cli/parse-numeric
- */
-
-/**
- * Parse a flag value as a strict positive integer (≥ 1). Leading `#` is
- * stripped to match the `parseTicketId` ergonomic.
- *
- * @param {string|number|null|undefined} raw
- * @param {string} flag  Flag label used in the thrown error message.
- * @param {string} [tool='cli'] Optional tool prefix for the error message.
- * @returns {number}
- */
-export function parseRequiredPositiveInt(raw, flag, tool = 'cli') {
-  if (raw === undefined || raw === null || raw === '') {
-    throw new Error(`${tool}: ${flag} is required`);
-  }
-  const n = Number.parseInt(String(raw).replace(/^#/, ''), 10);
-  if (!Number.isInteger(n) || n < 1) {
-    throw new Error(`${tool}: ${flag} must be a positive integer (got ${raw})`);
-  }
-  return n;
-}
-
-/**
- * Parse a flag value as a strict non-negative integer (≥ 0). Leading `#`
- * is NOT stripped — non-negative use cases (wave index, attempt offset)
- * do not carry the ticket-ID convention.
- *
- * @param {string|number|null|undefined} raw
- * @param {string} flag
- * @param {string} [tool='cli']
- * @returns {number}
- */
-export function parseRequiredNonNegativeInt(raw, flag, tool = 'cli') {
-  if (raw === undefined || raw === null || raw === '') {
-    throw new Error(`${tool}: ${flag} is required`);
-  }
-  const n = Number.parseInt(String(raw), 10);
-  if (!Number.isInteger(n) || n < 0) {
-    throw new Error(
-      `${tool}: ${flag} must be a non-negative integer (got ${raw})`,
-    );
-  }
-  return n;
-}

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');
-}