mandrel 1.57.0

package/.agents/scripts/lib/orchestration/finalize/post-handoff-comment.js

@@ -0,0 +1,489 @@
+// .agents/scripts/lib/orchestration/finalize/post-handoff-comment.js
+/**
+ * post-handoff-comment.js — finalize helper that upserts the
+ * `epic-handoff` structured comment on the Epic at the end of the
+ * bus-owned finalize flow.
+ *
+ * The Phase 7.1 prose previously asked operators to leave a free-form
+ * "PR opened, see #N" comment after `gh pr create`. Lifting that
+ * into a structured-marker upsert means the comment is:
+ *
+ *   - addressable by the `epic-handoff` marker (operators and tooling
+ *     can find the canonical PR pointer without scrolling);
+ *   - idempotent under finalize replay (re-invoking the helper edits
+ *     the existing comment rather than fanning out duplicates).
+ *
+ * Story #2894 / Task #2909 (Epic #2880).
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  epicLedgerPath,
+  epicPerfReportJsonPath,
+} from '../../config/temp-paths.js';
+import { Logger } from '../../Logger.js';
+import { render as renderLifecycleTrace } from '../lifecycle/trace-logger.js';
+import { upsertStructuredComment as defaultUpsertStructuredComment } from '../ticketing.js';
+
+export const EPIC_HANDOFF_MARKER = 'epic-handoff';
+
+/**
+ * Byte budget for the embedded run-trace digest. The digest is the
+ * `TraceLogger` Summary block only (phase list + per-phase durations +
+ * event/completed/failed counts), so it is small by construction — but we
+ * cap it well under GitHub's ~64KB comment limit so a pathological ledger
+ * with a huge phase list still degrades to a truncated note + the
+ * relative-path link rather than blowing the comment budget. Story #3669.
+ */
+export const RUN_TRACE_MAX_BYTES = 8000;
+
+/**
+ * Format a millisecond duration as a compact wall-clock string for the
+ * per-wave perf summary lines. Sub-second values render as `<n>ms`;
+ * second-scale values as `<n.n>s`; minute-scale values as `<m>m<ss>s`.
+ * Story #3029 / Task #3041.
+ *
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDurationMs(ms) {
+  const n = Number.isFinite(ms) ? Math.max(0, Math.floor(ms)) : 0;
+  if (n < 1000) return `${n}ms`;
+  if (n < 60000) return `${(n / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(n / 60000);
+  const seconds = Math.floor((n % 60000) / 1000);
+  return `${minutes}m${seconds.toString().padStart(2, '0')}s`;
+}
+
+/**
+ * Render the Performance Report section appended to the `epic-handoff`
+ * comment body. Returns an empty string when `perfReport` is null /
+ * undefined (no JSON on disk → section omitted) so callers can splice
+ * the result in unconditionally.
+ *
+ * Output contract (Story #3029 / Task #3041):
+ *   - `## Performance Report` heading
+ *   - One relative link line to `temp/epic-<id>/epic-perf-report.json`
+ *   - One bullet per wave: `Wave N: <wall> wall / <story> story / util <pct>% [cap binding]`
+ *
+ * @param {{
+ *   relativePath: string,
+ *   waveParallelism: Array<{ waveIndex: number, wallClockMs: number, summedStoryMs: number, utilisation: number, capBinding: boolean, verifyConcurrencyCap?: number }>,
+ * } | null | undefined} perfReport
+ * @returns {string}
+ */
+export function renderPerfReportSection(perfReport) {
+  if (!perfReport || typeof perfReport.relativePath !== 'string') return '';
+  const waves = Array.isArray(perfReport.waveParallelism)
+    ? perfReport.waveParallelism
+    : [];
+  const lines = [];
+  lines.push('');
+  lines.push('## Performance Report');
+  lines.push('');
+  lines.push(
+    `Persisted to [\`${perfReport.relativePath}\`](${perfReport.relativePath}).`,
+  );
+  lines.push('');
+  if (waves.length === 0) {
+    lines.push('No wave-parallelism rows recorded.');
+  } else {
+    for (const wave of waves) {
+      const wall = formatDurationMs(wave.wallClockMs);
+      const story = formatDurationMs(wave.summedStoryMs);
+      const util = Number.isFinite(wave.utilisation)
+        ? (wave.utilisation * 100).toFixed(0)
+        : '0';
+      const capLabel = wave.capBinding ? 'cap binding' : 'cap not binding';
+      lines.push(
+        `- Wave ${wave.waveIndex}: ${wall} wall / ${story} story / util ${util}% [${capLabel}]`,
+      );
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Slice the `## Summary` block out of the full `lifecycle.md` projection.
+ * The TraceLogger `render()` output ends with a `## Summary` section (phase
+ * list, per-phase durations, event/completed/failed counts); everything
+ * before it is the per-event trace, which the Story explicitly excludes
+ * from the embedded digest. Returns the Summary body (the lines *after* the
+ * `## Summary` heading, trimmed) or `''` when no Summary heading is present.
+ *
+ * @param {string} fullMarkdown
+ * @returns {string}
+ */
+function summaryBlockFrom(fullMarkdown) {
+  const marker = '## Summary';
+  const idx = fullMarkdown.indexOf(marker);
+  if (idx < 0) return '';
+  return fullMarkdown.slice(idx + marker.length).trim();
+}
+
+/**
+ * Project the canonical lifecycle ledger NDJSON into the compact run-trace
+ * digest embedded in the handoff comment. Reuses the pure `TraceLogger`
+ * `render()` projection and keeps only its Summary rollup — never the full
+ * per-event trace (Story #3669 acceptance).
+ *
+ * Pure + read-only: it parses the supplied ledger text and never touches
+ * the filesystem or mutates the ledger. Returns `null` on:
+ *   - a missing / empty ledger (no emitted records → empty Summary), or
+ *   - a malformed ledger (the underlying `render` throws on bad JSON; we
+ *     swallow it so the section degrades gracefully instead of blocking
+ *     the PR open).
+ *
+ * When the projected Summary exceeds `maxBytes`, the digest is truncated on
+ * a UTF-8-safe boundary and `truncated: true` is set so the renderer can
+ * append a note and keep the relative-path link to the full `lifecycle.md`.
+ *
+ * @param {{
+ *   ledgerText: string,
+ *   epicId: number,
+ *   relativePath: string,
+ *   maxBytes?: number,
+ * }} args
+ * @returns {{ digest: string, relativePath: string, truncated: boolean } | null}
+ */
+export function extractRunTraceDigest({
+  ledgerText,
+  epicId,
+  relativePath,
+  maxBytes = RUN_TRACE_MAX_BYTES,
+} = {}) {
+  if (typeof ledgerText !== 'string' || ledgerText.trim().length === 0) {
+    return null;
+  }
+  let fullMarkdown;
+  try {
+    fullMarkdown = renderLifecycleTrace(ledgerText, { epicId });
+  } catch {
+    // Malformed ledger (parseLedger throws on bad JSON). Degrade to no
+    // section rather than propagating and blocking the handoff comment.
+    return null;
+  }
+  const summary = summaryBlockFrom(fullMarkdown);
+  if (summary.length === 0) return null;
+
+  const budget =
+    Number.isInteger(maxBytes) && maxBytes > 0 ? maxBytes : RUN_TRACE_MAX_BYTES;
+  if (Buffer.byteLength(summary, 'utf8') <= budget) {
+    return { digest: summary, relativePath, truncated: false };
+  }
+  // Truncate on a UTF-8-safe boundary: take a byte slice, then drop any
+  // trailing partial multibyte sequence by decoding with replacement and
+  // stripping the U+FFFD tail.
+  const sliced = Buffer.from(summary, 'utf8')
+    .subarray(0, budget)
+    .toString('utf8')
+    .replace(/�+$/u, '');
+  return { digest: sliced, relativePath, truncated: true };
+}
+
+/**
+ * Render the "Run trace" digest section appended to the `epic-handoff`
+ * comment. Returns `''` when `runTrace` is null / malformed so callers can
+ * splice the result in unconditionally — mirrors `renderPerfReportSection`.
+ *
+ * Output contract (Story #3669):
+ *   - `## Run trace` heading
+ *   - One relative link line to `temp/epic-<id>/lifecycle.md`
+ *   - The TraceLogger Summary rollup (phase durations + counts)
+ *   - A truncation note when the projection overflowed the byte budget
+ *
+ * @param {{ digest: string, relativePath: string, truncated?: boolean } | null | undefined} runTrace
+ * @returns {string}
+ */
+export function renderRunTraceSection(runTrace) {
+  if (
+    !runTrace ||
+    typeof runTrace.digest !== 'string' ||
+    runTrace.digest.length === 0 ||
+    typeof runTrace.relativePath !== 'string'
+  ) {
+    return '';
+  }
+  const lines = [];
+  lines.push('');
+  lines.push('## Run trace');
+  lines.push('');
+  lines.push(
+    `Full lifecycle companion: [\`${runTrace.relativePath}\`](${runTrace.relativePath}).`,
+  );
+  lines.push('');
+  lines.push(runTrace.digest);
+  if (runTrace.truncated) {
+    lines.push('');
+    lines.push(
+      `_Digest truncated to fit the comment budget — see [\`${runTrace.relativePath}\`](${runTrace.relativePath}) for the full trace._`,
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Default loader: read the canonical `temp/epic-<id>/lifecycle.ndjson`
+ * ledger from disk and project it into the run-trace digest envelope
+ * `renderRunTraceSection` expects. Returns `null` on any failure (missing
+ * file, malformed JSON, empty ledger) so the handoff comment degrades
+ * gracefully — mirrors `loadPerfReportFromDisk`.
+ *
+ * `relativePath` points at the rendered `lifecycle.md` companion (the same
+ * directory as the ledger), computed relative to `cwd` so consumers can
+ * follow the link from the rendered comment. Falls back to the absolute
+ * path when the companion resolves outside `cwd`.
+ *
+ * @param {{ epicId: number, config?: object, cwd?: string }} args
+ * @returns {Promise<{ digest: string, relativePath: string, truncated: boolean } | null>}
+ */
+export async function loadRunTraceFromDisk({
+  epicId,
+  config,
+  cwd = process.cwd(),
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId < 1) return null;
+  let ledgerAbsPath;
+  try {
+    ledgerAbsPath = epicLedgerPath(epicId, config);
+  } catch {
+    return null;
+  }
+  let ledgerText;
+  try {
+    ledgerText = await fs.readFile(ledgerAbsPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const companionAbsPath = path.join(
+    path.dirname(ledgerAbsPath),
+    'lifecycle.md',
+  );
+  let relativePath;
+  try {
+    const rel = path.relative(cwd, companionAbsPath);
+    relativePath =
+      rel && !rel.startsWith('..') && !path.isAbsolute(rel)
+        ? rel
+        : companionAbsPath;
+    relativePath = relativePath.split(path.sep).join('/');
+  } catch {
+    relativePath = companionAbsPath;
+  }
+  return extractRunTraceDigest({ ledgerText, epicId, relativePath });
+}
+
+/**
+ * Render the `epic-handoff` comment body. Pure helper — exported so the
+ * contract tests can assert the rendered shape without standing up a
+ * provider.
+ *
+ * @param {{ epicId: number, prNumber: number, prUrl?: string|null }} input
+ * @returns {string} markdown body (without the structured-comment marker
+ *   prefix — the marker is prepended by `upsertStructuredComment`).
+ */
+export function renderHandoffBody({
+  epicId,
+  prNumber,
+  prUrl = null,
+  perfReport = null,
+  runTrace = null,
+} = {}) {
+  const lines = [];
+  lines.push('### 🤝 Epic handoff — PR opened');
+  lines.push('');
+  lines.push(`Epic: #${epicId}`);
+  if (typeof prUrl === 'string' && prUrl.length > 0) {
+    lines.push(`Pull request: [#${prNumber}](${prUrl})`);
+  } else {
+    lines.push(`Pull request: #${prNumber}`);
+  }
+  lines.push('');
+  lines.push(
+    'Auto-merge will arm once the watch-and-iterate gate (Phase 8) confirms required checks are green.',
+  );
+  // Story #3029 / Task #3041 — Performance Report section. Empty string
+  // is returned when no perf report is available, so the existing body
+  // shape is preserved for handoffs that fire before the close tail has
+  // emitted a report (e.g. legacy replays).
+  const perfSection = renderPerfReportSection(perfReport);
+  if (perfSection.length > 0) {
+    lines.push(perfSection);
+  }
+  // Story #3669 — Run trace digest section. Empty string is returned when
+  // no ledger digest is available (missing/malformed ledger → section
+  // omitted), so the body shape is preserved for handoffs that fire before
+  // a ledger exists.
+  const runTraceSection = renderRunTraceSection(runTrace);
+  if (runTraceSection.length > 0) {
+    lines.push(runTraceSection);
+  }
+  lines.push('');
+  lines.push('```json');
+  lines.push(
+    JSON.stringify(
+      { kind: 'epic-handoff', epicId, prNumber, prUrl: prUrl ?? null },
+      null,
+      2,
+    ),
+  );
+  lines.push('```');
+  return lines.join('\n');
+}
+
+/**
+ * Default loader: read the canonical `epic-perf-report.json` snapshot
+ * from disk (when present) and shape it into the
+ * `{ relativePath, waveParallelism }` envelope `renderPerfReportSection`
+ * expects. Returns `null` on any failure (missing file, malformed JSON,
+ * unreadable directory) so the handoff comment degrades gracefully to
+ * the pre-Story-#3029 body shape rather than blocking the PR open.
+ *
+ * `relativePath` is computed relative to `cwd` so consumers cloning the
+ * repo can follow the link from the rendered comment. When the report
+ * path resolves outside `cwd`, falls back to the absolute path (rare —
+ * happens only for callers that point `tempRoot` outside the repo).
+ *
+ * @param {{ epicId: number, config?: object, cwd?: string }} args
+ * @returns {Promise<{ relativePath: string, waveParallelism: Array<object> } | null>}
+ */
+export async function loadPerfReportFromDisk({
+  epicId,
+  config,
+  cwd = process.cwd(),
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId < 1) return null;
+  let absPath;
+  try {
+    absPath = epicPerfReportJsonPath(epicId, config);
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = await fs.readFile(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== 'object') return null;
+  let relativePath;
+  try {
+    const rel = path.relative(cwd, absPath);
+    relativePath =
+      rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : absPath;
+    // Normalize Windows backslashes so the rendered Markdown link works
+    // on both POSIX consumers and Windows operators.
+    relativePath = relativePath.split(path.sep).join('/');
+  } catch {
+    relativePath = absPath;
+  }
+  return {
+    relativePath,
+    waveParallelism: Array.isArray(payload.waveParallelism)
+      ? payload.waveParallelism
+      : [],
+  };
+}
+
+/**
+ * Upsert the `epic-handoff` structured comment on the Epic ticket.
+ *
+ * @param {object} args
+ * @param {number} args.epicId
+ * @param {number} args.prNumber
+ * @param {string} [args.prUrl]
+ * @param {object} args.provider — ITicketingProvider used by
+ *   `upsertStructuredComment`.
+ * @param {Function} [args.upsertStructuredCommentFn] — override for
+ *   tests.
+ * @param {object} [args.logger]
+ * @returns {Promise<{ marker: string, commentId: number|null }>}
+ */
+export async function postHandoffComment({
+  epicId,
+  prNumber,
+  prUrl,
+  provider,
+  config,
+  cwd,
+  perfReport,
+  runTrace,
+  loadPerfReportFn = loadPerfReportFromDisk,
+  loadRunTraceFn = loadRunTraceFromDisk,
+  upsertStructuredCommentFn = defaultUpsertStructuredComment,
+  logger = Logger,
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new TypeError(
+      'postHandoffComment: epicId must be a positive integer',
+    );
+  }
+  if (!Number.isInteger(prNumber) || prNumber < 1) {
+    throw new TypeError(
+      'postHandoffComment: prNumber must be a positive integer',
+    );
+  }
+  if (!provider) {
+    throw new TypeError('postHandoffComment: provider is required');
+  }
+  // Story #3029 / Task #3041 — if an explicit `perfReport` envelope is
+  // not supplied, fall back to reading the persisted JSON written by
+  // the close-tail. Any loader failure resolves to `null` and the
+  // Performance Report section is silently omitted.
+  let resolvedPerfReport = perfReport;
+  if (resolvedPerfReport === undefined) {
+    try {
+      resolvedPerfReport = await loadPerfReportFn({ epicId, config, cwd });
+    } catch (err) {
+      logger.warn?.(
+        `[finalize/post-handoff-comment] perf-report load failed for Epic #${epicId} (non-fatal): ${err?.message ?? err}`,
+      );
+      resolvedPerfReport = null;
+    }
+  }
+  // Story #3669 — if an explicit `runTrace` envelope is not supplied, fall
+  // back to projecting the canonical lifecycle ledger from disk. Any loader
+  // failure resolves to `null` and the Run trace section is silently
+  // omitted, never blocking the handoff comment / PR open.
+  let resolvedRunTrace = runTrace;
+  if (resolvedRunTrace === undefined) {
+    try {
+      resolvedRunTrace = await loadRunTraceFn({ epicId, config, cwd });
+    } catch (err) {
+      logger.warn?.(
+        `[finalize/post-handoff-comment] run-trace load failed for Epic #${epicId} (non-fatal): ${err?.message ?? err}`,
+      );
+      resolvedRunTrace = null;
+    }
+  }
+  const body = renderHandoffBody({
+    epicId,
+    prNumber,
+    prUrl: prUrl ?? null,
+    perfReport: resolvedPerfReport,
+    runTrace: resolvedRunTrace,
+  });
+  try {
+    const result = await upsertStructuredCommentFn(
+      provider,
+      epicId,
+      EPIC_HANDOFF_MARKER,
+      body,
+    );
+    const commentId =
+      typeof result?.commentId === 'number' ? result.commentId : null;
+    return { marker: EPIC_HANDOFF_MARKER, commentId };
+  } catch (err) {
+    logger.warn?.(
+      `[finalize/post-handoff-comment] upsert failed for Epic #${epicId}: ${err?.message ?? err}`,
+    );
+    throw err;
+  }
+}

package/.agents/scripts/lib/orchestration/finalize/sanitize-skip-ci.js

@@ -0,0 +1,88 @@
+// .agents/scripts/lib/orchestration/finalize/sanitize-skip-ci.js
+/**
+ * sanitize-skip-ci.js — pure helper that strips GitHub Actions
+ * `[skip ci]` markers (and the four variant spellings GitHub honours)
+ * from a text payload.
+ *
+ * Story #3165: `/epic-deliver` Phase 7 opens a PR squashed into `main`
+ * via `gh pr merge --squash`. Story commits legitimately carry
+ * `[skip ci]` markers under `delivery.ci.skipForStoryPushes: true` to
+ * keep CI from firing on the wave's intermediate pushes. When GitHub
+ * composes the squash commit body by concatenating constituent commit
+ * messages, those markers propagate into the squash body and suppress
+ * `ci.yml` + `release-please.yml` on `main` — even though the squash
+ * subject is just `Epic #<id> (#<pr>)`.
+ *
+ * The first defence is to ensure the PR body (assembled by
+ * `openOrLocatePr` and handed to `gh pr create`) carries no raw
+ * skip-ci markers, so any tooling that derives the squash body from
+ * the PR body (or from text that flows through this helper) cannot
+ * re-introduce the suppression.
+ *
+ * Markers stripped (case-insensitive, optional inner spaces, optional
+ * brackets per GitHub's documented contract — only the bracketed
+ * forms actually suppress CI, so those are the only forms removed):
+ *
+ *   - `[skip ci]`     / `[ci skip]`
+ *   - `[no ci]`
+ *   - `[skip actions]` / `[actions skip]`
+ *
+ * Reference: GitHub Actions docs, "Skipping workflow runs":
+ *   https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs
+ */
+
+/**
+ * Canonical regex list. Frozen so callers can introspect (e.g. a
+ * contract test that asserts the documented marker set is what the
+ * sanitizer actually matches) without mutating the SSOT.
+ *
+ * Each pattern matches the bracketed form only — bare `skip ci`
+ * without brackets does NOT suppress CI on GitHub and is left
+ * untouched.
+ */
+export const SKIP_CI_PATTERNS = Object.freeze([
+  /\[\s*skip\s+ci\s*\]/gi,
+  /\[\s*ci\s+skip\s*\]/gi,
+  /\[\s*no\s+ci\s*\]/gi,
+  /\[\s*skip\s+actions\s*\]/gi,
+  /\[\s*actions\s+skip\s*\]/gi,
+]);
+
+/**
+ * Strip every GitHub-recognised `[skip ci]` variant from `text`.
+ *
+ * Non-string input (null / undefined / number) is returned unchanged
+ * so the helper can be folded into an optional-body assembly chain
+ * without forcing the caller to guard.
+ *
+ * Multiple consecutive matches collapse cleanly:
+ *   - Each matched marker is replaced with the empty string.
+ *   - Runs of whitespace that the deletion leaves behind on the same
+ *     line collapse to a single space.
+ *   - Trailing whitespace on each line is trimmed.
+ *   - Runs of three or more blank lines collapse to a single blank
+ *     line (so a body that was nothing but markers doesn't leave a
+ *     gaping vertical gap).
+ *
+ * The helper is intentionally idempotent: `sanitize(sanitize(x)) ===
+ * sanitize(x)` for every input.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanitizeSkipCiMarkers(text) {
+  if (typeof text !== 'string') return text;
+  let out = text;
+  for (const pattern of SKIP_CI_PATTERNS) {
+    out = out.replace(pattern, '');
+  }
+  // Collapse intra-line whitespace runs left behind by deletions, but
+  // preserve line boundaries so paragraph structure survives.
+  out = out
+    .split('\n')
+    .map((line) => line.replace(/[ \t]{2,}/g, ' ').replace(/[ \t]+$/g, ''))
+    .join('\n');
+  // Collapse runs of 3+ blank lines down to one blank line.
+  out = out.replace(/\n{3,}/g, '\n\n');
+  return out;
+}