mandrel 1.57.0

package/.agents/scripts/lib/preflight-runner.js

@@ -0,0 +1,196 @@
+/**
+ * preflight-runner.js — Shared preflight wrapper around the checks registry.
+ *
+ * This module is the single implementation of the "run the registry, fail
+ * fast on blockers, log auto-fixes" pattern. The consumer entry points
+ * (story-close.js, epic-deliver-preflight.js, the npm test wrapper, and
+ * the bootstrap scripts) call `runPreflight({ scope })` instead of
+ * re-implementing the same assemble+run+format+exit-2 dance.
+ *
+ * Exit-code contract (shared by every consumer):
+ *   - 0 → no blocker findings (warnings/info may have been printed).
+ *   - 2 → at least one `severity: 'blocker'` finding survived after
+ *         auto-fixes. The wrapper prints a human-readable blocker table
+ *         (`id · summary · fixCommand`) before returning. Code 2 is the
+ *         project-wide "preflight refused" reservation — see
+ *         .agents/workflows/epic-deliver.md for the rationale.
+ *
+ * Auto-fixes are logged via `logFixes` before the blocker check so the
+ * operator sees the "we corrected X" line even when a separate blocker
+ * later trips the exit. Auto-fixes never themselves block.
+ */
+
+import { runChecks } from './checks/index.js';
+import { assembleState } from './checks/state.js';
+import { Logger } from './Logger.js';
+
+/**
+ * @typedef {object} PreflightResult
+ * @property {Array<object>} findings  Unfixed findings (any severity).
+ * @property {Array<object>} fixed     Findings that were auto-corrected.
+ * @property {boolean} blocked         True iff `findings` contains a
+ *   `severity: 'blocker'`. When `true`, the consumer must exit with code 2.
+ */
+
+/**
+ * Default logger adapter — routes info/warn/error through the project
+ * Logger. Kept as a module-local constant so the runner has a single seam
+ * tests can swap with a spy that captures lines without going through
+ * Logger's stdout/stderr.
+ */
+const DEFAULT_LOGGER = {
+  info: (msg) => Logger.info(msg),
+  warn: (msg) => Logger.warn(msg),
+  error: (msg) => Logger.error(msg),
+};
+
+/**
+ * Run preflight checks for `scope` against an assembled state probe.
+ *
+ * The consumer surface is intentionally tiny: pass a `scope` string and
+ * (optionally) a `cwd`. The runner handles state assembly, the autoFix
+ * flag, finding/fix routing, and pretty-print of the blocker table.
+ *
+ * @param {object} opts
+ * @param {string} opts.scope          Consumer surface — `'epic-close'`,
+ *   `'story-close'`, `'npm-test'`, etc.
+ * @param {boolean} [opts.autoFix=true] Forwarded to `runChecks`. Defaults
+ *   to `true` because every wiring call site at this Story's level wants
+ *   auto-correction (the `retro` consumer that needs `autoFix:false` does
+ *   NOT use this helper — it calls `runChecks` directly).
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {object} [opts.probes]       Test-only probe injection forwarded
+ *   to `assembleState`. Production callers omit this.
+ * @param {object} [opts.registry]     Test-only — bypass `loadRegistry()`.
+ * @param {string} [opts.dir]          Test-only fixture directory.
+ * @param {{ info?: Function, warn?: Function, error?: Function }} [opts.logger]
+ *   Defaults to the project Logger. Tests pass a spy that captures lines.
+ * @returns {Promise<PreflightResult>}
+ */
+export async function runPreflight({
+  scope,
+  autoFix = true,
+  cwd = process.cwd(),
+  probes,
+  registry,
+  dir,
+  logger = DEFAULT_LOGGER,
+} = {}) {
+  if (!scope || typeof scope !== 'string') {
+    throw new Error('runPreflight: scope is required');
+  }
+  // `retro` is reserved by the runner and is never a preflight scope.
+  // Catch it here so the failure mode is obvious instead of routing into
+  // the runner's autoFix throw.
+  if (scope === 'retro') {
+    throw new Error(
+      'runPreflight: retro scope is read-only — call runChecks directly',
+    );
+  }
+  const state = assembleState({ scope, cwd, probes });
+  const { findings, fixed } = await runChecks({
+    scope,
+    autoFix,
+    state,
+    registry,
+    dir,
+  });
+  if (fixed.length > 0) logFixes(fixed, logger);
+  const blockers = findings.filter((f) => f.severity === 'blocker');
+  const blocked = blockers.length > 0;
+  if (blocked) logBlockers(scope, blockers, logger);
+  // Surface non-blocker findings as well so operators see warnings/info.
+  const nonBlockerFindings = findings.filter((f) => f.severity !== 'blocker');
+  if (nonBlockerFindings.length > 0) logNonBlockers(nonBlockerFindings, logger);
+  return { findings, fixed, blocked };
+}
+
+/**
+ * Pick the logger method for `level` — falls back through the project
+ * Logger if the supplied logger is missing the level. Keeps the
+ * console-allowlist test happy (no direct console.* fallback here) and
+ * still lets tests swap the entire logger out.
+ */
+function pick(logger, level) {
+  if (logger && typeof logger[level] === 'function') {
+    return (msg) => logger[level](msg);
+  }
+  return (msg) => Logger[level](msg);
+}
+
+/**
+ * Print the auto-fixed findings as a one-line-per-fix summary.
+ *
+ * @param {Array<object>} fixed
+ * @param {object} [logger]
+ */
+export function logFixes(fixed, logger = DEFAULT_LOGGER) {
+  const info = pick(logger, 'info');
+  info(`[preflight] auto-fixed ${fixed.length} finding(s):`);
+  for (const f of fixed) {
+    const msg = f.fixResult?.message ?? 'fixed';
+    info(`  - ${f.id}: ${msg}`);
+  }
+}
+
+/**
+ * Print the blocker table the operator sees on `exit 2`. Each row carries
+ * `id · summary · fixCommand`; details (if present) wrap underneath.
+ *
+ * @param {string} scope
+ * @param {Array<object>} blockers
+ * @param {object} [logger]
+ */
+export function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
+  const error = pick(logger, 'error');
+  error(
+    `[preflight] ${scope}: ${blockers.length} blocker finding(s) — refusing to proceed.`,
+  );
+  error('');
+  error('  id                          severity  summary / fixCommand');
+  error(
+    '  --------------------------  --------  ----------------------------------------',
+  );
+  for (const b of blockers) {
+    // Pad short IDs to align the column; never TRUNCATE — the operator
+    // needs the full id to find the check module on disk and to grep the
+    // codebase for the failure mode. Long ids just push the severity
+    // column right, which is fine for terminal output.
+    const id = String(b.id).padEnd(26);
+    const sev = String(b.severity).padEnd(8);
+    error(`  ${id}  ${sev}  ${b.summary ?? ''}`);
+    if (b.detail) {
+      for (const line of String(b.detail).split('\n')) {
+        error(`                                          ${line}`);
+      }
+    }
+    if (b.fixCommand) {
+      error(`                                          $ ${b.fixCommand}`);
+    }
+  }
+  error('');
+  error(
+    '[preflight] exit 2 — fix the blockers above (or rerun the listed fix commands) and retry.',
+  );
+}
+
+/**
+ * Print warning/info findings as one line each. These never block.
+ *
+ * @param {Array<object>} findings
+ * @param {object} [logger]
+ */
+export function logNonBlockers(findings, logger = DEFAULT_LOGGER) {
+  const warn = pick(logger, 'warn');
+  for (const f of findings) {
+    warn(`[preflight] ${f.severity}: ${f.id} — ${f.summary ?? ''}`);
+    if (f.fixCommand) warn(`    $ ${f.fixCommand}`);
+  }
+}
+
+/**
+ * The reserved exit code for "preflight refused". Re-exported so consumer
+ * scripts can `process.exit(PREFLIGHT_REFUSED_EXIT_CODE)` instead of
+ * hard-coding the magic number.
+ */
+export const PREFLIGHT_REFUSED_EXIT_CODE = 2;

