mandrel 1.57.0

package/.agents/scripts/lib/orchestration/detectors-phase.js

@@ -0,0 +1,188 @@
+/**
+ * detectors-phase.js — pure post-merge phase that runs the per-Story
+ * signal detectors (rework + retry) before `analyze-execution.js` shells
+ * out to render the `<!-- structured:story-perf-summary -->` comment.
+ *
+ * Extracted from `post-merge-pipeline.js` (Story #1770 / Task #1779) to
+ * keep the parent sequencer's maintainability score above its baseline
+ * after the new wiring layer landed. The phase contract is identical to
+ * every other entry in `DEFAULT_POST_MERGE_PHASES`: take a context bag,
+ * return a value the runner stitches under a `stateKey`.
+ *
+ * ### Contract
+ *
+ * - **Pure detectors.** Both `detectRework` and `detectRetry` are pure
+ *   modules under `lib/signals/detectors/` — they read the per-Story
+ *   `traces.ndjson` and return SignalEvent arrays. This phase resolves
+ *   the operator-tunable thresholds via `getSignals(config)` (Epic
+ *   #1720 — `delivery.signals.*`), invokes each detector, and persists
+ *   each event through `appendSignal` so the per-Story `signals.ndjson`
+ *   stream covers both kinds before the analyzer reads it.
+ *
+ * - **Failure isolation.** A failing detector or a per-event append
+ *   MUST NOT block Task close. Each call is wrapped in try/catch;
+ *   failures degrade to a warn and contribute 0 to the offending
+ *   detector's count. The phase always resolves with a stable
+ *   `{ rework: N, retry: N }` shape.
+ *
+ * - **One info line per close.** The summary log
+ *   (`detectors: rework=N retry=M`) is the only stdout signal — one
+ *   line per Story rather than two per detector + N per event.
+ *
+ * - **3-tier (Storyless) closure (Story #3127).** When `tasks` is
+ *   empty (the 3-tier hierarchy shape), `resolveLastTaskId` returns
+ *   `null` and both detectors run with `taskId: null`. The detector
+ *   modules already accept a nullable `taskId` (see
+ *   `lib/signals/detectors/{rework,retry}.js`), so no branching on
+ *   hierarchy mode is required here.
+ *
+ * @module lib/orchestration/detectors-phase
+ */
+
+import { getSignals } from '../config/limits.js';
+import { storyArtifactPath } from '../config/temp-paths.js';
+import { Logger } from '../Logger.js';
+import { appendSignal } from '../observability/signals-writer.js';
+import { detectRetry, detectRework } from '../signals/detectors/index.js';
+
+function reapPhaseLogger(progress) {
+  return progress ?? (() => {});
+}
+
+function resolveLastTaskId(tasks) {
+  if (!Array.isArray(tasks) || tasks.length === 0) return null;
+  const last = tasks[tasks.length - 1];
+  const id = Number(last?.id ?? last);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
+async function persistDetectorEvents({
+  events,
+  epicId,
+  storyId,
+  config,
+  appendSignalFn,
+  logger,
+  kind,
+}) {
+  let count = 0;
+  for (const evt of events) {
+    try {
+      await appendSignalFn({ epicId, storyId, signal: evt, config });
+      count += 1;
+    } catch (err) {
+      logger?.warn?.(
+        `[detectors-phase] ${kind} appendSignal failed (${err?.message ?? err})`,
+      );
+    }
+  }
+  return count;
+}
+
+async function runOneDetector({
+  detectorFn,
+  args,
+  epicId,
+  storyId,
+  config,
+  appendSignalFn,
+  logger,
+  kind,
+}) {
+  try {
+    const events = await detectorFn(args);
+    return await persistDetectorEvents({
+      events,
+      epicId,
+      storyId,
+      config,
+      appendSignalFn,
+      logger,
+      kind,
+    });
+  } catch (err) {
+    logger?.warn?.(
+      `[detectors-phase] ${kind} detector threw (${err?.message ?? err})`,
+    );
+    return 0;
+  }
+}
+
+function isValidIdPair(eid, sid) {
+  return Number.isInteger(eid) && eid > 0 && Number.isInteger(sid) && sid > 0;
+}
+
+/**
+ * Run the rework + retry detectors for one Story and persist every
+ * emission to `temp/epic-<eid>/stories/story-<sid>/signals.ndjson`.
+ *
+ * @param {{
+ *   epicId: number|string,
+ *   storyId: number|string,
+ *   tasks?: Array<{ id?: number|string }>,
+ *   config?: object,
+ *   progress?: Function,
+ *   logger?: object,
+ *   detectorsImpl?: { detectRework?: typeof detectRework, detectRetry?: typeof detectRetry },
+ *   appendSignalFn?: typeof appendSignal,
+ * }} ctx
+ * @returns {Promise<{ rework: number, retry: number }>}
+ */
+export async function detectorsPhase(ctx) {
+  const {
+    epicId,
+    storyId,
+    tasks,
+    config,
+    progress,
+    logger = Logger,
+    detectorsImpl,
+    appendSignalFn = appendSignal,
+  } = ctx;
+  const log = reapPhaseLogger(progress);
+  const eid = Number(epicId);
+  const sid = Number(storyId);
+  if (!isValidIdPair(eid, sid)) {
+    logger?.warn?.(
+      `[detectors-phase] skipped: invalid epicId=${epicId} / storyId=${storyId}`,
+    );
+    return { rework: 0, retry: 0 };
+  }
+
+  let signalsCfg;
+  try {
+    signalsCfg = getSignals(config);
+  } catch (err) {
+    logger?.warn?.(
+      `[detectors-phase] getSignals failed (${err?.message ?? err}); using zero counts`,
+    );
+    return { rework: 0, retry: 0 };
+  }
+
+  const tracesPath = storyArtifactPath(eid, sid, 'traces.ndjson', config);
+  const taskId = resolveLastTaskId(tasks);
+  const baseArgs = { tracesPath, epicId: eid, storyId: sid, taskId };
+  const common = {
+    epicId: eid,
+    storyId: sid,
+    config,
+    appendSignalFn,
+    logger,
+  };
+
+  const rework = await runOneDetector({
+    ...common,
+    detectorFn: detectorsImpl?.detectRework ?? detectRework,
+    args: { ...baseArgs, threshold: signalsCfg.rework.editsPerFile },
+    kind: 'rework',
+  });
+  const retry = await runOneDetector({
+    ...common,
+    detectorFn: detectorsImpl?.detectRetry ?? detectRetry,
+    args: { ...baseArgs, threshold: signalsCfg.retry.repeatCount },
+    kind: 'retry',
+  });
+
+  log('DETECTORS', `detectors: rework=${rework} retry=${retry}`);
+  return { rework, retry };
+}

package/.agents/scripts/lib/orchestration/dispatch-engine.js

@@ -0,0 +1,144 @@
+/**
+ * lib/orchestration/dispatch-engine.js — Core Dispatch Engine (SDK coordinator)
+ *
+ * Thin facade composing:
+ *   - `dispatch-pipeline.js` — internal resolve/fetch/reconcile/graph helpers
+ *
+ * Every Epic is 3-tier (Epic → Feature → Story); `dispatch()` computes a
+ * Story-level wave plan and emits a 3-tier manifest. The legacy Task-tier
+ * dispatch runtime (Task fetcher, single-Story executor, the per-Task
+ * wave fan-out, and the Epic-completion detector) was removed in Epic
+ * #3163.
+ */
+
+import { PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
+import { ConflictingTypeLabelsError } from '../errors/index.js';
+import { ensureLocalBranch } from '../git-branch-lifecycle.js';
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { createProvider } from '../provider-factory.js';
+import {
+  buildStoryDispatchGraph,
+  fetchEpicContext,
+  isThreeTierDispatch,
+  reconcileEpicState,
+  resolveDispatchContext,
+} from './dispatch-pipeline.js';
+import { buildManifest } from './manifest-builder.js';
+import { STATE_LABELS } from './ticketing.js';
+
+export const AGENT_DONE_LABEL = STATE_LABELS.DONE;
+export const AGENT_EXECUTING_LABEL = STATE_LABELS.EXECUTING;
+export const AGENT_READY_LABEL = STATE_LABELS.READY;
+
+/* node:coverage ignore next */
+export function ensureBranch(branchName, baseBranch) {
+  ensureLocalBranch(branchName, baseBranch, PROJECT_ROOT, {
+    log: (msg) => Logger.info(msg),
+  });
+}
+
+/**
+ * Resolve a single ticket ID, detect its type, and delegate to the
+ * appropriate execution pipeline. Single entry point shared by the CLI
+ * wrapper and the MCP `dispatch_wave` tool.
+ */
+export async function resolveAndDispatch(options) {
+  const { ticketId, dryRun = false } = options;
+  const config = resolveConfig();
+  const provider = options.provider ?? createProvider(config);
+
+  const ticket = await provider.getTicket(ticketId);
+  const labels = ticket.labels || [];
+
+  const typeLabels = labels.filter((l) => l.startsWith('type::'));
+  if (typeLabels.length > 1) {
+    throw new ConflictingTypeLabelsError(
+      `Ticket #${ticketId} has conflicting type labels: ${typeLabels.join(', ')}. Exactly one type::* label is required.`,
+    );
+  }
+
+  const isStory = labels.includes(TYPE_LABELS.STORY);
+  const isEpic = labels.includes(TYPE_LABELS.EPIC);
+  const isFeature = labels.includes(TYPE_LABELS.FEATURE);
+
+  if (isStory) {
+    throw new Error(
+      `[Dispatcher] Ticket #${ticketId} is a **Story**. Stories are dispatched ` +
+        'through the 3-tier Story path, not directly via the dispatcher. ' +
+        `Run \`/story-deliver ${ticketId}\` to execute this Story, ` +
+        `or dispatch its parent Epic with \`/epic-deliver #<epicId>\`.`,
+    );
+  }
+
+  if (isEpic) {
+    return dispatch({ epicId: ticketId, dryRun, provider });
+  }
+
+  if (isFeature) {
+    throw new Error(
+      `[Dispatcher] Ticket #${ticketId} is a **Feature**. Features are containers and cannot be executed directly. ` +
+        `Please execute individual Stories within this Feature using \`/epic-deliver #[Story ID]\`, ` +
+        `or dispatch the entire Epic using \`/epic-deliver #${ticket.body?.match(/^parent:\s*#(\d+)/m)?.[1] || 'ID'}\`.`,
+    );
+  }
+
+  const typeLabel = labels.find((l) => l.startsWith('type::')) || 'unknown';
+  throw new Error(
+    `[Dispatcher] Ticket #${ticketId} has type "${typeLabel.replace('type::', '')}". ` +
+      `Only "epic" or "story" tickets can be dispatched. ` +
+      `Please ensure the ticket is correctly categorized before execution.`,
+  );
+}
+
+/**
+ * Main dispatcher. Orchestrates one dispatch cycle for an Epic.
+ * Primary public export of the orchestration SDK.
+ */
+export async function dispatch(options) {
+  const ctx = resolveDispatchContext(options, ensureBranch);
+  const { epicId, dryRun } = ctx;
+
+  const fetched = await fetchEpicContext(ctx);
+  await reconcileEpicState(ctx, fetched);
+
+  // Every Epic is 3-tier (Epic → Feature → Story). Compute Story-level
+  // waves directly from the Story tickets and emit a 3-tier-shaped
+  // manifest with `waves[].stories[]` so downstream consumers (manifest
+  // renderer, /epic-deliver wave planner) see the correct execution plan.
+  // Per-Story execution is owned by `/story-deliver` (story-init →
+  // story-close), not by this dispatcher.
+  if (isThreeTierDispatch(fetched.allTickets)) {
+    Logger.info(
+      'Detected 3-tier hierarchy — computing Story-level execution waves.',
+    );
+    const { allWaves: storyWaves } = buildStoryDispatchGraph(
+      fetched.allTickets,
+    );
+    return buildManifest({
+      epicId,
+      epic: fetched.epic,
+      tasks: [],
+      allTickets: fetched.allTickets,
+      waves: storyWaves,
+      dispatched: [],
+      dryRun,
+      hierarchy: '3-tier',
+    });
+  }
+
+  // No Story tickets under the Epic — nothing to dispatch. Emit an empty
+  // manifest so callers (renderer, /epic-deliver) get a well-formed
+  // artifact instead of a throw.
+  Logger.info('No Story tickets found under the Epic. Nothing to dispatch.');
+  return buildManifest({
+    epicId,
+    epic: fetched.epic,
+    tasks: [],
+    allTickets: fetched.allTickets,
+    waves: [],
+    dispatched: [],
+    dryRun,
+    hierarchy: '3-tier',
+  });
+}

package/.agents/scripts/lib/orchestration/dispatch-pipeline.js

@@ -0,0 +1,206 @@
+/**
+ * dispatch-pipeline.js
+ *
+ * Internal pipeline helpers composed by `dispatch-engine.js::dispatch()`.
+ * Keeping these out of the coordinator keeps the public entry point compact
+ * and focused on the 3-tier flow: resolve → fetch → reconcile → Story-graph.
+ */
+
+import { PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
+import { parseBlockedBy } from '../dependency-parser.js';
+import { getEpicBranch } from '../git-utils.js';
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { createProvider } from '../provider-factory.js';
+import { WorktreeManager } from '../worktree-manager.js';
+import { computeStoryWaves } from './dependency-analyzer.js';
+import { reconcileHierarchy } from './reconciler.js';
+
+/**
+ * Runtime context for a single dispatch cycle.
+ *
+ * Produced by {@link resolveDispatchContext} and consumed by every pipeline
+ * stage (fetch → reconcile → graph → scaffold → GC → dispatch). All fields
+ * are resolved once up-front so downstream helpers can stay free of
+ * configuration look-ups.
+ *
+ * @typedef {object} DispatchContext
+ * @property {number} epicId                                  Epic ticket number under dispatch.
+ * @property {boolean} dryRun                                 When true, mutating side-effects are skipped.
+ * @property {object} config                                  Resolved canonical `.agentrc.json` (with `project`, `github`, `planning`, `delivery` blocks).
+ * @property {import('../ITicketingProvider.js').ITicketingProvider} provider  Ticketing provider (may come from cache).
+ * @property {import('../worktree-manager.js').WorktreeManager | undefined} worktreeManager  Optional worktree manager (only when isolation is enabled and not dry-run).
+ * @property {string} baseBranch                              Trunk branch the Epic branches from (default `main`).
+ * @property {string} epicBranch                              Epic branch name (`epic/<epicId>`).
+ * @property {(branchName: string, baseBranch: string) => void} ensureBranch  Caller-supplied branch-creation helper.
+ */
+
+/**
+ * The output of {@link fetchEpicContext}.
+ *
+ * @typedef {object} FetchedEpic
+ * @property {object} epic                 The Epic ticket record.
+ * @property {object[]} allTickets         Every ticket under the Epic (stories + features + health).
+ * @property {Map<number, object>} allTicketsById  Index of `allTickets` by ticket id.
+ */
+
+/**
+ * Resolve the runtime context for a dispatch: canonical config, provider, adapter,
+ * worktree manager, base/epic branch names, and the `ensureBranch` bound
+ * helper supplied by the caller.
+ *
+ * @param {object} options                                    Dispatch entry options.
+ * @param {number} options.epicId                             Epic ticket number.
+ * @param {boolean} [options.dryRun=false]                    When true, skip branch creation and worktree setup.
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} [options.provider]  Pre-constructed provider (overrides factory).
+ * @param {import('../worktree-manager.js').WorktreeManager} [options.worktreeManager]  Pre-constructed worktree manager.
+ * @param {(branchName: string, baseBranch: string) => void} ensureBranch  Branch-creation helper bound by caller (keeps engine ↔ git-lifecycle coupling at the edge).
+ * @returns {DispatchContext}                                 Fully resolved dispatch context.
+ */
+export function resolveDispatchContext(options, ensureBranch) {
+  const { epicId, dryRun = false } = options;
+
+  const config = resolveConfig();
+  const provider = options.provider ?? createProvider(config);
+
+  const wtConfig = config?.delivery?.worktreeIsolation;
+  let worktreeManager = options.worktreeManager;
+  if (!worktreeManager && wtConfig?.enabled && !dryRun) {
+    worktreeManager = new WorktreeManager({
+      repoRoot: PROJECT_ROOT,
+      config: wtConfig,
+    });
+  }
+
+  return {
+    epicId,
+    dryRun,
+    config,
+    provider,
+    worktreeManager,
+    baseBranch: config?.project?.baseBranch ?? 'main',
+    epicBranch: getEpicBranch(epicId),
+    ensureBranch,
+  };
+}
+
+/**
+ * Fetch Epic + all tickets and prime the provider cache.
+ *
+ * @param {DispatchContext} ctx  Dispatch context.
+ * @returns {Promise<FetchedEpic>}  Epic + ticket graph.
+ */
+export async function fetchEpicContext(ctx) {
+  const { provider, epicId } = ctx;
+
+  Logger.info(`\nFetching Epic #${epicId}...`);
+  const epic = await provider.getEpic(epicId);
+
+  Logger.info(`Fetching all tickets under Epic #${epicId}...`);
+  const allTickets = await provider.getTickets(epicId);
+  const allTicketsById = new Map(allTickets.map((t) => [t.id, t]));
+
+  provider.primeTicketCache(allTickets);
+
+  return { epic, allTickets, allTicketsById };
+}
+
+/**
+ * Propagate already-done work up the hierarchy so the manifest reflects
+ * reality before dispatch. Walks Stories → Features bottom-up.
+ *
+ * @param {DispatchContext} ctx  Dispatch context.
+ * @param {FetchedEpic} fetched  Result of {@link fetchEpicContext}.
+ * @returns {Promise<void>}
+ */
+export async function reconcileEpicState(ctx, fetched) {
+  const { provider, dryRun, epicId } = ctx;
+  const { epic, allTickets } = fetched;
+
+  await reconcileHierarchy(provider, epicId, epic, allTickets, dryRun);
+}
+
+/**
+ * Detect 3-tier hierarchy from the fetched ticket graph. After Epic #3163's
+ * hard cutover deleted the `type::task` ticket layer, shape selection is
+ * purely structural: any Epic carrying at least one `type::story` ticket
+ * resolves to 3-tier.
+ *
+ * @param {object[]} allTickets
+ * @returns {boolean}
+ */
+export function isThreeTierDispatch(allTickets) {
+  if (!Array.isArray(allTickets) || allTickets.length === 0) return false;
+  return allTickets.some((t) =>
+    (t.labelSet ?? new Set(t.labels ?? [])).has(TYPE_LABELS.STORY),
+  );
+}
+
+/**
+ * Build the Story-level dispatch graph for a 3-tier Epic. Reads story
+ * tickets from `allTickets`, parses cross-Story `blocked by` references
+ * from each Story body (also honoring an optional `dependencies[]`
+ * field set by fixture providers), and computes wave indices via
+ * {@link computeStoryWaves}.
+ *
+ * The returned `allWaves` is an array of Story-ticket arrays, ordered by
+ * wave index. `storyMap` indexes the same Story tickets by id for downstream
+ * lookups (mirrors the `taskMap` returned by {@link buildDispatchGraph}).
+ *
+ * Stories with no resolvable wave (cycle pre-filter, missing in groups)
+ * are placed in their own trailing wave so they remain visible in the
+ * manifest output.
+ *
+ * @param {object[]} allTickets  Fetched ticket graph (Epic + Features + Stories).
+ * @returns {{ allWaves: object[][], storyMap: Map<number, object> }}
+ * @throws {Error} When the Story dependency graph contains a cycle.
+ */
+export function buildStoryDispatchGraph(allTickets) {
+  const stories = (allTickets ?? []).filter((t) =>
+    (t.labelSet ?? new Set(t.labels ?? [])).has(TYPE_LABELS.STORY),
+  );
+  const storyMap = new Map(stories.map((s) => [s.id, s]));
+
+  const explicitDeps = new Map();
+  for (const story of stories) {
+    const fromBody = parseBlockedBy(story.body ?? '');
+    const fromField = Array.isArray(story.dependencies)
+      ? story.dependencies.map(Number)
+      : [];
+    const merged = [...new Set([...fromBody, ...fromField])].filter(
+      (id) => Number.isInteger(id) && id !== story.id && storyMap.has(id),
+    );
+    if (merged.length > 0) explicitDeps.set(story.id, merged);
+  }
+
+  // computeStoryWaves expects a Map<storyId, { tasks: [] }>; with no Tasks
+  // present, only explicitDeps + focus-area rollup (no-op for empty
+  // task lists) drive wave assignment.
+  const storyGroups = new Map(
+    stories.map((s) => [s.id, { storyId: s.id, tasks: [] }]),
+  );
+  const waveAssignment = computeStoryWaves(storyGroups, explicitDeps);
+
+  // Bucket stories by wave index. `computeStoryWaves` returns -1 for any
+  // story it could not place; route those into a trailing bucket so they
+  // still surface in the manifest.
+  const byWave = new Map();
+  let maxWave = -1;
+  for (const story of stories) {
+    const wave = waveAssignment.get(story.id) ?? -1;
+    if (wave > maxWave) maxWave = wave;
+    if (!byWave.has(wave)) byWave.set(wave, []);
+    byWave.get(wave).push(story);
+  }
+
+  const allWaves = [];
+  for (let i = 0; i <= maxWave; i++) {
+    if (byWave.has(i)) allWaves.push(byWave.get(i));
+  }
+  if (byWave.has(-1)) allWaves.push(byWave.get(-1));
+
+  Logger.info(
+    `Computed ${allWaves.length} Story-level execution wave(s) (3-tier).`,
+  );
+  return { allWaves, storyMap };
+}

package/.agents/scripts/lib/orchestration/doc-reader.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getPaths } from '../config-resolver.js';
+import { Logger } from '../Logger.js';
+import { applyBudget } from './planning-context-budget.js';
+
+async function readDocsFromRoot(docsRoot, settings) {
+  const explicit =
+    Array.isArray(settings.docsContextFiles) &&
+    settings.docsContextFiles.length > 0;
+  const usedFallback = !explicit;
+  let targetFiles;
+  if (explicit) {
+    targetFiles = settings.docsContextFiles.map((f) => ({
+      name: f,
+      full: path.join(docsRoot, f),
+    }));
+  } else {
+    const entries = fs.readdirSync(docsRoot, { withFileTypes: true });
+    targetFiles = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => ({ name: e.name, full: path.join(docsRoot, e.name) }));
+  }
+
+  const reads = targetFiles.map(async ({ name, full }) => {
+    try {
+      const stat = await fs.promises.stat(full);
+      if (!stat.isFile()) return null;
+      const content = await fs.promises.readFile(full, 'utf-8');
+      return { name, path: name, content };
+    } catch (_e) {
+      return null;
+    }
+  });
+
+  const docs = (await Promise.all(reads)).filter(Boolean);
+  return { docs, usedFallback };
+}
+
+/**
+ * Read project documentation, returning raw doc objects so callers can apply
+ * the planning-context budget themselves. Each entry is `{ name, path,
+ * content }`. The legacy single-string concatenation is no longer the public
+ * surface — use {@link buildDocsContext} when an envelope-shaped value is
+ * needed.
+ *
+ * @param {object} settings — Resolved config bag (`project.paths.docsRoot`,
+ *   `project.docsContextFiles`) or legacy-shim view (same shape).
+ * @returns {Promise<{ docs: Array<{name: string, path: string, content: string}>, usedFallback: boolean }>}
+ */
+export async function scrapeProjectDocs(settings) {
+  // `settings` is the legacy-shim view (`{ paths, docsContextFiles, ... }`)
+  // OR the post-reshape canonical (`{ project: { paths, ... } }`). Under the
+  // resolver shim `agentSettings.paths === project.paths`, so re-wrap to the
+  // canonical shape `getPaths` consumes.
+  const docsRoot = getPaths({
+    project: { paths: settings?.project?.paths ?? settings?.paths },
+  }).docsRoot;
+  if (!docsRoot || !fs.existsSync(docsRoot)) {
+    return { docs: [], usedFallback: false };
+  }
+  Logger.info(`[Epic Planner] Scraping project docs from ${docsRoot}...`);
+  try {
+    const result = await readDocsFromRoot(docsRoot, settings);
+    if (result.usedFallback) {
+      Logger.warn(
+        '[Epic Planner] ⚠️  project.docsContextFiles is unset — falling back to every top-level *.md under docsRoot. Configure docsContextFiles for production planning.',
+      );
+    }
+    return result;
+  } catch (err) {
+    Logger.warn(
+      `[Epic Planner] Warning: Failed to read docsRoot: ${err.message}`,
+    );
+    return { docs: [], usedFallback: false };
+  }
+}
+
+/**
+ * Build the `docsContext` value emitted in `--emit-context` envelopes.
+ * Reads the docs and applies the planning-context budget so over-budget
+ * payloads downgrade to summary mode automatically. Callers pass
+ * `{ fullContext: true }` to honour the `--full-context` CLI opt-in.
+ *
+ * @param {object} settings — Resolved config bag (same shape as `scrapeProjectDocs`).
+ * @param {{ maxBytes?: number, summaryMode?: 'auto'|'always'|'never' }} [planningLimits]
+ * @param {{ fullContext?: boolean }} [opts]
+ * @returns {Promise<{ mode: 'full'|'summary', items: Array<object>, totalBytes: number, usedFallback: boolean }>}
+ */
+export async function buildDocsContext(settings, planningLimits, opts = {}) {
+  const { docs, usedFallback } = await scrapeProjectDocs(settings);
+  const budgeted = applyBudget(docs, planningLimits, opts);
+  return { ...budgeted, usedFallback };
+}