mandrel 1.57.0

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

@@ -0,0 +1,262 @@
+/**
+ * manifest-persistence.js
+ *
+ * File I/O for dispatch / story manifests. All fs writes land under the
+ * per-Epic tree (`temp/epic-<id>/manifest.{md,json}` for Epic dispatch
+ * manifests; `temp/epic-<id>/stories/story-<sid>/manifest.{md,json}` for Story
+ * execution manifests — see Epic #1030 Story #1040 / Task #1053). The
+ * formatter is injected so this module is testable against a tmpdir
+ * without touching the real filesystem layout.
+ *
+ * Story manifests with multiple stories that span Epic IDs (rare —
+ * happens only when the dispatcher is run against a hand-rolled cohort)
+ * fall back to the first story's epicId. Manifests with no resolvable
+ * epicId resolve to the legacy flat layout (`temp/story-manifest-*`)
+ * which is still understood by downstream cleanup paths.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  epicArtifactPath,
+  storyArtifactPath,
+  tempRootFrom,
+} from '../config/temp-paths.js';
+import { resolveConfig } from '../config-resolver.js';
+import {
+  formatManifestMarkdown,
+  formatStoryManifestMarkdown,
+} from './manifest-formatter.js';
+
+function getProjectRoot() {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(__dirname, '../../../..');
+}
+
+/**
+ * Build a config bag whose `tempRoot` is an ABSOLUTE path anchored to the
+ * caller-supplied `projectRoot` (Story #3900).
+ *
+ * The on-disk dispatch / story manifests are a per-Epic *operator view*
+ * bound to a specific project root the caller already knows — not a
+ * lifecycle ledger that must be cwd-independent. The `temp-paths` helpers
+ * now anchor a *relative* `tempRoot` to the main checkout (the git common
+ * dir's parent), which is correct for the ledger but wrong here: it would
+ * ignore the explicit `projectRoot` (e.g. a test tmpdir, or a sandboxed
+ * dispatcher root). Pre-absolutising the `tempRoot` against `projectRoot`
+ * makes the helpers honour it verbatim (absolute roots skip git anchoring),
+ * so manifest writes always land under the project root the caller named.
+ *
+ * @param {string} projectRoot
+ * @param {object|undefined} resolved Resolved config (or undefined).
+ * @returns {object} A config bag with an absolute `project.paths.tempRoot`.
+ */
+function absoluteTempRootConfig(projectRoot, resolved) {
+  const tempRoot = tempRootFrom(resolved);
+  const absoluteTempRoot = path.isAbsolute(tempRoot)
+    ? tempRoot
+    : path.join(projectRoot, tempRoot);
+  return { project: { paths: { tempRoot: absoluteTempRoot } } };
+}
+
+/**
+ * Resolve absolute path for a legacy flat dispatch-manifest sibling.
+ */
+function legacyOrphanPath(epicId, ext, projectRoot, resolved) {
+  const rel = epicArtifactPath(
+    epicId,
+    `dispatch-manifest-${epicId}.${ext}`,
+    resolved,
+  );
+  return path.isAbsolute(rel) ? rel : path.join(projectRoot, rel);
+}
+
+/**
+ * Sweep one legacy orphan; returns the path if removed, else null.
+ */
+function sweepOne(target) {
+  try {
+    if (!fs.existsSync(target)) return null;
+    fs.rmSync(target, { force: true });
+    return target;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sweep legacy flat-layout dispatch-manifest siblings out of the per-Epic
+ * temp dir. The Epic manifest layout migrated from
+ * `temp/epic-<id>/dispatch-manifest-<id>.{md,json}` to
+ * `temp/epic-<id>/manifest.{md,json}` in Epic #1030 / Story #1040;
+ * sweeping on each render keeps a single canonical artefact in the
+ * epic dir. Idempotent: returns `{ removed: [] }` when nothing to do.
+ *
+ * @param {number} epicId
+ * @param {{ projectRoot?: string, config?: object, logger?: { info?: Function } }} [opts]
+ */
+export function deleteLegacyFlatManifest(epicId, opts = {}) {
+  const projectRoot = opts.projectRoot ?? getProjectRoot();
+  const resolved = opts.config ?? safeResolveConfig(projectRoot);
+  const logger = opts.logger ?? console;
+  const tempPathsConfig = absoluteTempRootConfig(projectRoot, resolved);
+
+  const targets = ['md', 'json'].map((ext) =>
+    legacyOrphanPath(epicId, ext, projectRoot, tempPathsConfig),
+  );
+  const removed = targets.map(sweepOne).filter(Boolean);
+
+  if (removed.length > 0 && typeof logger?.info === 'function') {
+    logger.info(
+      `[manifest-persistence] Swept ${removed.length} legacy flat dispatch-manifest orphan(s) for Epic #${epicId}: ${removed.join(', ')}`,
+    );
+  }
+
+  return { removed };
+}
+
+/**
+ * Atomic write-then-rename. On any failure, best-effort remove the `.tmp`
+ * file and rethrow so the caller can surface a structured result.
+ *
+ * Exported so other writers (e.g. `render-manifest.js`) can route their
+ * `.md` / `.json` artefact writes through the same crash-safe primitive.
+ */
+export function atomicWrite(finalPath, content) {
+  const tmpPath = `${finalPath}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, finalPath);
+  } catch (err) {
+    try {
+      fs.rmSync(tmpPath, { force: true });
+    } catch {
+      // best-effort; original error is what the caller needs
+    }
+    throw err;
+  }
+}
+
+/**
+ * Persist a manifest to `temp/`. Story-execution manifests write a
+ * `story-manifest-<key>.{json,md}` pair keyed on story IDs; Epic manifests
+ * write a `dispatch-manifest-<epicId>.{json,md}` pair. Each file is written
+ * via an atomic write-then-rename sequence. On failure the caller receives
+ * the error string and the `.tmp` residue is removed — the final path is
+ * left untouched.
+ *
+ * When `opts.markdown` is provided (a pre-rendered Markdown string), it is
+ * used in place of `formatManifestMarkdown(manifest)`. This is the
+ * injection seam the dispatcher uses to route through `fromSpec` when a
+ * spec file is present alongside the Epic (Story #1501) without
+ * coupling persistence to the spec loader.
+ *
+ * Config resolution: the caller may pass the canonical resolved config
+ * via `opts.config` (story-init does this to avoid a redundant resolve);
+ * otherwise the helper lazy-resolves so `epicArtifactPath` /
+ * `storyArtifactPath` honour any `project.paths.tempRoot` override.
+ *
+ * @param {object} manifest
+ * @param {{ projectRoot?: string, config?: object, markdown?: string }} [opts]
+ * @returns {{ persisted: boolean, path: string|null, error: string|null }}
+ */
+export function persistManifest(manifest, opts = {}) {
+  const projectRoot = opts.projectRoot ?? getProjectRoot();
+  const resolved = opts.config ?? safeResolveConfig(projectRoot);
+  // Anchor manifest artifact paths to the explicit projectRoot (Story #3900)
+  // rather than letting temp-paths anchor a relative tempRoot to the main
+  // checkout — these manifests are a per-project operator view.
+  const tempPathsConfig = absoluteTempRootConfig(projectRoot, resolved);
+
+  let jsonPath = null;
+  let mdPath = null;
+
+  if (manifest.type === 'story-execution') {
+    // Story manifests live under `temp/epic-<eid>/stories/story-<sid>/`. When the
+    // manifest carries multiple stories, fall back to the first entry's
+    // epicId for the directory key (the dispatcher only ever bundles
+    // stories that share an Epic; the multi-Epic case is a hand-rolled
+    // cohort we tolerate but don't optimise for). Stories with no
+    // resolvable epicId fall through to the legacy flat layout so
+    // downstream cleanup paths keep finding them.
+    const stories = manifest.stories ?? [];
+    const epicId = stories.find((s) => s?.epicId)?.epicId;
+    const key = stories.map((s) => s.storyId).join('-');
+    if (epicId && stories.length === 1 && stories[0]?.storyId) {
+      const sid = stories[0].storyId;
+      const rel = storyArtifactPath(
+        epicId,
+        sid,
+        'manifest.json',
+        tempPathsConfig,
+      );
+      const relMd = storyArtifactPath(
+        epicId,
+        sid,
+        'manifest.md',
+        tempPathsConfig,
+      );
+      jsonPath = path.isAbsolute(rel) ? rel : path.join(projectRoot, rel);
+      mdPath = path.isAbsolute(relMd) ? relMd : path.join(projectRoot, relMd);
+    } else {
+      // Legacy flat layout — preserved as a safety net for multi-story
+      // manifests where the per-story dirs would collide.
+      const legacyDir = path.join(projectRoot, 'temp');
+      jsonPath = path.join(legacyDir, `story-manifest-${key}.json`);
+      mdPath = path.join(legacyDir, `story-manifest-${key}.md`);
+    }
+  } else if (manifest.epicId) {
+    const epicId = manifest.epicId;
+    // Sweep legacy flat dispatch-manifest-<id>.{md,json} orphans before
+    // re-rendering so the per-Epic dir only ever shows the canonical
+    // manifest.{md,json} pair (resolves #1126).
+    deleteLegacyFlatManifest(epicId, {
+      projectRoot,
+      config: resolved,
+    });
+    const relJson = epicArtifactPath(epicId, 'manifest.json', tempPathsConfig);
+    const relMd = epicArtifactPath(epicId, 'manifest.md', tempPathsConfig);
+    jsonPath = path.isAbsolute(relJson)
+      ? relJson
+      : path.join(projectRoot, relJson);
+    mdPath = path.isAbsolute(relMd) ? relMd : path.join(projectRoot, relMd);
+  } else {
+    return { persisted: false, path: null, error: null };
+  }
+
+  try {
+    const jsonContent = JSON.stringify(manifest, null, 2);
+    const mdContent =
+      typeof opts.markdown === 'string'
+        ? opts.markdown
+        : manifest.type === 'story-execution'
+          ? formatStoryManifestMarkdown(manifest, { config: resolved })
+          : formatManifestMarkdown(manifest);
+
+    // Ensure both parent directories exist (`temp/epic-<id>/` and
+    // optionally the per-Story sub-tree). `recursive: true` is a no-op
+    // when the dir already exists.
+    fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+    fs.mkdirSync(path.dirname(mdPath), { recursive: true });
+    atomicWrite(jsonPath, jsonContent);
+    atomicWrite(mdPath, mdContent);
+    return { persisted: true, path: jsonPath, error: null };
+  } catch (err) {
+    return { persisted: false, path: jsonPath, error: err.message };
+  }
+}
+
+/**
+ * `resolveConfig` throws when no `.agentrc.json` is loadable from `cwd`
+ * (zero-config callers — unit tests). Persistence treats that as a
+ * benign condition: the helpers fall back to the framework default
+ * (`tempRoot=temp`) when the config bag is absent.
+ */
+function safeResolveConfig(projectRoot) {
+  try {
+    return resolveConfig({ cwd: projectRoot });
+  } catch {
+    return undefined;
+  }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * manifest-procedures.js
+ *
+ * Renders the bottom collapsed `<details>` block that carries the agent
+ * operating procedures and the full symbol legend for a dispatch
+ * manifest. Split out of `manifest-formatter.js` (Story #1849 Task #1871)
+ * so the parent collapses to the dispatch-manifest wiring facade.
+ *
+ * Re-exported from `manifest-formatter.js` so existing call-sites and
+ * tests that import from there keep working without a path change.
+ */
+
+/**
+ * Render the bottom collapsed `<details>` block carrying the operating
+ * procedures and the full symbol legend (Story #1194 Task #1214). This is
+ * the only HTML the manifest emits by AC — every other section is plain
+ * Markdown.
+ *
+ * @param {number|string} epicId  the Epic id used to substitute `/epic-deliver` examples.
+ * @returns {string}
+ */
+export function renderProceduresAndLegendDetails(epicId) {
+  const lines = [];
+  lines.push(
+    '<details><summary>🤖 Agent Operating Procedures &amp; symbol reference</summary>',
+  );
+  lines.push('');
+  lines.push('### Operating Procedures');
+  lines.push('');
+  lines.push(
+    `1. **Deliver**: Run \`/epic-deliver ${epicId}\`. The runner iterates waves in order, fans Stories out in parallel via \`/story-deliver\`, and only pauses when the Epic flips to \`agent::blocked\`.`,
+  );
+  lines.push(
+    '2. **Resume (granular, optional)**: Re-running `/epic-deliver` resumes from the checkpointed wave. To re-drive a single Story, run `/story-deliver <storyId>`. Re-runs are checkpoint-idempotent.',
+  );
+  lines.push(
+    `3. **Close**: \`/epic-deliver ${epicId}\` runs close-validation, code-review, retro, and PR-create in its tail. Operators merge the PR via the GitHub UI.`,
+  );
+  lines.push('');
+  lines.push('### Symbol legend');
+  lines.push('');
+  lines.push('| Symbol | Meaning |');
+  lines.push('| :--- | :--- |');
+  lines.push('| ⬜ | Pending — no Tasks started |');
+  lines.push('| 🔄 | In-flight — at least one Task done or executing |');
+  lines.push('| ✅ | Done — every Task complete |');
+  lines.push('| 🚧 | Blocked — at least one Task is `agent::blocked` |');
+  lines.push('| 🚀 Ready | Wave is unblocked and ready to dispatch |');
+  lines.push('| ⏳ Blocked | Wave is gated on a prior wave still completing |');
+  lines.push('| `█` / `░` | Progress bar: filled / remaining cells |');
+  lines.push('| `*(after #N)*` | Task callout: depends on in-Story Task #N |');
+  lines.push('');
+  lines.push('</details>');
+  return lines.join('\n');
+}

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

@@ -0,0 +1,252 @@
+/**
+ * manifest-render-waves.js
+ *
+ * Presentation-only: emits the per-wave `## <emoji> Wave N` H2 sections
+ * (with nested per-Story H3 headings) that sit beneath the Wave Summary
+ * table in the dispatch manifest. Under the 3-tier hierarchy (Epic
+ * #3163) Stories are leaves with no child Task tickets, so each wave
+ * counts Stories (done/total) and renders one H3 per Story. The TOC
+ * links emitted by `renderWaveSections` jump directly into the H2
+ * anchors emitted here.
+ *
+ * Extracted from `manifest-formatter.js` (Story #1849 Task #1870). The
+ * shape-guard cascade lives behind a single private `validateWaveSection`
+ * predicate so `renderNestedWaveSections` reads as a straight projection
+ * and lands below CRAP 12.
+ *
+ * Imports the small pure helpers from `manifest-helpers.js` — the
+ * formatter re-exports them so existing call-sites that read these
+ * names off `manifest-formatter.js` keep working.
+ */
+
+import { AGENT_LABELS } from '../label-constants.js';
+import {
+  deriveStorySymbol,
+  deriveWaveStatus,
+  waveHeadingText,
+} from './manifest-helpers.js';
+
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+
+/**
+ * Private: shape-guard for the per-level nodes touched by the wave
+ * renderer. Centralising the checks keeps `renderNestedWaveSections`
+ * linear — the function reads as a straight projection from `storyManifest`
+ * into Markdown without re-asserting Array-ness at each loop.
+ *
+ * `level` describes which input the renderer is about to walk:
+ *   - `'storyManifest'` → top-level `storyManifest[]` array
+ *   - `'story'`         → a single Story manifest entry (object)
+ *
+ * Returns `true` when the node satisfies the contract; the caller skips
+ * or substitutes an empty list when `false`.
+ *
+ * @param {string} level
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function validateWaveSection(level, value) {
+  switch (level) {
+    case 'storyManifest':
+      return Array.isArray(value);
+    case 'story':
+      return value !== null && typeof value === 'object';
+    default:
+      return false;
+  }
+}
+
+/**
+ * Pick the inline tail rendered after the per-wave count blockquote.
+ * Pure derivation — only adds context the table doesn't already carry:
+ * the gating wave when this one is Blocked, or the parallel-fan-out
+ * count when multiple Stories run in parallel in a Ready wave.
+ *
+ * @param {{ word: string }} status
+ * @param {number} waveIdx
+ * @param {number[]} sortedWaves
+ * @param {number} storyCount
+ * @returns {string}
+ */
+function pickWaveTail(status, waveIdx, sortedWaves, storyCount) {
+  if (status.word === 'Blocked') {
+    const priorWaves = sortedWaves.filter((sw) => sw < waveIdx);
+    const lastPrior = priorWaves[priorWaves.length - 1];
+    if (lastPrior !== undefined) return ` · gated on Wave ${lastPrior}`;
+    return '';
+  }
+  if (status.word === 'Ready' && storyCount > 1) {
+    return ` · ${storyCount} run in parallel`;
+  }
+  return '';
+}
+
+/**
+ * Group Stories into per-wave buckets and accumulate per-wave Story
+ * totals. Pure helper — keeps the bookkeeping outside the main render
+ * loop. Under the 3-tier hierarchy (Epic #3163) Stories are leaves with
+ * no child Task tickets, so each wave's `total` / `done` counts Stories
+ * (a Story is "done" when it carries `agent::done`) — the unit
+ * `deriveWaveStatus` consumes.
+ *
+ * @param {object[]} waveStories
+ * @returns {{ waveGroups: Map<number, object[]>, waveStats: Map<number, { total: number, done: number }> }}
+ */
+function groupStoriesByWave(waveStories) {
+  const waveGroups = new Map();
+  const waveStats = new Map();
+  for (const story of waveStories) {
+    const w = story.earliestWave ?? -1;
+    if (!waveGroups.has(w)) {
+      waveGroups.set(w, []);
+      waveStats.set(w, { total: 0, done: 0 });
+    }
+    waveGroups.get(w).push(story);
+    const stat = waveStats.get(w);
+    stat.total++;
+    if (story.status === AGENT_LABELS.DONE) stat.done++;
+  }
+  return { waveGroups, waveStats };
+}
+
+/**
+ * Render one `## <emoji> Wave N` section per wave with nested per-Story H3
+ * headings. The TOC links from `renderWaveSections` jump straight into
+ * these H2 anchors.
+ *
+ * @param {object[]} storyManifest
+ * @returns {string} Markdown block, or empty string when nothing to render.
+ */
+export function renderNestedWaveSections(storyManifest) {
+  if (!validateWaveSection('storyManifest', storyManifest)) return '';
+  if (storyManifest.length === 0) return '';
+
+  const waveStories = storyManifest.filter(
+    (s) => validateWaveSection('story', s) && s.type !== 'feature',
+  );
+  const featureItems = storyManifest.filter(
+    (s) => validateWaveSection('story', s) && s.type === 'feature',
+  );
+
+  const { waveGroups, waveStats } = groupStoriesByWave(waveStories);
+  const sortedWaves = [...waveGroups.keys()].sort((a, b) => a - b);
+  const lines = [];
+
+  for (const waveIdx of sortedWaves) {
+    const stories = waveGroups.get(waveIdx);
+    const stat = waveStats.get(waveIdx);
+    const waveLabel = waveIdx === -1 ? 'Ungrouped' : `Wave ${waveIdx}`;
+    const status = deriveWaveStatus(waveIdx, waveStats, sortedWaves);
+
+    // The H2 text and slug must match `renderWaveSections` exactly so the
+    // TOC links land on the right anchor.
+    lines.push(`## ${waveHeadingText(waveLabel, status.emoji)}`);
+    lines.push('');
+
+    const tail = pickWaveTail(status, waveIdx, sortedWaves, stories.length);
+    lines.push(
+      `> ${stories.length} stor${stories.length === 1 ? 'y' : 'ies'} · ${stat.done}/${stat.total} done${tail}`,
+    );
+    lines.push('');
+
+    for (const story of stories) {
+      const symbol = deriveStorySymbol(story);
+      const titleCandidate = story.storyTitle || story.storySlug || '';
+      lines.push(`### ${symbol} #${story.storyId} — ${titleCandidate}`);
+      lines.push('');
+    }
+  }
+
+  if (featureItems.length > 0) {
+    lines.push('## Feature Containers');
+    lines.push('');
+    lines.push(
+      '> Features are organizational groupings and are **not directly executable**.',
+    );
+    lines.push('> Execute the Stories within each Feature instead.');
+    lines.push('');
+    lines.push('| Feature | Title |');
+    lines.push('| :--- | :--- |');
+    for (const f of featureItems) {
+      lines.push(`| #${f.storyId} | ${f.storySlug} |`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render the "Concurrency hazards" block that sits at the foot of the
+ * dispatch manifest. Consumes the structured findings array emitted by
+ * `computeConflictFindings` (Story #2296):
+ *
+ *   - `shared-editor` findings — one bullet per path with the conflicting
+ *     Story identifiers and a `depends_on` remediation hint.
+ *   - `implicit-cross-story-dep` findings — one bullet per missing dep
+ *     with the producer/consumer pair and a `depends_on` remediation hint.
+ *
+ * When `findings` is empty the renderer emits a single-line confirmation
+ * (`✓ No concurrency hazards detected.`) so absence is explicit in the
+ * dry-run log rather than silently dropped.
+ *
+ * Story identifiers are rendered verbatim — the validator carries planning
+ * slugs (e.g. `s-foo`) while persisted findings carry GitHub issue numbers
+ * (e.g. `201`). The renderer is agnostic; whichever identifier the caller
+ * passes is what shows up.
+ *
+ * @param {object[]} findings
+ * @returns {string} Markdown block, or empty string when `findings` is
+ *                   neither an array nor undefined (defensive no-op).
+ */
+export function renderConcurrencyHazards(findings) {
+  if (findings === undefined || findings === null) return '';
+  if (!Array.isArray(findings)) return '';
+  const lines = ['## ⚠️ Concurrency Hazards', ''];
+  if (findings.length === 0) {
+    lines.push('✓ No concurrency hazards detected.');
+    lines.push('');
+    return lines.join('\n');
+  }
+  const sharedEditors = findings.filter((f) => f?.kind === 'shared-editor');
+  const implicit = findings.filter(
+    (f) => f?.kind === 'implicit-cross-story-dep',
+  );
+  for (const f of sharedEditors.sort((a, b) =>
+    (a.path ?? '').localeCompare(b.path ?? ''),
+  )) {
+    lines.push(...renderSharedEditorBullet(f));
+  }
+  for (const f of implicit.sort((a, b) =>
+    (a.path ?? '').localeCompare(b.path ?? ''),
+  )) {
+    lines.push(...renderImplicitDepBullet(f));
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderSharedEditorBullet(finding) {
+  const stories = Array.isArray(finding.storySlugs) ? finding.storySlugs : [];
+  const storyList = stories.map((s) => `\`${s}\``).join(', ');
+  const sev = finding.severity === 'hard' ? ' **(blocking)**' : '';
+  return [
+    `- **\`${finding.path}\`** — written by ${stories.length} concurrent Stories: ${storyList}${sev}`,
+    '  - Recommend serializing via `depends_on` chains or a dedicated late-wave "wiring" Story.',
+  ];
+}
+
+function renderImplicitDepBullet(finding) {
+  const producer = finding.producer ?? {};
+  const consumer = finding.consumer ?? {};
+  const sev = finding.severity === 'hard' ? ' **(blocking)**' : '';
+  return [
+    `- **\`${finding.path}\`** — produced by Story \`${producer.storySlug ?? '?'}\` (Task \`${producer.taskSlug ?? '?'}\`), consumed by Story \`${consumer.storySlug ?? '?'}\` (Task \`${consumer.taskSlug ?? '?'}\`, \`body.${consumer.sourceField ?? '?'}\`)${sev}`,
+    `  - Recommend: add \`depends_on: ["${producer.storySlug ?? '?'}"]\` to the consumer Story.`,
+  ];
+}
+
+// Test-only: surface the private predicate so the sibling unit test can
+// exercise each branch without going through the full renderer.
+export const __testables = { validateWaveSection };