package/.agents/scripts/lib/presentation/dispatch-manifest-render.js

@@ -0,0 +1,95 @@
+/**
+ * dispatch-manifest-render.js — pure helper that renders the
+ * `dispatch-manifest` structured-comment body posted on an Epic.
+ *
+ * Extracted from `manifest-renderer.js::postManifestEpicComment` so the
+ * wave-runner's manifest refresh hop can render the same Markdown in
+ * process without spawning `dispatcher.js --dry-run`.
+ *
+ * No top-level side effects — safe to import from tests without
+ * triggering GitHub I/O.
+ */
+
+/**
+ * Pure: project a full dispatch manifest into the `{ stories }` shape
+ * `renderManifest` accepts. Returns the canonical, non-feature,
+ * non-ungrouped story rows used by the Epic-level dispatch-manifest
+ * comment.
+ *
+ * @param {object} manifest
+ * @returns {{ storyId: number|string, wave: number, title: string }[]}
+ */
+export function projectStoriesFromManifest(manifest) {
+  const storyManifest = manifest?.storyManifest ?? [];
+  return storyManifest
+    .filter((s) => s && s.type !== 'feature' && s.storyId !== '__ungrouped__')
+    .map((s) => ({
+      storyId: s.storyId,
+      wave: s.earliestWave ?? -1,
+      title: s.storyTitle ?? s.storySlug ?? '',
+    }));
+}
+
+/**
+ * Pure: count distinct, non-(-1) wave indexes across `stories`.
+ *
+ * @param {{ wave: number }[]} stories
+ */
+export function countWaves(stories) {
+  const set = new Set();
+  for (const s of stories ?? []) {
+    if (s && typeof s.wave === 'number' && s.wave !== -1) set.add(s.wave);
+  }
+  return set.size;
+}
+
+/**
+ * Pure: render the dispatch-manifest comment body for an Epic.
+ *
+ * The output is byte-identical to the body
+ * `postManifestEpicComment` historically built inline, so it can be
+ * upserted by either the dispatcher (CLI path) or the wave-runner
+ * (in-process refresh path) without behavioural drift.
+ *
+ * @param {{
+ *   epicId: number,
+ *   stories: { storyId: number|string, wave: number, title: string }[],
+ *   generatedAt: string,
+ * }} args
+ * @returns {string}
+ */
+export function renderManifest({ epicId, stories, generatedAt }) {
+  if (!Number.isFinite(epicId) && typeof epicId !== 'number') {
+    throw new TypeError('renderManifest: epicId is required');
+  }
+  const list = Array.isArray(stories) ? stories : [];
+  const waveCount = countWaves(list);
+  return [
+    `## 📋 Dispatch Manifest — Epic #${epicId}`,
+    '',
+    `- **Waves:** ${waveCount || 1}`,
+    `- **Stories:** ${list.length}`,
+    `- **Generated:** ${generatedAt}`,
+    '',
+    'Source of truth for the wave-completeness gate run at `/epic-deliver`.',
+    '',
+    '```json',
+    JSON.stringify({ stories: list }, null, 2),
+    '```',
+  ].join('\n');
+}
+
+/**
+ * Convenience: render directly from a full manifest object. Equivalent
+ * to `renderManifest({ epicId, stories: projectStoriesFromManifest(m),
+ * generatedAt: m.generatedAt })`.
+ *
+ * @param {object} manifest
+ */
+export function renderManifestFromManifest(manifest) {
+  return renderManifest({
+    epicId: manifest?.epicId,
+    stories: projectStoriesFromManifest(manifest),
+    generatedAt: manifest?.generatedAt,
+  });
+}

