mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/planning-artifacts.js

@@ -0,0 +1,75 @@
+/**
+ * planning-artifacts.js — Phase 1 of the epic-plan-decompose pipeline
+ * (Story #2466). Owns the `## Planning Artifacts` body shim and the
+ * cross-Story conflict-policy resolver.
+ *
+ * Extracted verbatim from `epic-plan-decompose.js` so the named exports
+ * the existing unit tests import (`ensurePlanningArtifacts`) keep their
+ * public surface byte-identical.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/planning-artifacts
+ */
+
+import { resolveListValue } from '../../../config/shared.js';
+import { _internal as conflictInternal } from '../../ticket-validator-conflicts.js';
+
+/**
+ * Ensure the supplied Epic body carries a `## Planning Artifacts` section.
+ * Idempotent — when the section already exists the body is returned
+ * verbatim; when it's missing and `linkedIssues` carries resolved ids
+ * the section is appended exactly once using the canonical
+ * `- [ ] PRD: #N` / `Tech Spec: #N` / `Acceptance Spec: #N` lines that
+ * `issue-link-parser.js` recognises (so cascade-close still resolves the
+ * linked tickets).
+ *
+ * Story #2283.
+ *
+ * @param {string} body
+ * @param {{ prd: number|null, techSpec: number|null, acceptanceSpec: number|null } | undefined | null} linkedIssues
+ * @returns {string}
+ */
+export function ensurePlanningArtifacts(body, linkedIssues) {
+  const safeBody = typeof body === 'string' ? body : '';
+  if (safeBody.includes('## Planning Artifacts')) return safeBody;
+  if (!linkedIssues) return safeBody;
+  const lines = [];
+  if (Number.isInteger(linkedIssues.prd)) {
+    lines.push(`- [ ] PRD: #${linkedIssues.prd}`);
+  }
+  if (Number.isInteger(linkedIssues.techSpec)) {
+    lines.push(`- [ ] Tech Spec: #${linkedIssues.techSpec}`);
+  }
+  if (Number.isInteger(linkedIssues.acceptanceSpec)) {
+    lines.push(`- [ ] Acceptance Spec: #${linkedIssues.acceptanceSpec}`);
+  }
+  if (lines.length === 0) return safeBody;
+  return `${safeBody}\n\n## Planning Artifacts\n${lines.join('\n')}\n`;
+}
+
+/**
+ * Resolve the cross-Story conflict-finding policy from `_config.planning`.
+ * Both flags default to `false` so existing repos keep the advisory-only
+ * behaviour; setting either to `true` upgrades the matching finding class
+ * to `'hard'`, which routes it through the validator's `errors[]` channel
+ * and (when called inside the bounded decompose loop) triggers a re-prompt.
+ */
+export function resolveConflictPolicy(cfg) {
+  const planning = cfg?.planning;
+  const policy = {
+    failOnSharedEditors: planning?.failOnSharedEditors === true,
+    requireExplicitCrossStoryDeps:
+      planning?.requireExplicitCrossStoryDeps === true,
+    failOnRegistryConflicts: planning?.failOnRegistryConflicts === true,
+    failOnLargeFanOut: planning?.failOnLargeFanOut === true,
+  };
+  if (Number.isFinite(planning?.largeFanOutThreshold)) {
+    policy.largeFanOutThreshold = planning.largeFanOutThreshold;
+  }
+  if (planning?.crossCuttingRegistries !== undefined) {
+    policy.registries = resolveListValue(
+      conflictInternal.DEFAULT_REGISTRY_PATTERNS,
+      planning.crossCuttingRegistries,
+    );
+  }
+  return policy;
+}

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/reconcile-spawn.js

