mandrel 1.94.0 → 2.1.0

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

@@ -1,213 +0,0 @@
-/**
- * manifest-helpers.js
- *
- * Small pure helpers shared by the dispatch-manifest renderer
- * (`manifest-formatter.js`) and the per-wave renderer
- * (`manifest-render-waves.js`). Split out (Story #1849 Task #1871) so
- * the parent formatter can collapse to the wiring facade. The formatter
- * re-exports every name here so existing call-sites' import paths stay
- * unchanged.
- *
- * Post-2-tier (Story #3194 / #3413, Epic #3163): the helpers consume the
- * Story-only manifest shape. Stories carry their lifecycle state on a
- * top-level `status` field (the parent Story's `agent::*` label) — the
- * old per-Story Task array, the per-Task id indirection, and the
- * Task-tier summary pass-through have all been deleted. `computeProgress`
- * now reports Story-tier aggregates only.
- */
-
-import { AGENT_LABELS } from '../label-constants.js';
-
-/**
- * Pick the per-Story symbol for the wave-grouped Story table:
- *   🚧 — Story is `agent::blocked`
- *   ✅ — Story is `agent::done`
- *   🔄 — Story is `agent::executing` (in flight)
- *   ⬜ — Story is `agent::ready` or unset (planning-time default)
- *
- * Pure: derives the symbol from `story.status` only.
- *
- * @param {{ status?: string }} story
- * @returns {string}
- */
-export function deriveStorySymbol(story) {
-  const status = story?.status;
-  if (status === AGENT_LABELS.BLOCKED) return '🚧';
-  if (status === AGENT_LABELS.DONE) return '✅';
-  if (status === AGENT_LABELS.EXECUTING) return '🔄';
-  return '⬜';
-}
-
-/**
- * Compute aggregate progress numbers for a dispatch manifest. Pure.
- *
- * Story-only shape (Epic #3163, Story #3413): `doneStories` /
- * `totalStories` are derived from each Story's top-level `status` (the
- * parent Story's `agent::*` label), not from a nested Task array.
- * `storyPct` is the Story-tier completion percentage; the residual
- * Task-tier pass-through fields have been deleted.
- *
- * @param {object} manifest
- * @returns {{
- *   storyPct: number,
- *   doneStories: number,
- *   totalStories: number,
- *   storyWaveCount: number,
- * }}
- */
-export function computeProgress(manifest) {
-  const storyManifest = manifest?.storyManifest ?? [];
-
-  const allStoryItems = storyManifest.filter(
-    (s) => s.type === 'story' && s.storyId !== '__ungrouped__',
-  );
-  const totalStories = allStoryItems.length;
-  const doneStories = allStoryItems.filter(
-    (s) => s.status === AGENT_LABELS.DONE,
-  ).length;
-
-  const storyWaveSet = new Set(
-    storyManifest.map((s) => s.earliestWave).filter((w) => w !== -1),
-  );
-
-  return {
-    storyPct:
-      totalStories > 0 ? Math.round((doneStories / totalStories) * 100) : 0,
-    doneStories,
-    totalStories,
-    storyWaveCount: storyWaveSet.size || 1,
-  };
-}
-
-/**
- * Derive a GitHub-flavoured Markdown anchor slug from a heading's
- * visible text. GitHub's slug algorithm:
- *   1. Lowercase the text.
- *   2. Strip emojis and other non-letter/digit/space/hyphen Unicode.
- *   3. Replace runs of whitespace with a single hyphen.
- *   4. Trim leading/trailing hyphens.
- *
- * @param {string} text
- * @returns {string}
- */
-export function slugifyHeading(text) {
-  const raw = String(text ?? '');
-  const stripped = raw
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}\s-]+/gu, '')
-    .trim();
-  return stripped.replace(/[\s-]+/g, '-').replace(/^-+|-+$/g, '');
-}
-
-/**
- * Build the visible H2 text for a wave row, e.g. `🚀 Wave 0`. The
- * status word lives only in the Wave Summary TOC; the H2 carries the
- * emoji as a visual anchor.
- *
- * @param {string} waveLabel e.g. `Wave 0` or `Ungrouped`
- * @param {string} emoji     e.g. `🚀`, `⏳`, `✅`
- * @returns {string}
- */
-export function waveHeadingText(waveLabel, emoji) {
-  return `${emoji} ${waveLabel}`;
-}
-
-/**
- * Render a fixed-width unicode progress bar, e.g. `█████░░░░░░░░░░░░░░░`.
- *
- * @param {number} percent  0..100
- * @param {object} [opts]
- * @param {number} [opts.width=20]
- * @returns {string}
- */
-export function renderProgressBar(percent, opts = {}) {
-  const width = opts.width ?? 20;
-  const pct = Math.max(0, Math.min(100, Number(percent) || 0));
-  const filled = Math.round((pct / 100) * width);
-  return '█'.repeat(filled) + '░'.repeat(width - filled);
-}
-
-/**
- * Derive the per-wave status label and emoji used by both the TOC table
- * and the per-wave H2 heading.
- *
- * The waveStats map carries an opaque pair `{ total, done }` per wave —
- * the meaning of the unit is the caller's choice. Story-only callers
- * (`renderWaveSections` here) pass Story counts; Task-aware callers
- * (the wave renderer, pending Story #3196's rewrite) pass Task counts.
- * Either way, a wave is "done" when `done === total > 0`. "Ready"
- * requires every prior wave to be done; otherwise "Blocked".
- *
- * @param {number} waveIdx
- * @param {Map<number, { total: number, done: number }>} waveStats
- * @param {number[]} sortedWaves
- * @returns {{ emoji: string, word: string, label: string }}
- */
-export function deriveWaveStatus(waveIdx, waveStats, sortedWaves) {
-  const stat = waveStats.get(waveIdx);
-  const isDone = stat && stat.total > 0 && stat.done === stat.total;
-  if (isDone) return { emoji: '✅', word: 'Done', label: '✅ Done' };
-  const isReady =
-    waveIdx === 0 ||
-    sortedWaves
-      .filter((sw) => sw < waveIdx)
-      .every((sw) => {
-        const swStat = waveStats.get(sw);
-        return swStat.done === swStat.total;
-      });
-  return isReady
-    ? { emoji: '🚀', word: 'Ready', label: '🚀 Ready' }
-    : { emoji: '⏳', word: 'Blocked', label: '⏳ Blocked' };
-}
-
-/**
- * Render the "## Wave Summary" section for a manifest's wave-eligible
- * items (Stories only — Features are containers and excluded by caller).
- *
- * Story-only shape: per-wave totals count Stories (not Tasks). Each
- * row reports `doneStories/storyCount` so the TOC reflects Story-tier
- * progress directly.
- *
- * @param {object[]} waveEligible
- * @returns {string} Markdown block, or empty string when nothing to render.
- */
-export function renderWaveSections(waveEligible) {
-  if (!waveEligible || waveEligible.length === 0) return '';
-
-  const waveStats = new Map();
-  for (const s of waveEligible) {
-    const w = s.earliestWave ?? -1;
-    if (!waveStats.has(w)) {
-      // `total` / `done` is the contract `deriveWaveStatus` consumes;
-      // here each unit is a Story. Other callers (the wave renderer,
-      // pending Story #3196's rewrite) pass Task counts under the same
-      // key names so the predicate stays unit-agnostic.
-      waveStats.set(w, { total: 0, done: 0 });
-    }
-    const stat = waveStats.get(w);
-    stat.total++;
-    if (s.status === AGENT_LABELS.DONE) stat.done++;
-  }
-
-  const sortedWaves = [...waveStats.keys()].sort((a, b) => a - b);
-  const lines = [
-    '## Wave Summary',
-    '',
-    '| Wave | Status | Stories |',
-    '| :--- | :--- | :--- |',
-  ];
-
-  for (const w of sortedWaves) {
-    const stat = waveStats.get(w);
-    const waveLabel = w === -1 ? 'Ungrouped' : `Wave ${w}`;
-    const status = deriveWaveStatus(w, waveStats, sortedWaves);
-    const headingText = waveHeadingText(waveLabel, status.emoji);
-    const anchor = slugifyHeading(headingText);
-    const waveCell = `[${waveLabel}](#${anchor})`;
-    lines.push(
-      `| ${waveCell} | ${status.label} | ${stat.done}/${stat.total} |`,
-    );
-  }
-  lines.push('');
-  return lines.join('\n');
-}

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

@@ -1,261 +0,0 @@
-/**
- * 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.
- *
- * Internal crash-safe write primitive for the manifest artefact pair.
- */
-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

@@ -1,55 +0,0 @@
-/**
- * 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 `/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 \`/deliver ${epicId}\`. The runner iterates waves in order, fans Stories out in parallel via \`/deliver\`, and only pauses when the Epic flips to \`agent::blocked\`.`,
-  );
-  lines.push(
-    '2. **Resume (granular, optional)**: Re-running `/deliver` resumes from the checkpointed wave. To re-drive a single Story, run `/deliver <storyId>`. Re-runs are checkpoint-idempotent.',
-  );
-  lines.push(
-    `3. **Close**: \`/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');
-}