mandrel 1.57.0

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

@@ -0,0 +1,188 @@
+/**
+ * manifest-renderer.js
+ *
+ * Facade that composes the presentation layer:
+ *   - `manifest-formatter.js`    — pure Markdown / CLI rendering.
+ *   - `manifest-persistence.js`  — write manifests to `temp/`.
+ *   - GitHub comment upserts     — `postManifestEpicComment` / `postParkedFollowOnsComment`.
+ *
+ * Keeps every export that external callers consume today so the split is
+ * internal: dispatcher.js and tests all continue to import from this path.
+ */
+
+import { resolveConfig } from '../config-resolver.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import {
+  classifyStoriesAgainstManifest,
+  renderParkedFollowOnsComment,
+} from '../orchestration/parked-follow-ons.js';
+import { upsertStructuredComment } from '../orchestration/ticketing.js';
+import { renderManifestFromManifest } from './dispatch-manifest-render.js';
+import {
+  buildManifestFromSpec,
+  formatManifestMarkdown,
+  formatStoryManifestMarkdown,
+  fromManifest,
+  fromSpec,
+  printStoryDispatchTable,
+  renderManifestMarkdown,
+} from './manifest-formatter.js';
+import { persistManifest } from './manifest-persistence.js';
+
+export {
+  buildManifestFromSpec,
+  formatManifestMarkdown,
+  fromManifest,
+  fromSpec,
+  persistManifest,
+  printStoryDispatchTable,
+  renderManifestMarkdown,
+};
+
+/**
+ * Backwards-compatible Markdown renderer for story-execution manifests.
+ * Resolves config internally to cite the canonical script paths. The pure
+ * variant lives at `manifest-formatter.js::formatStoryManifestMarkdown` — new
+ * call-sites should prefer that and inject the canonical `config` bag
+ * explicitly.
+ *
+ * @param {object} manifest
+ * @returns {string}
+ */
+export function renderStoryManifestMarkdown(manifest) {
+  const config = resolveConfig();
+  return formatStoryManifestMarkdown(manifest, { config });
+}
+
+/**
+ * Pure: a manifest qualifies for an Epic comment upsert when it exists, is
+ * not a story-execution dry-run, and carries an epicId.
+ *
+ * @param {unknown} manifest
+ */
+export function isEpicManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') return false;
+  return manifest.type !== 'story-execution' && Boolean(manifest.epicId);
+}
+
+/**
+ * Pure: a provider can upsert a comment when it is non-nullish and exposes a
+ * callable `postComment`.
+ *
+ * @param {unknown} provider
+ */
+export function providerCanPostComment(provider) {
+  return Boolean(provider) && typeof provider?.postComment === 'function';
+}
+
+/**
+ * Classify whether `(manifest, provider)` are eligible for an Epic comment
+ * upsert. Returns `null` when eligible, otherwise the skip-reason string.
+ *
+ * @param {unknown} manifest
+ * @param {unknown} provider
+ * @returns {null | 'not-an-epic-manifest' | 'no-provider'}
+ */
+export function classifyEpicCommentEligibility(manifest, provider) {
+  if (!isEpicManifest(manifest)) return 'not-an-epic-manifest';
+  if (!providerCanPostComment(provider)) return 'no-provider';
+  return null;
+}
+
+/**
+ * Persist the Epic's dispatch manifest as a structured comment on the Epic
+ * issue. Idempotent — replaces any existing `dispatch-manifest` comment.
+ * No-op in dry-run-only story manifests (no epicId).
+ *
+ * @param {object} manifest
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
+ * @returns {Promise<{ posted: boolean, reason?: string }>}
+ */
+export async function postManifestEpicComment(manifest, provider) {
+  const skipReason = classifyEpicCommentEligibility(manifest, provider);
+  if (skipReason) return { posted: false, reason: skipReason };
+
+  // Body rendering lives in the pure `dispatch-manifest-render.js`
+  // helper so the wave-runner's in-process refresh hop can produce a
+  // byte-identical body without spawning `dispatcher.js --dry-run`.
+  const body = renderManifestFromManifest(manifest);
+
+  try {
+    await upsertStructuredComment(
+      provider,
+      manifest.epicId,
+      'dispatch-manifest',
+      body,
+    );
+    return { posted: true };
+  } catch (err) {
+    process.stderr.write(
+      `[Dispatcher] Failed to persist dispatch-manifest comment to Epic #${manifest.epicId}: ${err.message}\n`,
+    );
+    return { posted: false, reason: err.message };
+  }
+}
+
+/**
+ * Classify Stories under the Epic against the frozen dispatch manifest and
+ * upsert a `parked-follow-ons` structured comment on the Epic. Idempotent.
+ *
+ * @param {object} manifest
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
+ * @returns {Promise<{ posted: boolean, recuts: number, parked: number, reason?: string }>}
+ */
+export async function postParkedFollowOnsComment(manifest, provider) {
+  const skipReason = classifyEpicCommentEligibility(manifest, provider);
+  if (skipReason) {
+    return { posted: false, recuts: 0, parked: 0, reason: skipReason };
+  }
+
+  const storyManifest = manifest.storyManifest ?? [];
+  const manifestStoryIds = storyManifest
+    .filter((s) => s.type !== 'feature' && s.storyId !== '__ungrouped__')
+    .map((s) => Number(s.storyId))
+    .filter((n) => Number.isFinite(n));
+
+  let storiesUnderEpic = [];
+  try {
+    const all = await provider.getTickets(manifest.epicId);
+    if (all) {
+      provider.primeTicketCache(all);
+    }
+    storiesUnderEpic = (all ?? []).filter((t) =>
+      (t.labels ?? []).includes(TYPE_LABELS.STORY),
+    );
+  } catch (err) {
+    return { posted: false, recuts: 0, parked: 0, reason: err.message };
+  }
+
+  const classification = classifyStoriesAgainstManifest(
+    manifestStoryIds,
+    storiesUnderEpic,
+  );
+  const body = renderParkedFollowOnsComment(manifest.epicId, classification);
+
+  try {
+    await upsertStructuredComment(
+      provider,
+      manifest.epicId,
+      'parked-follow-ons',
+      body,
+    );
+    return {
+      posted: true,
+      recuts: classification.recuts.length,
+      parked: classification.parked.length,
+    };
+  } catch (err) {
+    process.stderr.write(
+      `[Dispatcher] Failed to persist parked-follow-ons comment to Epic #${manifest.epicId}: ${err.message}\n`,
+    );
+    return {
+      posted: false,
+      recuts: classification.recuts.length,
+      parked: classification.parked.length,
+      reason: err.message,
+    };
+  }
+}