@@ -0,0 +1,86 @@
+/**
+ * reconcile-spawn.js — helper for `persist.js` (Story #2466).
+ *
+ * Owns the bridge between the decomposer pipeline and the structural
+ * reconciler entry script (`epic-reconcile.js`). Two pieces are split
+ * out so `persist.js` stays under Story #2466's 200-LOC ceiling:
+ *
+ *   - `RECONCILE_CLI` — the canonical path to `epic-reconcile.js` resolved
+ *     against the phases-module location (this file lives four levels
+ *     below `.agents/scripts/`).
+ *   - `spawnReconcilerApply({ spawnSync, reconcileCli, epicId, cwd,
+ *     explicitDelete })` — invokes the reconciler in `--apply --yes` mode
+ *     (appending `--explicit-delete` when `explicitDelete` is true),
+ *     surfaces stdout + stderr to the parent stream, and throws when the
+ *     child exits non-zero. Returns the same `{ status, stdout, stderr }`
+ *     envelope the legacy in-line invocation produced.
+ *
+ * Story #3905 — a `--force` re-plan with a changed ticket set produces a
+ * plan that carries close ops (the slugs the new plan drops). The
+ * reconciler hard-exits 2 on close ops unless `--explicit-delete` is
+ * passed. The persist phase therefore threads `--force` through to this
+ * helper as `explicitDelete` so a force re-decompose can actually close
+ * the dropped children instead of failing after the spec was already
+ * overwritten.
+ *
+ * @module lib/orchestration/epic-plan-decompose/phases/reconcile-spawn
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// phases/ → epic-plan-decompose/ → orchestration/ → lib/ → scripts/ →
+// repo-relative `epic-reconcile.js` entry point.
+export const RECONCILE_CLI = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'epic-reconcile.js',
+);
+
+/**
+ * Run `epic-reconcile.js --apply --yes` against `epicId`, surface stdout
+ * and stderr to the parent stream, and throw when the child exits
+ * non-zero. Returns the `{ status, stdout, stderr }` envelope used by
+ * the persist phase's return contract.
+ *
+ * When `explicitDelete` is true, `--explicit-delete` is appended so a
+ * plan carrying close ops (the common shape of a `--force` re-plan that
+ * dropped slugs) applies instead of hard-exiting 2 (Story #3905).
+ *
+ * @param {{ spawnSync: Function, reconcileCli: string, epicId: number, cwd: string, explicitDelete?: boolean }} args
+ */
+export function spawnReconcilerApply({
+  spawnSync,
+  reconcileCli,
+  epicId,
+  cwd,
+  explicitDelete = false,
+}) {
+  const reconcileArgs = [reconcileCli, String(epicId), '--apply', '--yes'];
+  if (explicitDelete) reconcileArgs.push('--explicit-delete');
+  const reconcileResult = spawnSync(process.execPath, reconcileArgs, {
+    cwd,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    env: { ...process.env, EPIC_RECONCILE_INVOKER: 'epic-plan-decompose' },
+  });
+  const reconcile = {
+    status: reconcileResult.status ?? 1,
+    stdout: reconcileResult.stdout ?? '',
+    stderr: reconcileResult.stderr ?? '',
+  };
+  if (reconcile.stdout) process.stdout.write(reconcile.stdout);
+  if (reconcile.stderr) process.stderr.write(reconcile.stderr);
+  if (reconcile.status !== 0) {
+    throw new Error(
+      `[epic-plan-decompose] epic-reconcile.js exited with status ${reconcile.status}. See stderr above.`,
+    );
+  }
+  return reconcile;
+}

package/.agents/scripts/lib/orchestration/epic-plan-lease-guard.js