package/.agents/scripts/lib/presentation/manifest-builder.js

@@ -0,0 +1,245 @@
+/**
+ * manifest-builder.js
+ *
+ * Pure projection: builds a manifest-shaped object from a structural spec
+ * (the `.agents/epics/<epic-id>.yaml` shape returned by
+ * `lib/spec/loader.js#loadSpec`) plus a state mapping (the sibling
+ * `<epic-id>.state.json` shape returned by `loadState`).
+ *
+ * Extracted from `manifest-formatter.js` (Story #1849 Task #1869). The
+ * shape projection used to be inlined in the formatter; pulling it out
+ * isolates the spec → manifest projection from the Markdown renderer and
+ * lets the per-feature / per-story guard cascade live behind a single
+ * private predicate (`validateSpecShape`) so the orchestrator function's
+ * CRAP score drops below 12.
+ *
+ * Story #3413 (3-tier cutover, final): the residual per-Task projection
+ * (the Task projector, the per-Story Task array, and the Task-count
+ * rollup) has been deleted. The walker (`projectFeatures`) now counts
+ * Stories directly, and `summary` carries Story-tier counts only
+ * (`totalStories` / `doneStories` / `progressPercent`), matching the
+ * canonical producer in `lib/orchestration/manifest-builder.js`.
+ *
+ * Story-level status surfaces on each `storyEntry.status` so downstream
+ * renderers read the Story's own `agent::*` label directly — the 3-tier
+ * "Stories are first-class lifecycle units" invariant.
+ *
+ * No fs / network access; pure transform. Caller supplies `state` from
+ * `lib/spec/loader.js#loadState`.
+ */
+
+import { AGENT_LABELS } from '../label-constants.js';
+
+/**
+ * Private: validate the per-level shape of a spec node before we project
+ * it into the manifest. Centralising the guards keeps
+ * `buildManifestFromSpec` linear instead of branching at every level — the
+ * function reads as a straight projection and the predicate carries the
+ * "is this thing iterable / object-shaped?" decisions.
+ *
+ * `level` describes which spec node we are validating:
+ *   - `'features'` → the spec-level `features` array
+ *   - `'stories'`  → a feature's `stories` array
+ *   - `'story'`    → a single Story object (must be a non-null object)
+ *
+ * Returns `true` when the node satisfies the shape contract for that
+ * level, `false` otherwise. The caller substitutes an empty array (for
+ * iterable levels) or skips the node (for object levels) on `false`.
+ *
+ * @param {string} level
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function validateSpecShape(level, value) {
+  switch (level) {
+    case 'features':
+    case 'stories':
+      return Array.isArray(value);
+    case 'story':
+      return value !== null && typeof value === 'object';
+    default:
+      return false;
+  }
+}
+
+/**
+ * Private factory: build the slug→id and slug→status resolvers from a
+ * state mapping. Returning the two closures from one factory keeps the
+ * branching that interprets the optional `state.mapping` shape out of
+ * `buildManifestFromSpec`'s body.
+ *
+ * Per Tech Spec #1483, agent::* status labels do not live in the spec.
+ * `resolveStatus` reads `state.mapping[slug].lastObservedAgentState` when
+ * present and falls back to `agent::ready` for un-mapped Stories.
+ * `resolveId` falls back to a deterministic `slug:<slug>` sentinel so
+ * the renderer never sees a null id.
+ *
+ * @param {{ mapping?: Record<string, { issueNumber?: number|null, lastObservedAgentState?: string|null }> }|null} state
+ * @returns {{ resolveId: (slug: string) => number|string, resolveStatus: (slug: string) => string }}
+ */
+function buildResolvers(state) {
+  const mapping =
+    state && typeof state.mapping === 'object' && state.mapping !== null
+      ? state.mapping
+      : {};
+
+  const resolveId = (slug) => {
+    const entry = mapping[slug];
+    const id =
+      entry && typeof entry.issueNumber === 'number' ? entry.issueNumber : null;
+    return id ?? `slug:${slug}`;
+  };
+  const resolveStatus = (slug) => {
+    const entry = mapping[slug];
+    return entry && typeof entry.lastObservedAgentState === 'string'
+      ? entry.lastObservedAgentState
+      : 'agent::ready';
+  };
+  return { resolveId, resolveStatus };
+}
+
+/**
+ * Private: project a single spec Story into a manifest Story entry. The
+ * Story's status is resolved directly from the Story-level label
+ * (`state.mapping[slug].lastObservedAgentState`) and surfaces on
+ * `storyEntry.status` — under the 3-tier hierarchy Stories carry their
+ * own lifecycle state and are leaves with no child Task tickets. Caller
+ * filters non-object stories with `validateSpecShape('story', ...)`
+ * before invoking.
+ *
+ * @param {object} story
+ * @param {{ resolveId: Function, resolveStatus: Function }} resolvers
+ * @returns {{ storyEntry: object, wave: number }}
+ */
+function projectStory(story, resolvers) {
+  const wave = Number.isInteger(story.wave) ? story.wave : -1;
+  const storyId = resolvers.resolveId(story.slug);
+  const status = resolvers.resolveStatus(story.slug);
+  const storyEntry = {
+    storyId,
+    storyTitle: story.title ?? '',
+    storySlug: story.slug ?? '',
+    type: 'story',
+    branchName:
+      typeof storyId === 'number' ? `story-${storyId}` : `story-${story.slug}`,
+    earliestWave: wave,
+    status,
+  };
+  return { storyEntry, wave };
+}
+
+/**
+ * Private: walk every feature → story pair in a spec and collect the
+ * per-story projections + Story-tier roll-up counters. Keeps the loop
+ * machinery out of `buildManifestFromSpec` so the entry point reads as a
+ * straight assembly of the result envelope.
+ *
+ * Under the 3-tier hierarchy (Epic #3163) Stories are leaves, so the
+ * rollup counts Stories directly: `totalStories` is every projected
+ * Story and `doneStories` is the subset carrying `agent::done`.
+ *
+ * @param {object[]} features
+ * @param {{ resolveId: Function, resolveStatus: Function }} resolvers
+ * @returns {{
+ *   storyManifest: object[],
+ *   totalStories: number,
+ *   doneStories: number,
+ *   waveSet: Set<number>,
+ * }}
+ */
+function projectFeatures(features, resolvers) {
+  const storyManifest = [];
+  let totalStories = 0;
+  let doneStories = 0;
+  const waveSet = new Set();
+  for (const feature of features) {
+    const stories = validateSpecShape('stories', feature?.stories)
+      ? feature.stories
+      : [];
+    for (const story of stories) {
+      if (!validateSpecShape('story', story)) continue;
+      const { storyEntry, wave } = projectStory(story, resolvers);
+      storyManifest.push(storyEntry);
+      totalStories++;
+      if (storyEntry.status === AGENT_LABELS.DONE) doneStories++;
+      if (wave >= 0) waveSet.add(wave);
+    }
+  }
+  return { storyManifest, totalStories, doneStories, waveSet };
+}
+
+/**
+ * Build a manifest-shaped object from a spec entry. Mirrors the contract
+ * produced by `lib/orchestration/manifest-builder.js#buildManifest` so
+ * `formatManifestMarkdown` (the renderer that backs `fromManifest`)
+ * accepts it without modification.
+ *
+ * Slug→issue-number resolution prefers `state.mapping[slug].issueNumber`
+ * when present and falls back to a deterministic `slug:<slug>` sentinel
+ * so the renderer never sees a null id. Status labels prefer
+ * `state.mapping[slug].lastObservedAgentState` and fall back to
+ * `agent::ready` per Tech Spec #1483.
+ *
+ * Pure — does not touch fs or the network. Caller supplies `state` from
+ * `lib/spec/loader.js#loadState`.
+ *
+ * @param {object} spec — parsed epic-spec (see `lib/spec/loader.js`).
+ * @param {{
+ *   state?: { mapping?: Record<string, { issueNumber?: number|null, lastObservedAgentState?: string|null }> },
+ *   generatedAt?: string,
+ *   executor?: string,
+ *   dryRun?: boolean,
+ *   agentTelemetry?: object|null,
+ * }} [opts]
+ * @returns {object} manifest object matching the shape `formatManifestMarkdown` consumes.
+ */
+export function buildManifestFromSpec(spec, opts = {}) {
+  const resolvers = buildResolvers(opts.state ?? null);
+  const epicId =
+    spec?.epic && typeof spec.epic.id === 'number' ? spec.epic.id : null;
+  const epicTitle =
+    spec?.epic && typeof spec.epic.title === 'string' ? spec.epic.title : '';
+  const features = validateSpecShape('features', spec?.features)
+    ? spec.features
+    : [];
+
+  const { storyManifest, totalStories, doneStories, waveSet } = projectFeatures(
+    features,
+    resolvers,
+  );
+
+  const progressPercent =
+    totalStories > 0 ? Math.round((doneStories / totalStories) * 100) : 0;
+
+  return {
+    schemaVersion: '1.0.0',
+    generatedAt: opts.generatedAt ?? new Date().toISOString(),
+    epicId,
+    epicTitle,
+    executor: opts.executor ?? 'spec',
+    dryRun: opts.dryRun ?? false,
+    summary: {
+      totalStories,
+      doneStories,
+      progressPercent,
+      totalWaves: waveSet.size,
+      dispatched: 0,
+    },
+    waves: [],
+    storyManifest,
+    dispatched: [],
+    agentTelemetry: opts.agentTelemetry ?? null,
+    // Cross-Story conflict findings forwarded by the validator (Story
+    // #2296). The formatter only emits the hazards block when this key
+    // is *defined* — undefined means the caller didn't compute findings
+    // for this manifest (e.g. live progress reporter ticks), so the
+    // section is suppressed rather than showing a misleading "no
+    // hazards" line.
+    concurrencyFindings: opts.concurrencyFindings,
+  };
+}
+
+// Test-only: surface the private predicate so the sibling unit test can
+// exercise each branch without going through the full builder. Export
+// stays underscored to signal "internal" to production callers.
+export const __testables = { validateSpecShape };