mandrel 2.36.0 → 2.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.36.0",
+  "version": "2.38.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -19,7 +19,9 @@
     "test": "node .agents/scripts/run-tests.js",
     "test:quick": "node .agents/scripts/run-tests.js --tier quick",
     "test:integration": "node .agents/scripts/run-tests.js --tier integration",
+    "test:e2e": "node .agents/scripts/run-tests.js --tier e2e",
     "test:profile": "node .agents/scripts/run-test-profile.js",
+    "test:census": "SPAWN_CENSUS_OUT=\"${SPAWN_CENSUS_OUT:-temp/census.json}\" NODE_OPTIONS=\"--require $PWD/tests/fixtures/spawn-census.cjs\" node .agents/scripts/run-tests.js",
     "test:isolate": "node .agents/scripts/test-isolate.js",
     "verify": "node .agents/scripts/run-verify.js",
     "typecheck": "node -e \"process.exit(0)\"",
@@ -31,7 +33,7 @@
     "baselines:scope": "node .agents/scripts/check-baseline-scope.js",
     "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
-    "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
+    "lint": "node .agents/scripts/run-lint.js && node .agents/scripts/check-generated-validator.js --check && npm run docs:check",
     "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
     "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
@@ -47,6 +49,8 @@
     "cyclomatic:update": "node .agents/scripts/check-cyclomatic.js --update",
     "dead-exports:update": "node .agents/scripts/update-dead-exports-baseline.js && node .agents/scripts/update-dead-exports-baseline.js --production",
     "check:knip-entries": "node .agents/scripts/check-knip-entries.js",
+    "validator:gen": "node .agents/scripts/check-generated-validator.js",
+    "validator:check": "node .agents/scripts/check-generated-validator.js --check",
     "check:schema-refs": "node .agents/scripts/check-schema-references.js",
     "check:workflow-citations": "node .agents/scripts/check-workflow-citations.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
@@ -101,7 +105,7 @@
     "markdownlint-cli2": "^0.22.1",
     "memfs": "^4.57.7",
     "node-pty": "^1.0.0",
-    "typescript": ">=5.0.0"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "ajv": "^8.20.0",

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

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`;
-}