@@ -0,0 +1,235 @@
+/**
+ * epic-plan-lease-guard.js — `/epic-plan` workflow guards (Story #3481,
+ * Epic #3457).
+ *
+ * Wires the assignee-as-lease primitive (`ticket-lease.js`, Story #3480) and a
+ * decompose-idempotency guard into the split planning flow so two concurrent
+ * `/epic-plan` runs cannot both drive the same Epic, and so a re-run does not
+ * silently duplicate the Feature/Story tree:
+ *
+ *   - `acquireEpicPlanLease`   — claim the Epic before Phase 7 (spec). Refuses
+ *                                (throws, exit non-zero) when a foreign claim
+ *                                already holds the Epic, naming the current
+ *                                owner. **Fail-closed (audit #3513):**
+ *                                `/epic-plan` emits no `story.heartbeat` during
+ *                                its run (heartbeats are a delivery-time
+ *                                signal), so there is no live-heartbeat source
+ *                                to judge a concurrent plan's liveness from.
+ *                                Defaulting liveness to "stale" made every
+ *                                foreign claim look reclaimable, leaving the
+ *                                guard inert. We therefore treat ANY foreign
+ *                                assignee as a live claim and refuse the take
+ *                                unless `--steal` forcibly transfers it. An
+ *                                unassigned or self-held Epic still proceeds.
+ *   - `releaseEpicPlanLease`   — release the claim after Phase 8 (decompose).
+ *                                Best-effort and self-scoped: a no-op once the
+ *                                Epic was reassigned elsewhere.
+ *   - `assertNoOpenPlanChildren` — refuse Phase 8 persist when the Epic already
+ *                                has open Feature/Story children, unless the
+ *                                operator passed `--force` (a deliberate
+ *                                re-decompose that closes the old tree).
+ *
+ * The PRD / Tech Spec find-or-create idempotency already lives in
+ * `phases/plan-epic.js` (keyed on `epic.linkedIssues`); these guards add the
+ * cross-run mutual exclusion and the child-duplication refusal around it.
+ */
+
+import { getGitHub } from '../config/github.js';
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import {
+  acquireLease,
+  normalizeOperatorHandle,
+  releaseLease,
+} from './ticket-lease.js';
+
+/**
+ * Resolve the operator handle that owns this `/epic-plan` run from
+ * `github.operatorHandle`. The assignee-as-lease primitive is single-holder
+ * keyed on a non-empty string; when no operator is configured (unset, or the
+ * shipped `@[USERNAME]` placeholder, both of which `normalizeOperatorHandle`
+ * maps to `null`) the lease cannot be keyed. This returns `null`; the caller
+ * (`acquireEpicPlanLease`) then fails closed by throwing rather than running an
+ * ownerless, unguarded plan.
+ *
+ * The `@`-prefix some operators carry on `operatorHandle` is stripped so the
+ * value matches the bare login GitHub writes to (and returns from) a ticket's
+ * `assignees` — otherwise the assignee PATCH is rejected (HTTP 422, invalid
+ * assignee) and the self-held-claim comparison (`owner === operator`) never
+ * matches. This mirrors the sibling lease guards
+ * (`single-story-lease-guard.js`, `epic-deliver-lease-guard.js`).
+ *
+ * @param {object} config Resolved config bag.
+ * @returns {string|null}
+ */
+export function resolveOperator(config) {
+  return normalizeOperatorHandle(getGitHub(config).operatorHandle);
+}
+
+/**
+ * Acquire the Epic-lease before Phase 7.
+ *
+ * **Fail-closed (audit #3513).** `/epic-plan` emits no `story.heartbeat`
+ * during its run, so there is no live-heartbeat source to judge a concurrent
+ * plan's liveness from. Rather than default liveness to "stale" (which made
+ * every foreign claim look reclaimable and left this guard inert), we anchor
+ * `heartbeatAt` to the same `now` the lease primitive evaluates against. That
+ * makes `isClaimLive` return true for ANY foreign owner, so `acquireLease`
+ * refuses a foreign assignee unless `steal` is set — naming the current owner.
+ * An unassigned Epic (`unclaimed`) or a self-held claim (`already-held`) still
+ * proceeds without a write. This mirrors `single-story-lease-guard.js`.
+ *
+ * A refused claim throws (caught at the CLI boundary → exit non-zero).
+ *
+ * @param {object} args
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} args.provider
+ * @param {number} args.epicId
+ * @param {object} [args.config]
+ * @param {boolean} [args.steal=false]   Force-transfer a foreign claim.
+ * @param {number} [args.now]            Injectable clock (epoch ms; tests).
+ * @returns {Promise<{ acquired: boolean, owner: string|null, previousOwner: string|null, reason: string }>}
+ */
+export async function acquireEpicPlanLease({
+  provider,
+  epicId,
+  config,
+  steal = false,
+  now,
+}) {
+  const operator = resolveOperator(config);
+  if (operator === null) {
+    throw new Error(
+      `[epic-plan] Refusing to plan Epic #${epicId}: no operator identity is ` +
+        'configured. github.operatorHandle is unset or still the shipped ' +
+        '`@[USERNAME]` placeholder, so the Epic-lease has no owner and ' +
+        'concurrent /epic-plan runs cannot be serialised. Set your own handle ' +
+        'in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
+        '"@your-login" } }) and re-run.',
+    );
+  }
+
+  // Fail closed: with no live-heartbeat source on the plan path, treat any
+  // foreign assignee as a live claim by anchoring `heartbeatAt` to the same
+  // `now` the primitive evaluates against (`isClaimLive` → true for any owner).
+  // `acquireLease` then refuses a foreign claim unless `steal` is set; an
+  // unassigned or self-held Epic proceeds without a write.
+  const resolvedNow =
+    typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+  const result = await acquireLease({
+    provider,
+    ticketId: epicId,
+    operator,
+    heartbeatAt: resolvedNow,
+    steal,
+    config,
+    now: resolvedNow,
+  });
+
+  if (!result.acquired) {
+    throw new Error(
+      `[epic-plan] Epic #${epicId} is currently claimed by '${result.owner}'. ` +
+        `Refusing to plan concurrently — another /epic-plan run owns this Epic ` +
+        `(the plan path has no heartbeat ledger, so a foreign assignee always ` +
+        `blocks unless stolen). Wait for that run to finish, or re-run with ` +
+        `--steal to forcibly transfer the claim once you have confirmed the ` +
+        `other run is dead.`,
+    );
+  }
+
+  Logger.info(
+    `[epic-plan] Acquired Epic-lease on #${epicId} for '${operator}' ` +
+      `(reason: ${result.reason}).`,
+  );
+  return result;
+}
+
+/**
+ * Release the Epic-lease after Phase 8. Best-effort: a release failure (or a
+ * lease already reassigned elsewhere) MUST NOT fail the decompose phase, which
+ * has already persisted the plan by the time release runs.
+ *
+ * @param {object} args
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} args.provider
+ * @param {number} args.epicId
+ * @param {object} [args.config]
+ * @returns {Promise<{ released: boolean, owner: string|null, reason: string }>}
+ */
+export async function releaseEpicPlanLease({ provider, epicId, config }) {
+  const operator = resolveOperator(config);
+  if (operator === null) {
+    return { released: false, owner: null, reason: 'no-operator' };
+  }
+  try {
+    const result = await releaseLease({
+      provider,
+      ticketId: epicId,
+      operator,
+      config,
+    });
+    if (result.released) {
+      Logger.info(`[epic-plan] Released Epic-lease on #${epicId}.`);
+    } else {
+      Logger.info(
+        `[epic-plan] Epic-lease on #${epicId} not released (${result.reason}).`,
+      );
+    }
+    return result;
+  } catch (err) {
+    Logger.warn(
+      `[epic-plan] Lease release on #${epicId} failed (non-fatal): ${err.message}`,
+    );
+    return { released: false, owner: null, reason: 'release-error' };
+  }
+}
+
+/**
+ * Refuse a Phase 8 decompose-persist when the Epic already has open
+ * Feature/Story children, unless `force` is set. This is the idempotency guard
+ * that prevents a re-run from stacking a duplicate Feature/Story tree on top of
+ * an existing one. Under `--force` the decomposer closes and recreates the
+ * tree, so the guard steps aside.
+ *
+ * @param {object} args
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} args.provider
+ * @param {number} args.epicId
+ * @param {boolean} [args.force=false]
+ * @returns {Promise<{ openChildren: Array<{ id: number, title: string }> }>}
+ */
+export async function assertNoOpenPlanChildren({
+  provider,
+  epicId,
+  force = false,
+}) {
+  if (force) return { openChildren: [] };
+
+  const children = await provider.getSubTickets(epicId);
+  const openChildren = (children ?? []).filter((t) => {
+    const labels = Array.isArray(t.labels) ? t.labels : [];
+    const isOpen = t.state === undefined || t.state === 'open';
+    return (
+      isOpen &&
+      (labels.includes(TYPE_LABELS.FEATURE) ||
+        labels.includes(TYPE_LABELS.STORY))
+    );
+  });
+
+  if (openChildren.length > 0) {
+    const summary = openChildren
+      .slice(0, 10)
+      .map((t) => `  - #${t.id} ${t.title}`)
+      .join('\n');
+    const more =
+      openChildren.length > 10
+        ? `\n  …and ${openChildren.length - 10} more`
+        : '';
+    throw new Error(
+      `[epic-plan-decompose] Epic #${epicId} already has ` +
+        `${openChildren.length} open Feature/Story child ticket(s):\n${summary}${more}\n\n` +
+        `Persisting now would duplicate the breakdown. Re-run with --force to ` +
+        `close the existing tree and re-decompose, or close the stale children ` +
+        `by hand first.`,
+    );
+  }
+
+  return { openChildren: [] };
+}

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/authoring-context.js