package/.agents/scripts/lib/presentation/manifest-story-views.js

@@ -0,0 +1,119 @@
+/**
+ * manifest-story-views.js
+ *
+ * Story-execution manifest renderer (`formatStoryManifestMarkdown`) plus
+ * the CLI dispatch-table printer (`printStoryDispatchTable`). 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.
+ */
+
+import { Logger } from '../Logger.js';
+
+/**
+ * Format the per-story execution manifest. Pure: caller must supply
+ * `opts.config` (the canonical resolved config bag) so we can cite the
+ * canonical `story-init.js` / `story-close.js` paths without touching
+ * `resolveConfig` (fs).
+ *
+ * Reads `config.project.paths.scriptsRoot` and `config.project.commands.*`
+ * from the post-reshape canonical blocks (Epic #1720). The fallback
+ * strings keep the formatter usable in tiny test fixtures that omit the
+ * paths / commands block.
+ *
+ * @param {object} manifest
+ * @param {{ config?: { project?: { paths?: { scriptsRoot?: string }, commands?: { validate?: string, test?: string } } } }} [opts]
+ * @returns {string}
+ */
+export function formatStoryManifestMarkdown(manifest, opts = {}) {
+  const project = opts.config?.project ?? {};
+  const scriptsRoot = project.paths?.scriptsRoot ?? '.agents/scripts';
+  const commands = project.commands ?? {};
+  const validateCmd = commands.validate ?? 'npm run lint';
+  const testCmd = commands.test ?? 'npm test';
+
+  const lines = [];
+  lines.push(`# 📚 Story Execution Manifest`);
+  lines.push('');
+  lines.push(`> **Generated:** ${manifest.generatedAt}`);
+  lines.push('');
+
+  for (const story of manifest.stories) {
+    lines.push(`## Story #${story.storyId}: ${story.storyTitle}`);
+    lines.push(`- **Epic Branch:** \`${story.epicBranch}\``);
+    lines.push(`- **Story Branch:** \`${story.branchName}\``);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push('## Execution Steps');
+  lines.push('');
+
+  const initPath = `${scriptsRoot}/story-init.js`;
+  const closePath = `${scriptsRoot}/story-close.js`;
+
+  lines.push(
+    `1. \`node ${initPath} --story <storyId>\` (bootstraps branch, transitions Story)`,
+  );
+  lines.push(
+    '2. Implement the Story body acceptance criteria and commit on the Story branch.',
+  );
+  lines.push(`3. Run \`${validateCmd}\` and \`${testCmd}\` to validate.`);
+  lines.push(
+    `4. \`node <main-repo>/${closePath} --story <storyId> --cwd <main-repo>\` (merges, cleans up, closes tickets)`,
+  );
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Print the CLI Story Dispatch Table. Writes to the supplied `logger.log`
+ * channel (defaults to `Logger.info`). Keeping the sink injectable makes
+ * the function testable without capturing stdout.
+ *
+ * @param {object[]} storyManifest
+ * @param {{ logger?: { log: (line: string) => void } }} [opts]
+ */
+/* node:coverage ignore next */
+export function printStoryDispatchTable(storyManifest, opts = {}) {
+  const log = opts.logger?.log ?? ((line) => Logger.info(line));
+  if (!storyManifest || storyManifest.length === 0) return;
+
+  // Split into wave-eligible Stories and Feature containers
+  const stories = storyManifest.filter((s) => s.type !== 'feature');
+  const features = storyManifest.filter((s) => s.type === 'feature');
+
+  log('\n┌─────────┬──────────────────────────────────────┬──────┐');
+  log('│                  📋 STORY DISPATCH TABLE                 │');
+  log('├─────────┼──────────────────────────────────────┼──────┤');
+  log('│ Story   │ Title                                │ Wave │');
+  log('├─────────┼──────────────────────────────────────┼──────┤');
+
+  for (const story of stories) {
+    const id =
+      story.storyId === '__ungrouped__' ? '(none)' : `#${story.storyId}`;
+    const title = (story.storySlug ?? '').substring(0, 36).padEnd(36);
+    const wave = (
+      story.earliestWave === -1 ? '-' : String(story.earliestWave)
+    ).padEnd(4);
+    log(`│ ${id.padEnd(7)} │ ${title} │ ${wave} │`);
+  }
+
+  log('└─────────┴──────────────────────────────────────┴──────┘');
+  log('');
+  log('  💡 Stories in the same [Wave] can be executed in parallel.');
+  log('  💡 Use /epic-deliver #[Story ID] to execute a Story.');
+
+  if (features.length > 0) {
+    log('');
+    log('  📦 Feature Containers (not directly executable):');
+    for (const f of features) {
+      log(`     #${f.storyId} — ${f.storySlug}`);
+    }
+  }
+  log('');
+}

package/.agents/scripts/lib/provider-factory.js

@@ -0,0 +1,80 @@
+/**
+ * Provider Factory — resolves the configured ticketing provider to a concrete class.
+ *
+ * Accepts the canonical resolved config object (the wrapper returned by
+ * `resolveConfig()` with `config.github` populated). The legacy
+ * `orchestration`-shaped argument is no longer supported as part of the
+ * Epic #2880 hard cutover; see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`.
+ *
+ * @see docs/v5-implementation-plan.md Sprint 1B
+ */
+
+import { GitHubProvider } from '../providers/github.js';
+
+/** @type {Record<string, typeof import('../lib/ITicketingProvider.js').ITicketingProvider>} */
+const PROVIDERS = {
+  github: GitHubProvider,
+};
+
+/**
+ * Create a ticketing provider instance from the canonical resolved config.
+ *
+ * The canonical contract is:
+ *   - `config.github` carries the GitHub provider config block
+ *     (`owner`, `repo`, `projectNumber`, `projectOwner`, `operatorHandle`,
+ *     and friends).
+ *   - Today GitHub is the only supported provider, so the provider name is
+ *     inferred from the presence of `config.github`. When additional
+ *     providers land, this resolver will gain a `config.provider` discriminator.
+ *
+ * @param {object|null} config - The resolved config wrapper (`resolveConfig()` output).
+ * @param {{ token?: string }} [opts] - Override options (e.g., test token).
+ * @returns {import('../lib/ITicketingProvider.js').ITicketingProvider}
+ * @throws {Error} If config is not provided or the provider block is missing.
+ */
+export function createProvider(config, opts = {}) {
+  if (!config) {
+    throw new Error(
+      '[ProviderFactory] config is not configured. ' +
+        'Pass the resolved config from resolveConfig() with a populated "github" block.',
+    );
+  }
+
+  const providerName = resolveProviderName(config);
+  if (!providerName) {
+    throw new Error(
+      '[ProviderFactory] provider is required. ' +
+        'Populate the canonical "github" block in .agentrc.json.',
+    );
+  }
+
+  const ProviderClass = PROVIDERS[providerName];
+  if (!ProviderClass) {
+    const supported = Object.keys(PROVIDERS).join(', ');
+    throw new Error(
+      `[ProviderFactory] Unsupported provider "${providerName}". ` +
+        `Supported: ${supported}.`,
+    );
+  }
+
+  const providerConfig = config[providerName];
+  if (!providerConfig) {
+    throw new Error(
+      `[ProviderFactory] ${providerName} config block is required ` +
+        `when provider is "${providerName}".`,
+    );
+  }
+
+  return new ProviderClass(providerConfig, opts);
+}
+
+/**
+ * Infer the provider name from the resolved config. Today the only
+ * supported value is `'github'`; a future provider would add a discriminator
+ * field on the top-level config and this helper would consult it.
+ */
+function resolveProviderName(config) {
+  if (typeof config.provider === 'string') return config.provider;
+  if (config.github) return 'github';
+  return null;
+}

package/.agents/scripts/lib/push-epic-retry.js

@@ -0,0 +1,209 @@
+/**
+ * push-epic-retry.js — Bounded retry for concurrent epic-branch pushes.
+ *
+ * story-close holds a per-Epic filesystem lock for the rebase / merge /
+ * push sequence, but that lock is local to one machine. N sprint sessions on
+ * different machines (or different Claude Code web workers) will not see each
+ * other's lock and can race on `origin/epic/<id>`. Whoever pushes second will
+ * be rejected with a non-fast-forward error.
+ *
+ * This module provides `pushEpicWithRetry`: first push attempt is a direct
+ * `git push` — single-session behaviour is byte-identical to pre-change code.
+ * Only on a non-fast-forward rejection do we enter the retry loop: fetch the
+ * advanced remote, reset local epic onto `origin/<epic>`, reapply the story
+ * merge, and retry the push. A real content conflict during re-apply is
+ * non-recoverable: we abort the merge (restoring a clean tree) and throw a
+ * `PushRetryConflictError` naming the conflicting files.
+ */
+
+import { DEFAULT_STORY_MERGE_RETRY } from './config/runners.js';
+
+/**
+ * Stderr patterns git emits when `git push` is rejected because the remote
+ * tip has advanced beyond our local branch head. Only these patterns trigger
+ * a retry; every other push error surfaces immediately so we do not mask
+ * permission denials, protected-branch rejections, or network errors behind
+ * a retry loop.
+ */
+const NON_FAST_FORWARD_PATTERNS = [
+  /non-fast-forward/i,
+  /fetch first/i,
+  /failed to push some refs/i,
+  /\[rejected\]/,
+  /Updates were rejected/i,
+];
+
+export function isNonFastForwardPush(stderr) {
+  if (!stderr) return false;
+  return NON_FAST_FORWARD_PATTERNS.some((p) => p.test(stderr));
+}
+
+/**
+ * Thrown when the retry loop's re-apply step (`git merge --no-ff story-<id>`
+ * onto the freshly-fetched epic tip) hits a real content conflict. The
+ * caller should surface this to the operator — we do not attempt automated
+ * resolution. The merge is aborted before throwing so the working tree is
+ * clean and recoverable.
+ */
+export class PushRetryConflictError extends Error {
+  constructor(conflictFiles, gitStderr) {
+    const fileList = conflictFiles.length
+      ? conflictFiles.join(', ')
+      : '(unknown)';
+    super(
+      `Content conflict while reapplying story merge onto origin/epic. ` +
+        `Conflicting file(s): ${fileList}. ` +
+        `The merge has been aborted and the working tree is clean — no ` +
+        `half-merged files remain. Resolve manually by rebasing the story ` +
+        `branch onto the updated epic, committing, and re-running ` +
+        `story-close.\n\n` +
+        `git stderr:\n${gitStderr}`,
+    );
+    this.name = 'PushRetryConflictError';
+    this.conflictFiles = conflictFiles;
+  }
+}
+
+/** Re-apply the story merge during a non-ff retry, optionally pinning the
+ * conventional-commit subject so the post-merge `(resolves #N)` grep keeps
+ * finding the merge commit (without it, git falls back to its default
+ * `Merge branch …` subject and the grep misses). */
+function runRetryMerge({ cwd, git, storyBranch, mergeMessage }) {
+  return mergeMessage
+    ? git.gitSpawn(cwd, 'merge', '--no-ff', '-m', mergeMessage, storyBranch)
+    : git.gitSpawn(cwd, 'merge', '--no-ff', '--no-edit', storyBranch);
+}
+
+/** Collect the list of files with unmerged paths after a failed merge. */
+function collectConflictFiles(cwd, git) {
+  const result = git.gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
+  if (result.status !== 0 || !result.stdout) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Push `epicBranch` with a bounded retry on non-fast-forward rejections.
+ *
+ * The first attempt is a direct push (no fetch, no reapply) so single-session
+ * runs behave identically to the pre-change path. Retries fetch the advanced
+ * remote, reset local `<epicBranch>` to `origin/<epicBranch>`, and reapply
+ * `<storyBranch>` via `merge --no-ff --no-edit`.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {string} opts.epicBranch
+ * @param {string} opts.storyBranch
+ * @param {{ maxAttempts?: number, backoffMs?: number[] }} [opts.storyMergeRetry]
+ * @param {{ gitSpawn: (cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string } }} opts.git
+ * @param {(ms: number) => Promise<void>} [opts.sleep]
+ * @param {(msg: string) => void} [opts.log]
+ * @returns {Promise<{ ok: boolean, attempts: number, reason?: string, result: object }>}
+ * @throws {PushRetryConflictError} On content conflict during re-apply.
+ */
+export async function pushEpicWithRetry({
+  cwd,
+  epicBranch,
+  storyBranch,
+  storyMergeRetry,
+  git,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  log = () => {},
+  mergeMessage = null,
+}) {
+  if (!cwd) throw new Error('pushEpicWithRetry: cwd is required');
+  if (!epicBranch) throw new Error('pushEpicWithRetry: epicBranch is required');
+  if (!storyBranch)
+    throw new Error('pushEpicWithRetry: storyBranch is required');
+  if (!git || typeof git.gitSpawn !== 'function') {
+    throw new Error('pushEpicWithRetry: git.gitSpawn injection is required');
+  }
+
+  const maxAttempts =
+    storyMergeRetry?.maxAttempts ?? DEFAULT_STORY_MERGE_RETRY.maxAttempts;
+  const backoffMs =
+    storyMergeRetry?.backoffMs ?? DEFAULT_STORY_MERGE_RETRY.backoffMs;
+
+  let lastResult;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    lastResult = git.gitSpawn(cwd, 'push', '--no-verify', 'origin', epicBranch);
+    if (lastResult.status === 0) {
+      return { ok: true, attempts: attempt, result: lastResult };
+    }
+
+    if (!isNonFastForwardPush(lastResult.stderr)) {
+      return {
+        ok: false,
+        attempts: attempt,
+        result: lastResult,
+        reason: 'non-retryable-push-error',
+      };
+    }
+
+    if (attempt === maxAttempts) {
+      return {
+        ok: false,
+        attempts: attempt,
+        result: lastResult,
+        reason: 'retry-exhausted',
+      };
+    }
+
+    const backoff = backoffMs[Math.min(attempt - 1, backoffMs.length - 1)] ?? 0;
+    log(
+      `[push-epic-retry] Push rejected (non-fast-forward) on attempt ` +
+        `${attempt}/${maxAttempts}; fetching remote and reapplying after ` +
+        `${backoff}ms backoff.`,
+    );
+    await sleep(backoff);
+
+    const fetchResult = git.gitSpawn(cwd, 'fetch', 'origin', epicBranch);
+    if (fetchResult.status !== 0) {
+      return {
+        ok: false,
+        attempts: attempt,
+        result: fetchResult,
+        reason: 'fetch-failed',
+      };
+    }
+
+    const resetResult = git.gitSpawn(
+      cwd,
+      'reset',
+      '--hard',
+      `origin/${epicBranch}`,
+    );
+    if (resetResult.status !== 0) {
+      return {
+        ok: false,
+        attempts: attempt,
+        result: resetResult,
+        reason: 'reset-failed',
+      };
+    }
+
+    const mergeResult = runRetryMerge({
+      cwd,
+      git,
+      storyBranch,
+      mergeMessage,
+    });
+    if (mergeResult.status !== 0) {
+      const conflicts = collectConflictFiles(cwd, git);
+      git.gitSpawn(cwd, 'merge', '--abort');
+      throw new PushRetryConflictError(
+        conflicts,
+        mergeResult.stderr || mergeResult.stdout || '',
+      );
+    }
+  }
+
+  return {
+    ok: false,
+    attempts: maxAttempts,
+    result: lastResult,
+    reason: 'retry-exhausted',
+  };
+}