mandrel 1.57.0

package/.agents/scripts/lib/orchestration/lifecycle/trace-logger.js

@@ -0,0 +1,322 @@
+// .agents/scripts/lib/orchestration/lifecycle/trace-logger.js
+/**
+ * TraceLogger — renders the human-readable `lifecycle.md` companion
+ * from the canonical NDJSON ledger.
+ *
+ * The companion is a strict projection of the ledger: re-rendering the
+ * same ledger produces byte-identical Markdown (modulo wall-clock `ts`
+ * formatting). Editing the companion does NOT affect resume; only the
+ * NDJSON ledger is canonical. This is repeatability AC #12.
+ *
+ * `render(ledger)` is the pure function consumers should call.
+ * `TraceLogger.register(bus, writerLedgerPath)` installs the wildcard
+ * observer + the on-write side that keeps the companion in sync after
+ * every emit, but it does so by re-reading the NDJSON file and calling
+ * `render()` — there is no in-memory drift.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Format an ISO-8601 timestamp as HH:MM:SS for the per-event line. The
+ * `(durationMs)` chunk is computed from the gap between `emitted` and
+ * `completed` (or `failed`) of the same seqId.
+ */
+function formatClock(iso) {
+  // The ledger record schema requires ISO date-time strings (validated
+  // up-stream); a defensive `Date` parse here is just for resilience.
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '??:??:??';
+  const hh = String(d.getUTCHours()).padStart(2, '0');
+  const mm = String(d.getUTCMinutes()).padStart(2, '0');
+  const ss = String(d.getUTCSeconds()).padStart(2, '0');
+  return `${hh}:${mm}:${ss}`;
+}
+
+/**
+ * Phase header derived from event name. The companion is grouped by
+ * phase so operators can scan to the section that interests them. The
+ * mapping is stable across runs.
+ */
+const PHASE_BY_PREFIX = Object.freeze({
+  'epic.snapshot': 'Snapshot',
+  'epic.plan': 'Plan',
+  'story.dispatch': 'Waves',
+  'story.merged': 'Waves',
+  'story.blocked': 'Waves',
+  'epic.blocked': 'Waves',
+  'epic.close': 'Close-tail',
+  'acceptance.reconcile': 'Acceptance Reconciliation',
+  'epic.finalize': 'Finalize',
+  'pr.created': 'Finalize',
+  'epic.watch': 'Watch',
+  'epic.automerge': 'Automerge',
+  'epic.merge': 'Automerge',
+  'epic.cleanup': 'Cleanup',
+  'epic.complete': 'Complete',
+  'notification.emitted': 'Notifications',
+  'checkpoint.written': 'Checkpoint',
+});
+
+function phaseFor(eventName) {
+  // Match longest prefix first so `epic.snapshot.start` resolves before
+  // `epic.snapshot` would match an unrelated `epic.*` block.
+  const keys = Object.keys(PHASE_BY_PREFIX).sort((a, b) => b.length - a.length);
+  for (const k of keys) {
+    if (eventName === k || eventName.startsWith(`${k}.`)) {
+      return PHASE_BY_PREFIX[k];
+    }
+  }
+  return 'Other';
+}
+
+/**
+ * Render the payload summary chunk for a per-event line. We keep it
+ * short: keys + scalar values, no nested object dumps (the canonical
+ * NDJSON ledger is the place to recover full payloads). This matches
+ * the Tech Spec spec: "payload-summary".
+ */
+function summarizePayload(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  const parts = [];
+  for (const [k, v] of Object.entries(payload)) {
+    if (v == null) continue;
+    if (
+      typeof v === 'string' ||
+      typeof v === 'number' ||
+      typeof v === 'boolean'
+    ) {
+      parts.push(`${k}=${v}`);
+    } else if (Array.isArray(v)) {
+      parts.push(`${k}=[${v.length}]`);
+    } else if (typeof v === 'object') {
+      const keys = Object.keys(v);
+      parts.push(`${k}={${keys.length}}`);
+    }
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Parse an NDJSON ledger string into an array of records. Blank lines
+ * and trailing whitespace are tolerated; malformed lines throw with
+ * line number so the operator can locate the corruption.
+ */
+export function parseLedger(text) {
+  const out = [];
+  const lines = String(text || '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (_err) {
+      throw new Error(
+        `lifecycle ledger: malformed JSON on line ${i + 1}: ${line.slice(0, 80)}`,
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * Pure render of a parsed ledger to Markdown. Same input → byte-identical
+ * output (modulo `ts` field formatting, which is wall-clock by design).
+ *
+ * Layout (mirroring Tech Spec § Human-readable companion):
+ *   # Lifecycle — epic <id>
+ *
+ *   ## <Phase>
+ *   HH:MM:SS  event.name  (durationMs)  payload-summary
+ *   ...
+ *
+ *   ## Summary
+ *   - Events: N
+ *   - Failed: N
+ *   - …
+ */
+export function render(ledger, opts = {}) {
+  const records = Array.isArray(ledger) ? ledger : parseLedger(ledger);
+  const emittedBySeq = new Map();
+  const terminalBySeq = new Map(); // seqId -> 'completed' | 'failed' record
+  for (const rec of records) {
+    if (!rec || typeof rec !== 'object') continue;
+    if (rec.kind === 'emitted') emittedBySeq.set(rec.seqId, rec);
+    else if (rec.kind === 'completed' || rec.kind === 'failed')
+      terminalBySeq.set(rec.seqId, rec);
+  }
+
+  const phaseOrder = [];
+  const phaseLines = new Map();
+  for (const emit of [...emittedBySeq.values()].sort(
+    (a, b) => a.seqId - b.seqId,
+  )) {
+    const phase = phaseFor(emit.event);
+    if (!phaseLines.has(phase)) {
+      phaseLines.set(phase, []);
+      phaseOrder.push(phase);
+    }
+    const terminal = terminalBySeq.get(emit.seqId);
+    let durationMs = '';
+    if (terminal) {
+      const start = new Date(emit.ts).getTime();
+      const end = new Date(terminal.ts).getTime();
+      if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+        durationMs = `(${end - start}ms)`;
+      }
+    } else {
+      durationMs = '(pending)';
+    }
+    const summary = summarizePayload(emit.payload);
+    const failedMarker =
+      terminal && terminal.kind === 'failed' ? ' ⚠️ FAILED' : '';
+    const parts = [
+      formatClock(emit.ts),
+      emit.event,
+      durationMs,
+      summary,
+    ].filter(Boolean);
+    phaseLines.get(phase).push(parts.join('  ') + failedMarker);
+  }
+
+  const lines = [];
+  const epicId = opts.epicId ? `epic ${opts.epicId}` : 'epic';
+  lines.push(`# Lifecycle — ${epicId}`);
+  lines.push('');
+  for (const phase of phaseOrder) {
+    lines.push(`## ${phase}`);
+    lines.push('');
+    for (const l of phaseLines.get(phase)) {
+      lines.push(l);
+    }
+    lines.push('');
+  }
+  // Summary block
+  const totalEvents = emittedBySeq.size;
+  const failedCount = [...terminalBySeq.values()].filter(
+    (r) => r.kind === 'failed',
+  ).length;
+  const completedCount = totalEvents - failedCount;
+  const phaseDurations = [];
+  for (const phase of phaseOrder) {
+    const seqIds = [...emittedBySeq.values()]
+      .filter((e) => phaseFor(e.event) === phase)
+      .map((e) => e.seqId);
+    if (seqIds.length === 0) continue;
+    let minStart = Infinity;
+    let maxEnd = -Infinity;
+    for (const sid of seqIds) {
+      const e = emittedBySeq.get(sid);
+      const t = terminalBySeq.get(sid);
+      const start = new Date(e.ts).getTime();
+      if (Number.isFinite(start) && start < minStart) minStart = start;
+      if (t) {
+        const end = new Date(t.ts).getTime();
+        if (Number.isFinite(end) && end > maxEnd) maxEnd = end;
+      }
+    }
+    if (Number.isFinite(minStart) && Number.isFinite(maxEnd)) {
+      phaseDurations.push(`  - ${phase}: ${maxEnd - minStart}ms`);
+    }
+  }
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- Events: ${totalEvents}`);
+  lines.push(`- Completed: ${completedCount}`);
+  lines.push(`- Failed: ${failedCount}`);
+  if (phaseDurations.length > 0) {
+    lines.push('- Phase durations:');
+    for (const pd of phaseDurations) lines.push(pd);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * TraceLogger wires `render()` against a live bus + ledger file. It is
+ * a wildcard observer: it does not mutate state under orchestration, it
+ * only re-renders the companion markdown on every event.
+ *
+ * The wildcard-firewall rule (Tech Spec § Bus contract) requires that
+ * trace observers do NOT import any module that mutates GitHub state,
+ * the worktree, or the filesystem outside `temp/epic-<id>/`. This
+ * module satisfies that constraint: the only filesystem writes are to
+ * the companion path under the same temp directory the ledger lives
+ * in.
+ */
+export class TraceLogger {
+  /**
+   * @param {object} opts
+   * @param {string} opts.ledgerPath - absolute path to the NDJSON ledger
+   *   the bus is writing (matches `LedgerWriter.ledgerPath`).
+   * @param {number} [opts.epicId] - included in the companion header.
+   */
+  constructor(opts) {
+    if (
+      !opts ||
+      typeof opts.ledgerPath !== 'string' ||
+      opts.ledgerPath.length === 0
+    ) {
+      throw new TypeError('TraceLogger: opts.ledgerPath is required');
+    }
+    this._ledgerPath = opts.ledgerPath;
+    this._companionPath = path.join(
+      path.dirname(this._ledgerPath),
+      'lifecycle.md',
+    );
+    this._epicId = opts.epicId ?? null;
+  }
+
+  get companionPath() {
+    return this._companionPath;
+  }
+
+  /**
+   * Re-render the companion from the on-disk ledger. Idempotent.
+   */
+  rerender() {
+    let text;
+    try {
+      text = readFileSync(this._ledgerPath, 'utf8');
+    } catch (err) {
+      if (err && err.code === 'ENOENT') return; // ledger not yet written
+      throw err;
+    }
+    const markdown = render(text, { epicId: this._epicId });
+    writeFileSync(this._companionPath, markdown, 'utf8');
+  }
+
+  /**
+   * Register as a wildcard observer. After every emit, re-read the
+   * ledger and re-render the companion.
+   *
+   * The companion render is a best-effort projection: a failed render
+   * (malformed ledger, transient write error, full disk) MUST NOT abort
+   * the in-flight bus emit. Because wildcard listeners run inside the
+   * `emit()` try/catch (see `bus.js`), an unguarded throw here would
+   * short-circuit the emit and propagate to the orchestration caller.
+   * We instead log the failure to stderr and swallow it, degrading to a
+   * stale `lifecycle.md` companion — the canonical NDJSON ledger is
+   * unaffected, so resume and downstream consumers are not broken.
+   */
+  register(bus) {
+    if (!bus || typeof bus.on !== 'function') {
+      throw new TypeError('TraceLogger.register: bus must expose .on()');
+    }
+    bus.on('*', () => {
+      try {
+        this.rerender();
+      } catch (err) {
+        const message = err && err.message ? err.message : String(err);
+        process.stderr.write(
+          `[TraceLogger] companion rerender failed (degrading to stale lifecycle.md): ${message}\n`,
+        );
+      }
+    });
+  }
+}
+
+export function createTraceLogger(opts) {
+  return new TraceLogger(opts);
+}

package/.agents/scripts/lib/orchestration/lint-baseline-service.js

@@ -0,0 +1,114 @@
+/**
+ * lib/orchestration/lint-baseline-service.js
+ *
+ * Captures the Epic lint baseline (see `lint-baseline.js capture`). Extracted
+ * from the inline implementation that used to live in `dispatch-engine.js`
+ * so the coordinator no longer reaches into `node:child_process` or
+ * `node:fs` directly. Tests can exercise the service with a stubbed exec
+ * adapter and no filesystem interaction.
+ */
+
+import defaultFs from 'node:fs';
+import path from 'node:path';
+import { getBaselines, getPaths, PROJECT_ROOT } from '../config-resolver.js';
+
+/**
+ * Shape of the exec adapter passed into {@link LintBaselineService}.
+ *
+ * Implementations may be sync (e.g. `execFileSync`) or async; the service
+ * always `await`s the return value so either works.
+ *
+ * @typedef {(file: string, args: string[], options?: object) => (void | Promise<void>)} LintBaselineExec
+ */
+
+/**
+ * Minimal logger shape consumed by {@link LintBaselineService}. Matches the
+ * surviving `lib/Logger.js` surface (single-argument message form).
+ *
+ * @typedef {object} LintBaselineLogger
+ * @property {(msg: string) => void} info
+ * @property {(msg: string) => void} warn
+ */
+
+/**
+ * Outcome of {@link LintBaselineService#capture}.
+ *
+ * @typedef {object} LintBaselineCaptureResult
+ * @property {boolean} skipped                   True when the baseline file already existed on disk.
+ * @property {boolean} [captured]                True when the exec adapter ran and succeeded.
+ * @property {string} [error]                    Error message when the exec adapter threw (still non-fatal).
+ */
+
+export class LintBaselineService {
+  /**
+   * @param {object} deps
+   * @param {LintBaselineExec} deps.exec           Injected exec adapter — invoked with `(file, args, options)`.
+   * @param {LintBaselineLogger} deps.logger       Logger for skip / capture / failure messages.
+   * @param {object} deps.settings                 `.agentrc.json` `settings` block.
+   *   The baseline artifact path is resolved via
+   *   `getBaselines(settings).lint.path` (default
+   *   `baselines/lint.json`); operators override under
+   *   `delivery.quality.gates.lint.baselinePath`.
+   *   `scriptsRoot` is resolved via `getPaths(settings)`
+   *   (lives at `project.paths.scriptsRoot` post-Epic #773 Story 9).
+   * @param {typeof import('node:fs')} [deps.fs]   Optional `fs` module (defaults to `node:fs`). Kept injectable so unit tests can assert no real-disk access.
+   */
+  constructor({ exec, logger, settings, fs = defaultFs }) {
+    this.exec = exec;
+    this.logger = logger;
+    this.settings = settings;
+    this.fs = fs;
+  }
+
+  /**
+   * Capture (or skip) the lint baseline for the given Epic branch.
+   *
+   * Behaviour:
+   * - If the baseline artifact already exists, log a skip and return
+   *   `{ skipped: true }` — **no exec call is made**.
+   * - Otherwise invoke the injected exec adapter to run
+   *   `node <scriptsRoot>/lint-baseline.js capture`.
+   * - Exec failures are logged at `warn` and swallowed — baseline capture
+   *   is advisory and must never break the dispatch cycle.
+   *
+   * @param {string} epicBranch  Epic branch name (used for logging only).
+   * @returns {Promise<LintBaselineCaptureResult>}  Resolution of the capture attempt.
+   */
+  async capture(epicBranch) {
+    const { settings, logger, exec, fs } = this;
+    // `settings` is the legacy-shim view (`{ paths, quality, ... }`). The
+    // post-reshape accessors read `project.paths` and `delivery.quality`;
+    // the shim's pointers are reference-equal to the canonical blocks, so
+    // re-wrap here.
+    const canonical = {
+      project: { paths: settings?.paths },
+      delivery: { quality: settings?.quality },
+    };
+    const lintBaselinePath = getBaselines(canonical).lint.path;
+    const absPath = path.resolve(PROJECT_ROOT, lintBaselinePath);
+
+    if (fs.existsSync(absPath)) {
+      logger.info('Lint baseline already exists, skipping capture.');
+      return { skipped: true };
+    }
+
+    logger.info(`Capturing lint baseline on ${epicBranch}...`);
+    const scriptsRoot = getPaths(canonical).scriptsRoot;
+    try {
+      await exec(
+        'node',
+        [path.join(PROJECT_ROOT, scriptsRoot, 'lint-baseline.js'), 'capture'],
+        {
+          cwd: PROJECT_ROOT,
+          encoding: 'utf8',
+          stdio: 'inherit',
+          shell: false,
+        },
+      );
+      return { skipped: false, captured: true };
+    } catch (err) {
+      logger.warn(`Lint baseline capture failed (non-fatal): ${err.message}`);
+      return { skipped: false, captured: false, error: err.message };
+    }
+  }
+}

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

@@ -0,0 +1,216 @@
+/**
+ * lib/orchestration/manifest-builder.js — Manifest Building Logic
+ *
+ * 3-tier-only producer. Reads Story tickets from `allTickets` directly,
+ * computes Story-scoped waves, and emits the `waves[].stories[]` /
+ * Story-only `storyManifest` shape. The pre-Epic-#3163 Task-tier branch
+ * has been removed; the framework no longer carries a Task-tier
+ * producer path.
+ */
+
+import { parseBlockedBy } from '../dependency-parser.js';
+import { getStoryBranch, slugify } from '../git-utils.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { computeStoryWaves } from './dependency-analyzer.js';
+import { STATE_LABELS } from './ticketing.js';
+
+/**
+ * Extract the markdown list items under a `## <heading>` section of a
+ * Story body. Returns an empty array when the section is missing or has
+ * no list items. Recognises both `- ` (incl. `- [ ]` / `- [x]`) and
+ * `* ` bullet markers — the same set the schema expects to round-trip
+ * verbatim per the manifest dispatch-manifest contract.
+ *
+ * @param {string} body
+ * @param {string} heading
+ * @returns {string[]}
+ */
+function extractSectionList(body, heading) {
+  if (typeof body !== 'string' || body.length === 0) return [];
+  const pattern = new RegExp(
+    `^##\\s+${heading.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\s*$`,
+    'mi',
+  );
+  const startMatch = body.match(pattern);
+  if (!startMatch || startMatch.index == null) return [];
+  const startIdx = startMatch.index + startMatch[0].length;
+  const rest = body.slice(startIdx);
+  const nextHeading = rest.search(/^##\s+/m);
+  const block = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+  const items = [];
+  for (const rawLine of block.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const m = line.match(/^[-*]\s+(?:\[[ xX]\]\s+)?(.*)$/);
+    if (m && m[1].length > 0) items.push(m[1].trim());
+  }
+  return items;
+}
+
+/**
+ * Project a Story ticket into the inline-acceptance/verify shape required by
+ * the 3-tier waves[].stories[] schema. Reads `## Acceptance` /
+ * `## Acceptance Criteria` and `## Verify` sections from the body.
+ *
+ * @param {object} story
+ * @param {number} epicId
+ * @returns {object}
+ */
+function projectStoryForWave(story, epicId) {
+  const body = story.body ?? '';
+  const acceptanceCriteria = extractSectionList(body, 'Acceptance Criteria');
+  const acceptanceItems =
+    acceptanceCriteria.length > 0
+      ? acceptanceCriteria
+      : extractSectionList(body, 'Acceptance');
+  const verifyItems = extractSectionList(body, 'Verify');
+  const fromBody = parseBlockedBy(body);
+  const fromField = Array.isArray(story.dependencies)
+    ? story.dependencies.map(Number)
+    : [];
+  const dependsOn = [...new Set([...fromBody, ...fromField])].filter((id) =>
+    Number.isInteger(id),
+  );
+  const labels = story.labels ?? [];
+  const personaLabel = labels.find((l) => l.startsWith('persona::'));
+  const persona =
+    story.persona ??
+    (personaLabel ? personaLabel.replace('persona::', '') : 'engineer');
+  const status =
+    story.status ??
+    labels.find((l) => l.startsWith('agent::')) ??
+    'agent::ready';
+
+  return {
+    storyId: story.id,
+    title: story.title ?? '',
+    status,
+    branch: getStoryBranch(epicId, story.id),
+    persona,
+    acceptance: acceptanceItems,
+    verify: verifyItems,
+    dependsOn,
+  };
+}
+
+const AGENT_DONE_LABEL = STATE_LABELS.DONE;
+
+/**
+ * Build the Story-only manifest array used by the 3-tier hierarchy path.
+ * Reads Story tickets directly from `allTickets`; there is no Task tier
+ * to walk. Each entry exposes an empty `tasks: []` to keep downstream
+ * consumers (renderers, dispatch helpers) on a single per-Story shape
+ * until Category 4 of Epic #3163 rewrites them.
+ *
+ * @param {object[]} stories  Story tickets (each with `id`, `title`,
+ *                            `body`, `labels`, optional `dependencies`).
+ * @param {number}   epicId
+ * @returns {object[]}
+ */
+function buildStoryOnlyManifest(stories, epicId) {
+  const storyById = new Map(stories.map((s) => [s.id, s]));
+  const explicitStoryDeps = new Map();
+  for (const story of stories) {
+    const fromBody = parseBlockedBy(story.body ?? '');
+    const fromField = Array.isArray(story.dependencies)
+      ? story.dependencies.map(Number)
+      : [];
+    const merged = [...new Set([...fromBody, ...fromField])].filter(
+      (id) => Number.isInteger(id) && id !== story.id && storyById.has(id),
+    );
+    if (merged.length > 0) explicitStoryDeps.set(story.id, merged);
+  }
+
+  // Reuse `computeStoryWaves` by adapting Stories to its `storyGroups`
+  // input shape: a Map keyed by storyId whose values look like grouper
+  // output. With no Tasks, every group's `tasks: []` collapses the
+  // task-level wave inference to a no-op; only `explicitDeps` drives
+  // ordering.
+  const storyGroups = new Map(
+    stories.map((s) => [s.id, { storyId: s.id, tasks: [] }]),
+  );
+  const storyWaves = computeStoryWaves(storyGroups, explicitStoryDeps);
+
+  return stories.map((story) => {
+    const earliestWave = storyWaves.get(story.id) ?? -1;
+    return {
+      storyId: story.id,
+      storyTitle: story.title ?? '',
+      storySlug: slugify(story.title ?? `story-${story.id}`),
+      type: 'story',
+      branchName: getStoryBranch(epicId, story.id),
+      earliestWave,
+      tasks: [],
+    };
+  });
+}
+
+/**
+ * Build the wave records for a 3-tier manifest. Each wave entry exposes a
+ * `stories[]` projection (instead of the legacy `tasks[]`) so dispatch
+ * consumers can fan Story execution out wave-by-wave without ever seeing
+ * a `type::task` ticket.
+ *
+ * @param {object[][]} waves   Story waves (array of Story-ticket arrays).
+ * @param {number}     epicId
+ * @returns {object[]}
+ */
+function buildStoryWaves(waves, epicId) {
+  return waves.map((wave, i) => ({
+    waveIndex: i,
+    stories: wave.map((s) => projectStoryForWave(s, epicId)),
+  }));
+}
+
+/**
+ * Build the full Dispatch Manifest object.
+ *
+ * Epic #3163, Category 2 deleted the legacy Task-tier
+ * `waves[].tasks[]` branch and the Task-grouping import this module
+ * used to pull from the removed helper. The producer is now
+ * Story-only: it filters `allTickets` to the Story tier, computes
+ * Story-scoped waves, and emits `waves[].stories[]` plus a Story-only
+ * `storyManifest`.
+ *
+ * @param {object} params
+ * @returns {object}
+ */
+export function buildManifest({
+  epicId,
+  epic,
+  allTickets,
+  waves,
+  dispatched,
+  dryRun,
+  agentTelemetry = null,
+}) {
+  const stories = (allTickets ?? []).filter((t) =>
+    (t.labelSet ?? new Set(t.labels ?? [])).has(TYPE_LABELS.STORY),
+  );
+  const totalStories = stories.length;
+  const doneStories = stories.filter((s) =>
+    (s.labelSet ?? new Set(s.labels ?? [])).has(AGENT_DONE_LABEL),
+  ).length;
+  const progress =
+    totalStories > 0 ? Math.round((doneStories / totalStories) * 100) : 0;
+
+  return {
+    schemaVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    epicId,
+    epicTitle: epic?.title ?? '',
+    executor: 'claude-code',
+    dryRun,
+    hierarchy: '3-tier',
+    summary: {
+      totalStories,
+      doneStories,
+      progressPercent: progress,
+      totalWaves: waves.length,
+      dispatched: dispatched.length,
+    },
+    waves: buildStoryWaves(waves, epicId),
+    storyManifest: buildStoryOnlyManifest(stories, epicId),
+    dispatched,
+    agentTelemetry,
+  };
+}