@@ -0,0 +1,197 @@
+/**
+ * phases/authoring-context.js — emit-context phase.
+ *
+ * Builds the authoring context the host LLM (or the
+ * `epic-plan-spec-author` Skill) needs to write the PRD and Tech Spec.
+ * Returns a plain JSON-serialisable object; never hits the network beyond
+ * the provider call needed to load the Epic.
+ */
+
+import * as os from 'node:os';
+import path from 'node:path';
+import {
+  resolveFeatureRoots,
+  verifyBddRunnerPendingTag,
+} from '../../../bdd-runner-detect.js';
+import { scanBddScenarios } from '../../../bdd-scenario-scanner.js';
+import { buildCodebaseSnapshot } from '../../../codebase-snapshot.js';
+import { getLimits, PROJECT_ROOT } from '../../../config-resolver.js';
+import { scanMemoryFreshness } from '../../../feedback-loop/memory-freshness.js';
+import { fetchPriorFeedback } from '../../../feedback-loop/prior-feedback-fetcher.js';
+import { Logger } from '../../../Logger.js';
+import { buildDocsContext } from '../../doc-reader.js';
+import { applyBudget } from '../../planning-context-budget.js';
+import {
+  ACCEPTANCE_SPEC_SYSTEM_PROMPT,
+  PRD_SYSTEM_PROMPT,
+  TECH_SPEC_SYSTEM_PROMPT,
+} from './prompts.js';
+
+/**
+ * Resolve the per-project memory directory used by the memory-freshness
+ * pre-flight (Story #2557 / Epic #2547).
+ *
+ * Resolution order:
+ *   1. `MANDREL_MEMORY_DIR` environment variable (test seam and operator
+ *      override).
+ *   2. `~/.claude/projects/<repo>/memory/` — the standard Claude Code
+ *      memory substrate path, scoped by the configured GitHub repo so each
+ *      consumer project gets its own memory pool.
+ *   3. `null` when neither is resolvable. The scanner tolerates a missing
+ *      `memoryDir` and surfaces a single `errors[]` entry.
+ *
+ * @param {{ github?: { owner?: string, repo?: string }|null }} opts
+ * @returns {string|null}
+ */
+export function resolveMemoryDir({ github } = {}) {
+  if (
+    typeof process.env.MANDREL_MEMORY_DIR === 'string' &&
+    process.env.MANDREL_MEMORY_DIR.length > 0
+  ) {
+    return process.env.MANDREL_MEMORY_DIR;
+  }
+  const repo = github?.repo;
+  if (typeof repo !== 'string' || repo.length === 0) return null;
+  return path.join(os.homedir(), '.claude', 'projects', repo, 'memory');
+}
+
+/**
+ * Build the authoring context the host LLM (or the
+ * `epic-plan-spec-author` Skill) needs to write the PRD and Tech Spec.
+ *
+ * `docsContext` is bounded by the planning-context budget (Epic #817 Story 9):
+ * over-budget payloads downgrade to a summary representation with headings +
+ * bounded excerpts. Pass `{ fullContext: true }` (CLI: `--full-context`) to
+ * restore the unbounded full-body envelope. The Epic body itself is always
+ * subject to the same budget so a sprawling Epic narrative cannot bypass the
+ * cap by riding on top of `docsContext`.
+ */
+export async function buildAuthoringContext(
+  epicId,
+  provider,
+  settings = {},
+  opts = {},
+) {
+  const epic = await provider.getEpic(epicId);
+  if (!epic) {
+    throw new Error(`Epic #${epicId} not found.`);
+  }
+
+  const planningLimits = getLimits(settings).planningContext;
+  const { fullContext = false } = opts;
+
+  const docsContext = await buildDocsContext(settings, planningLimits, {
+    fullContext,
+  });
+
+  const epicBody = applyBudget(
+    [{ path: `epic-${epic.id}.md`, content: epic.body ?? '' }],
+    planningLimits,
+    { fullContext },
+  );
+
+  // Story #2094 Task #2103 — verify the project's BDD runner pending-tag
+  // support so the acceptance-spec body can record either the verified tag
+  // (features-first ordering) or "fallback: dependencies-first ordering"
+  // when no supported runner is present.
+  const bddRunner = await verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT });
+
+  // Story #2637 — index existing BDD scenarios so the Acceptance Engineer
+  // step can annotate planned ACs with matches from the project's
+  // `.feature` files. Empty array when the project has not adopted BDD;
+  // the scanner is best-effort and never throws on filesystem errors.
+  let bddScenarios = [];
+  try {
+    const featureRoots = resolveFeatureRoots({ cwd: PROJECT_ROOT });
+    bddScenarios = scanBddScenarios({ featureRoots });
+  } catch (err) {
+    Logger.warn(`[epic-plan-spec] BDD scenario scan skipped: ${err.message}`);
+  }
+
+  // Story #2557 — memory-freshness pre-flight runs BEFORE the prior-feedback
+  // fetch so the planner sees a deduplicated, currently-actionable memory
+  // store. The scanner is best-effort: missing memory dir or gh-CLI failures
+  // land in `memoryFreshness.errors[]` and never throw.
+  const githubCfg = opts.github ?? null;
+  const memoryDir = resolveMemoryDir({ github: githubCfg });
+  const memoryFreshness = await scanMemoryFreshness({
+    memoryDir,
+    owner: githubCfg?.owner,
+    repo: githubCfg?.repo,
+    projectRoot: PROJECT_ROOT,
+  });
+
+  // Story #2554 — surface open meta feedback issues to the planner so retro
+  // signals are routed into durable substrates rather than lost in chat.
+  // The fetcher is best-effort: missing owner/repo or gh-CLI failures land
+  // in `errors[]` and never throw.
+  const priorFeedback = await fetchPriorFeedback({
+    owner: githubCfg?.owner,
+    repo: githubCfg?.repo,
+  });
+
+  // Story #2634 — codebase snapshot. Generates a bounded structural view
+  // of the consumer repo (file tree + package surface + recent activity
+  // + optional export signatures at the `medium` tier) so the Architect
+  // can prefer real module names over doc-only ones. The check is
+  // best-effort: any git/filesystem error degrades to an empty snapshot
+  // so Phase 7 stays non-blocking.
+  let codebaseSnapshot = null;
+  try {
+    codebaseSnapshot = buildCodebaseSnapshot({
+      cwd: PROJECT_ROOT,
+      tier: settings?.planning?.codebaseSnapshot?.tier,
+      include: settings?.planning?.codebaseSnapshot?.include,
+      exclude: settings?.planning?.codebaseSnapshot?.exclude,
+      recentCommitWindow:
+        settings?.planning?.codebaseSnapshot?.recentCommitWindow,
+    });
+    // Story #3959 — when the skinny-tier cap drops files, the degradation
+    // used to be silent (only `truncated: true` on the envelope). Surface
+    // an operator-visible warning naming the dropped count and the two
+    // remedies so the spec author knows the snapshot is partial and can
+    // either opt into the richer `medium` tier or narrow `include`.
+    if (codebaseSnapshot?.truncated) {
+      const dropped = Math.max(
+        0,
+        (codebaseSnapshot.fileCount ?? 0) -
+          (codebaseSnapshot.files?.length ?? 0),
+      );
+      Logger.warn(
+        `[epic-plan-spec] codebase snapshot truncated: ${dropped} of ` +
+          `${codebaseSnapshot.fileCount} matched file(s) dropped from the ` +
+          `skinny-tier view. The spec-author context is partial. To restore ` +
+          `full grounding, set planning.codebaseSnapshot.tier: "medium" ` +
+          `and/or narrow planning.codebaseSnapshot.include in .agentrc.json.`,
+      );
+    }
+  } catch (err) {
+    Logger.warn(`[epic-plan-spec] codebase snapshot skipped: ${err.message}`);
+  }
+
+  // Epic #3865 — planning risk is no longer classified at emit-context
+  // time. The `epic-plan-spec-author` Skill authors the risk verdict
+  // (`risk-verdict.json`) as the fourth planning artifact, and the persist
+  // half derives the planningRisk envelope from it via deriveRiskEnvelope.
+
+  return {
+    epic: {
+      id: epic.id,
+      title: epic.title,
+      body: epicBody.mode === 'full' ? epic.body : null,
+      bodySummary: epicBody.mode === 'summary' ? epicBody.items[0] : null,
+      linkedIssues: epic.linkedIssues ?? { prd: null, techSpec: null },
+    },
+    docsContext,
+    codebaseSnapshot,
+    systemPrompts: {
+      prd: PRD_SYSTEM_PROMPT,
+      techSpec: TECH_SPEC_SYSTEM_PROMPT,
+      acceptanceSpec: ACCEPTANCE_SPEC_SYSTEM_PROMPT,
+    },
+    bddRunner,
+    bddScenarios,
+    memoryFreshness,
+    priorFeedback,
+  };
+}

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/cli-args.js

