mandrel 1.94.0 → 2.1.0

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

@@ -1,111 +0,0 @@
-/**
- * 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.
- *
- * Story #4157 — each projected story's `wave` is a **render-time
- * dependency depth** derived from the manifest's `dependsOn` edges via the
- * shared `deriveStoryDepths` lens (`manifest-render-waves.js`, built on
- * `assignLayers`), not the persisted `earliestWave`. Scheduling no longer
- * stamps a wave field onto the run checkpoint (Epic #4151 / Story #4155),
- * so the rollup re-derives depth from the dependency graph at render time.
- */
-
-import { deriveStoryDepths } from './manifest-render-waves.js';
-
-/**
- * Pure: project a full dispatch manifest into the `{ stories }` shape
- * `renderManifest` accepts. Returns the canonical, non-ungrouped story
- * rows used by the Epic-level dispatch-manifest comment.
- *
- * The `wave` field is the render-time dependency depth (Story #4157):
- * `deriveStoryDepths` runs `assignLayers` over the entries' `dependsOn`
- * edges, so a Story with no in-set dependency is wave 0 and a dependent
- * sits one layer deeper than its deepest dependency. Entries the lens
- * cannot place (e.g. a non-integer storyId that survives the sentinel
- * filter) fall back to `-1`.
- *
- * @param {object} manifest
- * @returns {{ storyId: number|string, wave: number, title: string }[]}
- */
-export function projectStoriesFromManifest(manifest) {
-  const storyManifest = manifest?.storyManifest ?? [];
-  const depths = deriveStoryDepths(storyManifest);
-  return storyManifest
-    .filter((s) => s && s.storyId !== '__ungrouped__')
-    .map((s) => ({
-      storyId: s.storyId,
-      wave: depths.get(s.storyId) ?? -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 `/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

@@ -1,239 +0,0 @@
-/**
- * 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-story guard cascade live behind a single
- * private predicate (`validateSpecShape`) so the orchestrator function's
- * CRAP score drops below 12.
- *
- * Story #3413 (2-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 (`projectStories`) 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
- * "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:
- *   - `'stories'`  → the spec-level `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 '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` — Stories carry their own lifecycle state and are
- * leaves with no child 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 Story 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 2-tier hierarchy (Story #4041) Stories are direct Epic
- * children and leaves, so the rollup counts Stories directly:
- * `totalStories` is every projected Story and `doneStories` is the
- * subset carrying `agent::done`.
- *
- * @param {object[]} stories
- * @param {{ resolveId: Function, resolveStatus: Function }} resolvers
- * @returns {{
- *   storyManifest: object[],
- *   totalStories: number,
- *   doneStories: number,
- *   waveSet: Set<number>,
- * }}
- */
-function projectStories(stories, resolvers) {
-  const storyManifest = [];
-  let totalStories = 0;
-  let doneStories = 0;
-  const waveSet = new Set();
-  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 stories = validateSpecShape('stories', spec?.stories)
-    ? spec.stories
-    : [];
-
-  const { storyManifest, totalStories, doneStories, waveSet } = projectStories(
-    stories,
-    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 };

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

@@ -1,242 +0,0 @@
-/**
- * manifest-formatter.js
- *
- * Wiring facade for the dispatch-manifest presentation layer. Composes:
- *   - `manifest-builder.js`        — spec → manifest projection.
- *   - `manifest-helpers.js`        — small pure helpers (progress, slug,
- *                                    wave-status, topo sort, …).
- *   - `manifest-render-waves.js`   — per-wave H2 sections + Story H3 list.
- *   - `manifest-procedures.js`     — bottom `<details>` block.
- *   - `manifest-story-views.js`    — story-execution manifest + CLI table.
- *
- * Exposes `formatManifestMarkdown` (memoised on per-input content hash)
- * plus `fromManifest` / `fromSpec` entry points, and re-exports every
- * symbol the older monolithic formatter used to host so existing
- * imports off this path keep resolving without change.
- *
- * Pure: no fs / provider / config I/O. Callers that need injected values
- * (e.g. `renderStoryManifestMarkdown`'s script-path hints) pass them via
- * `opts`. The outer façade `manifest-renderer.js` re-exports this module
- * and owns the one impure helper that reads config to build the options
- * bag.
- */
-
-import { createHash } from 'node:crypto';
-import { buildManifestFromSpec } from './manifest-builder.js';
-import {
-  computeProgress,
-  deriveStorySymbol,
-  deriveWaveStatus,
-  renderProgressBar,
-  renderWaveSections,
-  slugifyHeading,
-  waveHeadingText,
-} from './manifest-helpers.js';
-import { renderProceduresAndLegendDetails } from './manifest-procedures.js';
-import {
-  renderConcurrencyHazards,
-  renderNestedWaveSections,
-} from './manifest-render-waves.js';
-import {
-  formatStoryManifestMarkdown,
-  printStoryDispatchTable,
-} from './manifest-story-views.js';
-
-// Re-export every name that used to live in this file so external
-// call-sites and tests keep importing them from here without a path
-// change (Story #1849 split).
-export {
-  buildManifestFromSpec,
-  computeProgress,
-  deriveStorySymbol,
-  deriveWaveStatus,
-  formatStoryManifestMarkdown,
-  printStoryDispatchTable,
-  renderConcurrencyHazards,
-  renderNestedWaveSections,
-  renderProceduresAndLegendDetails,
-  renderProgressBar,
-  renderWaveSections,
-  slugifyHeading,
-  waveHeadingText,
-};
-
-// ---------------------------------------------------------------------------
-// Dispatch manifest (Epic-level) Markdown — memoised public entry
-// ---------------------------------------------------------------------------
-
-let _lastManifestRef = null;
-let _lastManifestHash = null;
-let _lastManifestOutput = null;
-
-function hashManifest(manifest) {
-  return createHash('sha1')
-    .update(JSON.stringify(manifest ?? null))
-    .digest('hex');
-}
-
-/**
- * Clear the content-hash cache for `formatManifestMarkdown`. Intended
- * for tests and for callers that mutate manifest objects in place
- * between renders.
- */
-export function __resetManifestFormatterCache() {
-  _lastManifestRef = null;
-  _lastManifestHash = null;
-  _lastManifestOutput = null;
-}
-
-export function formatManifestMarkdown(manifest) {
-  // Fast path: same manifest instance as last call (progress-reporter
-  // reuses the same object across ticks when nothing has changed).
-  if (manifest === _lastManifestRef && _lastManifestOutput !== null) {
-    return _lastManifestOutput;
-  }
-  // Slow path: content-hash comparison for cases where the caller built
-  // a fresh manifest object with identical content.
-  const hash = hashManifest(manifest);
-  if (hash === _lastManifestHash && _lastManifestOutput !== null) {
-    _lastManifestRef = manifest;
-    return _lastManifestOutput;
-  }
-  const output = _formatManifestMarkdownUncached(manifest);
-  _lastManifestRef = manifest;
-  _lastManifestHash = hash;
-  _lastManifestOutput = output;
-  return output;
-}
-
-function _formatManifestMarkdownUncached(manifest) {
-  const lines = [
-    ...renderManifestHeader(manifest),
-    ...renderManifestBody(manifest),
-  ];
-  /* node:coverage ignore next */
-  if (manifest.agentTelemetry) {
-    lines.push(...renderManifestTelemetry(manifest.agentTelemetry));
-  }
-  return lines.join('\n');
-}
-
-/**
- * Private: emit the manifest header — title, subtitle, the single
- * `_Generated …_` meta line, and the operating-procedures `<details>`
- * block that sits directly under the meta. Pure.
- *
- * @param {object} manifest
- * @returns {string[]}
- */
-function renderManifestHeader(manifest) {
-  const { epicId, epicTitle, generatedAt } = manifest;
-  const progress = computeProgress(manifest);
-  const waveCount = progress.storyWaveCount;
-  return [
-    `# 📋 Dispatch Manifest — Epic #${epicId}`,
-    '',
-    `> **${epicTitle}**`,
-    '',
-    `_Generated ${generatedAt} · ${progress.doneStories}/${progress.totalStories} stories · ${waveCount} wave${waveCount === 1 ? '' : 's'}_`,
-    '',
-    renderProceduresAndLegendDetails(epicId),
-    '',
-  ];
-}
-
-/**
- * Private: emit the Wave Summary table plus the per-wave H2 sections.
- *
- * @param {object} manifest
- * @returns {string[]}
- */
-function renderManifestBody(manifest) {
-  const allItems =
-    manifest.storyManifest ||
-    manifest.stories ||
-    manifest.summary?.stories ||
-    [];
-  const waveEligible = allItems;
-  const lines = [];
-  const waveBlock = renderWaveSections(waveEligible);
-  if (waveBlock) lines.push(waveBlock);
-  const storyManifest = manifest.storyManifest;
-  if (storyManifest && storyManifest.length > 0) {
-    const nestedBlock = renderNestedWaveSections(storyManifest);
-    if (nestedBlock) lines.push(nestedBlock);
-  }
-  // Cross-Story concurrency hazards block — only emitted when the caller
-  // attaches `concurrencyFindings` to the manifest (i.e. `/plan`
-  // Phase 9 dispatcher dry-run forwards the validator's findings array).
-  // Absent for live progress-reporter manifests where the block would
-  // duplicate Story-level state already shown above.
-  if (manifest.concurrencyFindings !== undefined) {
-    const hazardsBlock = renderConcurrencyHazards(manifest.concurrencyFindings);
-    if (hazardsBlock) lines.push(hazardsBlock);
-  }
-  return lines;
-}
-
-/**
- * Private: emit the agent-telemetry trailer (friction count + recent
- * friction list) when the manifest carries one. Under the 2-tier
- * hierarchy (Epic #3163) friction records are Story-scoped, so each
- * recent-friction item is keyed by its `storyId`.
- *
- * @param {{ totalFriction: number, recentFriction: Array<{ message: string, storyId: number|string }> }} agentTelemetry
- * @returns {string[]}
- */
-/* node:coverage ignore next */
-function renderManifestTelemetry(agentTelemetry) {
-  const lines = [
-    '## 📈 Agent Telemetry & Diagnostics',
-    '',
-    `- **Total Friction Events:** ${agentTelemetry.totalFriction}`,
-  ];
-  if (agentTelemetry.recentFriction.length > 0) {
-    lines.push('- **Active Issues & Friction:**');
-    for (const item of agentTelemetry.recentFriction) {
-      const safeMessage = item.message
-        .replace(/\s+/g, ' ')
-        .replace(/\n/g, ' ')
-        .trim();
-      lines.push(`  - Story **#${item.storyId}**: ${safeMessage}`);
-    }
-  } else {
-    lines.push('- **Active Issues:** None recorded.');
-  }
-  lines.push('');
-  lines.push('---');
-  lines.push('');
-  return lines;
-}
-
-// Backward-compat alias (existing callers and tests import this name).
-export const renderManifestMarkdown = formatManifestMarkdown;
-
-// ---------------------------------------------------------------------------
-// Dual entry points: fromManifest / fromSpec (Epic #1182 Story #1501)
-// ---------------------------------------------------------------------------
-
-/**
- * Canonical alias for `formatManifestMarkdown`. Existing callers should
- * migrate to this name; the underlying function is unchanged.
- */
-export const fromManifest = formatManifestMarkdown;
-
-/**
- * Render a Markdown dispatch manifest from a structural spec. Funnels
- * through `formatManifestMarkdown` so the output is byte-identical to
- * `fromManifest` when given an equivalent manifest fixture (round-trip
- * parity AC for Story #1501).
- *
- * @param {object} spec — parsed epic-spec.
- * @param {Parameters<typeof buildManifestFromSpec>[1]} [opts]
- * @returns {string}
- */
-export function fromSpec(spec, opts = {}) {
-  const manifest = buildManifestFromSpec(spec, opts);
-  // Bust the cache so callers toggling fromSpec / fromManifest in the
-  // same process don't get a stale render from a content-hash collision
-  // on a different manifest instance.
-  __resetManifestFormatterCache();
-  return formatManifestMarkdown(manifest);
-}