@@ -0,0 +1,48 @@
+/**
+ * cli-args.js — argv parsing + validation for the `epic-plan-spec` CLI.
+ *
+ * Extracted from `epic-plan-spec.js` (refs #3685) so the top-level entry
+ * stays a thin wire-up that scores at or above the maintainability floor;
+ * the option schema and the epic-id guards live here.
+ */
+
+import { parseArgs } from 'node:util';
+
+/**
+ * Parse and validate the `epic-plan-spec` CLI arguments.
+ *
+ * @param {string[]} [argv] Defaults to `process.argv.slice(2)`.
+ * @returns {{ values: Record<string, unknown>, epicId: number }}
+ * @throws {Error} when `--epic` is missing or not a number.
+ */
+export function parseEpicPlanSpecArgs(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      epic: { type: 'string' },
+      prd: { type: 'string' },
+      techspec: { type: 'string' },
+      'acceptance-spec': { type: 'string' },
+      'risk-verdict': { type: 'string' },
+      force: { type: 'boolean', default: false },
+      'force-review': { type: 'boolean', default: false },
+      steal: { type: 'boolean', default: false },
+      'emit-context': { type: 'boolean', default: false },
+      pretty: { type: 'boolean', default: false },
+      'full-context': { type: 'boolean', default: false },
+    },
+  });
+
+  if (!values.epic) {
+    throw new Error(
+      'Usage: epic-plan-spec.js --epic <EpicId> (--emit-context [--pretty] [--full-context] | --prd <file> --techspec <file> --risk-verdict <file> [--acceptance-spec <file>]) [--force]',
+    );
+  }
+
+  const epicId = Number.parseInt(values.epic, 10);
+  if (Number.isNaN(epicId)) {
+    throw new Error(`Invalid epic ID: "${values.epic}" — must be a number.`);
+  }
+
+  return { values, epicId };
+}