mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/plan-critic-conditions.js

@@ -1,5 +1,5 @@
 /**
- * plan-critic-conditions.js — risk/size-conditional dispatch decisions for
+ * plan-critic-conditions.js — size/heuristic-conditional dispatch decisions for
  * the /plan author-step critics (Epic #4474 PR6, design §4).
  *
  * The collapsed plan flow keeps the consolidation (8.3) and pre-mortem
@@ -18,10 +18,12 @@
  *     small draft is NOT a confirmed divergence — it skips, because a
  *     ≤-threshold draft is small enough for gate #2's single-view review
  *     to catch a distorted shape without a dedicated sub-agent.
- *   - **Pre-mortem (8.5)**: dispatch when the risk verdict's overall level
- *     is `high`, OR the ticket count is at least half of `maxTickets`, OR
- *     any configured `planning.riskHeuristics` phrase matches the plan
- *     text (case-insensitive substring).
+ *   - **Pre-mortem (8.5)**: dispatch when the ticket count is at least half
+ *     of `maxTickets`, OR any configured `planning.riskHeuristics` phrase
+ *     matches the plan text (case-insensitive substring). Story #4542 removed
+ *     its third condition — the authored risk verdict's overall level — along
+ *     with the verdict itself; both surviving conditions read the plan's own
+ *     observable text and shape rather than a self-assessment.
  *
  * Under-firing risk (design PR6 note): the persist validators are
  * unchanged hard gates and G2's cohort re-measures plan quality; every
@@ -34,7 +36,6 @@
  */
 
 import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';
-import { deriveRiskEnvelope } from './planning-risk.js';
 
 /**
  * Draft-story count above which the consolidation critic fires even
@@ -105,14 +106,10 @@ export function evaluateConsolidationDispatch({ draftStories, specText }) {
 }
 
 /**
- * Decide the 8.5 pre-mortem dispatch: high risk, or size ≥ ½ budget, or a
- * risk-heuristic phrase match.
+ * Decide the 8.5 pre-mortem dispatch: size ≥ ½ budget, or a risk-heuristic
+ * phrase match.
  *
  * @param {object} input
- * @param {import('./planning-risk.js').RiskVerdict} input.riskVerdict -
- *   The authored `risk-verdict.json` payload; the overall level is derived
- *   deterministically from its axes (`deriveRiskEnvelope`), never trusted
- *   as a free-standing field.
  * @param {number} input.ticketCount - Draft ticket count (0 in the
  *   single-delivery shape — no tickets exist).
  * @param {number} input.maxTickets - The reviewability budget
@@ -120,11 +117,10 @@ export function evaluateConsolidationDispatch({ draftStories, specText }) {
  * @param {string[]} [input.riskHeuristics] - `planning.riskHeuristics`
  *   phrases from the resolved config.
  * @param {string} [input.planText] - Concatenated plan text the heuristics
- *   match against (tech spec + serialized tickets + risk summary).
+ *   match against (tech spec + serialized tickets).
  * @returns {CriticDispatchDecision}
  */
 export function evaluatePremortemDispatch({
-  riskVerdict,
   ticketCount,
   maxTickets,
   riskHeuristics = [],
@@ -137,13 +133,6 @@ export function evaluatePremortemDispatch({
   }
   const reasons = [];
 
-  const { overallLevel } = deriveRiskEnvelope(riskVerdict);
-  if (overallLevel === 'high') {
-    reasons.push(
-      'Risk verdict overall level is high — predicted-rework findings are worth a fresh-context pass.',
-    );
-  }
-
   const count = Number.isInteger(ticketCount) ? ticketCount : 0;
   if (count * 2 >= maxTickets) {
     reasons.push(
@@ -172,7 +161,7 @@ export function evaluatePremortemDispatch({
     critic: 'pre-mortem',
     dispatch: false,
     reasons: [
-      `Overall risk is ${overallLevel} (not high), ticket count ${count} is under half the budget (maxTickets ${maxTickets}), and no planning.riskHeuristics phrase matches the plan text.`,
+      `Ticket count ${count} is under half the budget (maxTickets ${maxTickets}) and no planning.riskHeuristics phrase matches the plan text.`,
     ],
   };
 }

package/.agents/scripts/lib/orchestration/plan-critics-evaluate.js

@@ -36,7 +36,7 @@ function resolveRiskHeuristics(config = {}) {
   if (Array.isArray(config.planning?.riskHeuristics)) {
     return config.planning.riskHeuristics;
   }
-  return config.agentSettings?.planning?.riskHeuristics || [];
+  return [];
 }
 
 /**
@@ -47,13 +47,12 @@ function resolveRiskHeuristics(config = {}) {
  *   - Consolidation: skipped outright when `tickets` is null/absent (the
  *     single-delivery shape authors no draft tickets); otherwise the
  *     deterministic precondition + size/divergence conditions.
- *   - Pre-mortem: risk verdict overall level high, OR ticket count at least
- *     half `maxTickets`, OR any `planning.riskHeuristics` phrase matching
- *     the plan text.
+ *   - Pre-mortem: ticket count at least half `maxTickets`, OR any
+ *     `planning.riskHeuristics` phrase matching the plan text. Story #4542
+ *     retired its authored-risk-level condition with the verdict itself.
  *
  * @param {{
  *   techSpecContent: string,
- *   riskVerdict: { summary?: string },
  *   tickets?: Array<object>|null,
  *   config?: object,
  * }} args
@@ -64,7 +63,6 @@ function resolveRiskHeuristics(config = {}) {
  */
 export function evaluatePlanCritics({
   techSpecContent,
-  riskVerdict,
   tickets = null,
   config = {},
 }) {
@@ -84,14 +82,12 @@ export function evaluatePlanCritics({
         });
 
   const premortem = evaluatePremortemDispatch({
-    riskVerdict,
     ticketCount: ticketList?.length ?? 0,
     maxTickets: getLimits(config).maxTickets,
     riskHeuristics: resolveRiskHeuristics(config),
     planText: [
       techSpecContent ?? '',
       ticketList ? JSON.stringify(ticketList) : '',
-      riskVerdict?.summary ?? '',
     ].join('\n'),
   });
 

package/.agents/scripts/lib/orchestration/plan-metrics.js

@@ -5,7 +5,7 @@
  * phase is removed, every plan CLI invocation stamps an entry/exit record so
  * the current 12-phase baseline is captured on disk. Each record is one
  * newline-terminated JSON line appended to
- * `temp/epic-<id>/plan-metrics.json` (per-Epic plan CLIs) or
+ * `temp/run-<id>/plan-metrics.json` (per-Epic plan CLIs) or
  * `temp/standalone/plan-metrics.json` (the standalone `story-plan.js` path
  * and Epic-less healthcheck runs — same standalone routing the friction
  * ledger uses).
@@ -61,7 +61,7 @@ import path from 'node:path';
 
 import {
   anchorTempRoot,
-  epicArtifactPath,
+  runArtifactPath,
   tempRootFrom,
 } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
@@ -95,7 +95,7 @@ export function planMetricsPath(epicId, config) {
       PLAN_METRICS_BASENAME,
     );
   }
-  return epicArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
+  return runArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
 }
 
 /**
@@ -314,7 +314,8 @@ export async function readPlanMetrics(epicId, config) {
 
 /**
  * Roll a read ledger up into the compact summary surfaced by the persist
- * summary and `analyze-execution.js`. Returns `null` when there is nothing
+ * summary. (Story #4545 deleted its second consumer, `analyze-execution.js`,
+ * with the execution-analysis surface.) Returns `null` when there is nothing
  * to summarize (missing ledger or zero parseable entries).
  *
  * Critic-skip records (kind: 'critic-skip') are counted separately from
@@ -322,7 +323,15 @@ export async function readPlanMetrics(epicId, config) {
  * them down, so the skip-audit trail is visible in the persist summary
  * without inflating the turns-per-plan proxy.
  *
+ * Pass `opts.since` (an ISO-8601 instant) to scope the roll-up to one plan
+ * run (Story #4541). The Epic-less ledger at `temp/standalone/` is shared by
+ * every plan the repo has ever run, so an unfiltered summary reported
+ * lifetime totals under a line the reader takes to describe the invocation
+ * in front of them. Records are timestamped `startedAt` (invocations) or
+ * `at` (critic skips); either at-or-after `since` is in scope.
+ *
  * @param {{ entries: object[], malformedLines?: number }} ledger
+ * @param {{ since?: string|null }} [opts]
  * @returns {{
  *   invocations: number,
  *   failures: number,
@@ -337,8 +346,31 @@ export async function readPlanMetrics(epicId, config) {
  *   malformedLines: number,
  * }|null}
  */
-export function summarizePlanMetrics(ledger) {
-  const entries = ledger?.entries ?? [];
+/**
+ * Timestamp a ledger record is ordered by: `startedAt` for invocation
+ * records, `at` for critic-skip records.
+ *
+ * @param {object} entry
+ * @returns {string|null}
+ */
+function recordTimestamp(entry) {
+  const stamp =
+    entry?.kind === PLAN_METRICS_KIND_CRITIC_SKIP ? entry.at : entry.startedAt;
+  return typeof stamp === 'string' ? stamp : null;
+}
+
+export function summarizePlanMetrics(ledger, opts = {}) {
+  const all = ledger?.entries ?? [];
+  const since = typeof opts.since === 'string' ? opts.since : null;
+  // ISO-8601 UTC strings sort lexicographically in time order, so a string
+  // compare is a correct (and allocation-free) instant compare here.
+  const entries =
+    since === null
+      ? all
+      : all.filter((e) => {
+          const stamp = recordTimestamp(e);
+          return stamp !== null && stamp >= since;
+        });
   if (entries.length === 0) return null;
   const byCli = {};
   const byMode = {};

package/.agents/scripts/lib/orchestration/plan-navigation.js

@@ -0,0 +1,92 @@
+/**
+ * plan-navigation.js — shared navigability helpers for the persist-side
+ * draft reachability check (`plan-reachability.js`).
+ *
+ * Extracted from the retired `epic-plan-healthcheck.js` so the live
+ * draft-ticket scan owns its own mechanics without pulling in the
+ * deleted post-plan healthcheck CLI.
+ */
+
+/**
+ * Resolve the navigation config that drives the reachability check.
+ *
+ * The check is opt-in: a consumer that has not configured
+ * `planning.navigation.routeGlobs` gets a silent no-op. The nav-registry
+ * token list is what a route-adding Story is expected to reference
+ * somewhere in its body or `## Acceptance` section.
+ *
+ * @param {object} config Resolved `.agentrc.json`.
+ * @returns {{ routeGlobs: string[], navRegistry: string[] }}
+ */
+export function resolveNavConfig(config) {
+  const nav = config?.planning?.navigation ?? {};
+  const toList = (v) =>
+    (Array.isArray(v) ? v : v == null ? [] : [v])
+      .filter((s) => typeof s === 'string' && s.trim().length > 0)
+      .map((s) => s.trim());
+  return {
+    routeGlobs: toList(nav.routeGlobs),
+    navRegistry: toList(nav.navRegistry),
+  };
+}
+
+/**
+ * Translate a route glob (`pages/**`, `app/**\/route.ts`) into a RegExp that
+ * matches a path string. Supports `**` (any depth, including `/`), `*` (any
+ * run of non-separator chars), and `?` (single non-separator char). All other
+ * characters are matched literally.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  // Collapse adjacent `**` segments before compiling. `**/**` and `***` both
+  // mean "any depth", but compiling them literally emits adjacent `.*` runs
+  // (`.*/.*` / `.*.*`) that backtrack catastrophically on a long non-matching
+  // path. Collapsing to a single `**` preserves semantics and keeps the
+  // matcher linear (ReDoS hardening).
+  const normalized = glob
+    .replace(/\*\*(?:\/\*\*)+/g, '**')
+    .replace(/\*{3,}/g, '**');
+  let re = '';
+  for (let i = 0; i < normalized.length; i++) {
+    const ch = normalized[i];
+    if (ch === '*') {
+      if (normalized[i + 1] === '*') {
+        re += '.*';
+        i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Extract the candidate route-touching paths a Story declares. Reads the
+ * `## Changes` block (the decompose-author emits one `{"path":...}` JSON
+ * object per bullet) and falls back to any bare `` `path/like/this` ``
+ * inline-code spans in the body.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+export function extractStoryPaths(body) {
+  if (typeof body !== 'string' || body.length === 0) return [];
+  const paths = new Set();
+  // `{"path":"pages/foo.tsx", ...}` change descriptors.
+  for (const m of body.matchAll(/"path"\s*:\s*"([^"]+)"/g)) {
+    paths.add(m[1]);
+  }
+  // Inline-code spans that look like a path (contain a slash or a dotted ext).
+  for (const m of body.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (/[/.]/.test(token) && !token.includes(' ')) paths.add(token);
+  }
+  return [...paths];
+}

package/.agents/scripts/lib/orchestration/plan-persist/fan-out-gate.js

@@ -0,0 +1,71 @@
+/**
+ * Fan-out / soft-conflict gates used by plan-persist (extracted from the
+ * retired epic-plan-decompose persist phase in Stage 5).
+ *
+ * @module lib/orchestration/plan-persist/fan-out-gate
+ */
+
+import { Logger } from '../../Logger.js';
+import {
+  renderFanOutEvidence,
+  renderFanOutRemedy,
+  renderHardConflictError,
+} from '../ticket-validator-conflicts.js';
+
+/**
+ * @param {object[]} findings
+ * @param {boolean} allowLargeFanOut
+ * @param {string} [tag]
+ */
+export function enforceFanOutGate(
+  findings,
+  allowLargeFanOut,
+  tag = 'plan-persist',
+) {
+  const fanOut = (findings ?? []).filter((f) => f.kind === 'fan-out-warning');
+  if (fanOut.length === 0) return;
+  if (allowLargeFanOut) {
+    for (const f of fanOut) {
+      Logger.warn(
+        `[${tag}] Persisting a large-fan-out deletion: ` +
+          `Story "${f.storySlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
+          `importer(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.` +
+          renderFanOutEvidence(f),
+      );
+    }
+    return;
+  }
+  const lines = fanOut
+    .map(
+      (f) =>
+        `  - Story "${f.storySlug}" deletes "${f.path}" — ` +
+        `${f.callSiteCount} importer(s) (threshold ${f.threshold})` +
+        renderFanOutEvidence(f),
+    )
+    .join('\n');
+  // Each finding carries its own remedy — a rename-shaped deletion has no
+  // subsystems to split across, so a blanket "split it up" footer would be
+  // wrong advice for it (Story #4547).
+  const remedies = [...new Set(fanOut.map((f) => renderFanOutRemedy(f)))];
+  throw new Error(
+    `[${tag}] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
+      remedies.join('\n\n'),
+  );
+}
+
+/**
+ * @param {object[]} findings
+ * @param {string} [tag]
+ */
+export function surfaceSoftConflictFindings(findings, tag = 'plan-persist') {
+  const soft = (findings ?? []).filter(
+    (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
+  );
+  if (soft.length === 0) return;
+  Logger.warn(
+    `[${tag}] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
+  );
+  for (const finding of soft) {
+    Logger.warn(`[${tag}] soft conflict: ${renderHardConflictError(finding)}`);
+  }
+}

package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js

@@ -0,0 +1,245 @@
+/**
+ * persist-helpers.js — pure helper surface for the flat Story `/plan` persist.
+ *
+ * Exports:
+ *   - `resolveBaseBranchRef(config)` — the one place the persist gates learn
+ *     which ref to probe.
+ *   - `validateTickets(tickets, config)` — runs the cross-link, model-capacity,
+ *     freshness, and task-body validators in one pass. Capacity settings are
+ *     explicit inputs so the validator and decomposer share one live delivery
+ *     envelope instead of silently falling back to framework defaults.
+ *   - `makeDefaultFanOutCounter({ baseBranchRef, cwd, git })` — production
+ *     fan-out probe used by the conflict policy.
+ *
+ * @module lib/orchestration/plan-persist/persist-helpers
+ */
+
+import posix from 'node:path/posix';
+import { resolveListValue } from '../../config/shared.js';
+import { gitSpawn } from '../../git-utils.js';
+import { validateTaskBodies } from '../task-body-validator.js';
+import { validateAndNormalizeTickets } from '../ticket-validator.js';
+import { DEFAULT_REGISTRY_PATTERNS } from '../ticket-validator-conflicts.js';
+
+/**
+ * Extensions an import specifier may elide. Probed longest-path-first when
+ * resolving an extensionless specifier back onto a concrete repo path.
+ */
+const RESOLVABLE_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.json'];
+
+/** Every quoted string on a candidate line — the specifier lives in one. */
+const QUOTED_RE = /['"]([^'"\n]+)['"]/g;
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The specifier tails an importer of `path` could plausibly write as the
+ * final segment of its quoted specifier: the basename, the basename minus
+ * its extension, and — for a directory-index module — the directory name
+ * (`./foo` resolving to `foo/index.js`).
+ *
+ * This is a *candidate* net only. It is deliberately generous because the
+ * resolution pass below re-checks every hit against the real path; a tail
+ * that over-matches costs one extra resolve, a tail that under-matches
+ * loses a genuine importer.
+ */
+function specifierTails(path) {
+  const base = posix.basename(path);
+  const ext = posix.extname(base);
+  const stem = ext ? base.slice(0, -ext.length) : base;
+  const tails = new Set([base, stem]);
+  if (stem === 'index') {
+    const dir = posix.basename(posix.dirname(path));
+    if (dir && dir !== '.') tails.add(dir);
+  }
+  return [...tails].filter((t) => t.length > 0);
+}
+
+/**
+ * ERE matching a line that carries an `import` / `export … from` /
+ * `require(` / dynamic `import(` whose quoted specifier *ends* at one of
+ * `tails`. The `(^|/)`-equivalent guard (`([^'"]*\/)?`) is what keeps
+ * `notification.js` from matching `push-notification.js`.
+ */
+function buildProbePattern(tails) {
+  const alt = tails.map(escapeRegExp).join('|');
+  return `(from|require|import)[[:space:]]*\\(?[[:space:]]*['"]([^'"]*/)?(${alt})['"]`;
+}
+
+/**
+ * Resolve a relative specifier written in `importerPath` back onto a repo
+ * path and report whether it names `deletedPath`.
+ *
+ * **Known boundary:** only relative (`./`, `../`) specifiers resolve. A
+ * consumer repo that imports its own modules through bare specifiers or a
+ * path alias (`#lib/x`, `@app/x`, a `tsconfig` `paths` entry) would
+ * under-count, because resolving those needs the resolver config this probe
+ * deliberately does not read. Mandrel's own internal imports are all
+ * relative. Under-counting is the *quiet* failure direction — it argues for
+ * a deletion rather than against one — so if alias-importing consumers
+ * appear, this is the place to teach the probe their resolver.
+ */
+function specifierResolvesTo(importerPath, specifier, deletedPath) {
+  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return false;
+  const resolved = posix.normalize(
+    posix.join(posix.dirname(importerPath), specifier),
+  );
+  for (const ext of RESOLVABLE_EXTENSIONS) {
+    if (`${resolved}${ext}` === deletedPath) return true;
+    if (ext && `${resolved}/index${ext}` === deletedPath) return true;
+  }
+  return false;
+}
+
+/**
+ * Quote one argv entry so the reported probe is **runnable as emitted**.
+ *
+ * The probe is the operator's route to checking the number, so it has to
+ * survive a paste into a shell. Unquoted, the ERE's `(`, `|`, `[[:space:]]`
+ * and `?` are glob/grouping metacharacters: zsh fails the paste with
+ * `no matches found` *and exits 0*, which reads as "zero importers" — the
+ * gate's own audit trail would then argue for the deletion it is meant to
+ * question (Story #4547).
+ */
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Parse one `git grep -n` output line of the form `<ref>:<path>:<lineno>:<text>`.
+ */
+function parseGrepLine(line, baseBranchRef) {
+  const prefix = `${baseBranchRef}:`;
+  if (!line.startsWith(prefix)) return null;
+  const rest = line.slice(prefix.length);
+  const pathEnd = rest.indexOf(':');
+  if (pathEnd === -1) return null;
+  const path = rest.slice(0, pathEnd);
+  const afterPath = rest.slice(pathEnd + 1);
+  const lineEnd = afterPath.indexOf(':');
+  if (lineEnd === -1) return null;
+  return { path, text: afterPath.slice(lineEnd + 1) };
+}
+
+/**
+ * Default fan-out probe — resolves the *importers* of the deleted module at
+ * `baseBranchRef`, and reports the referencing files alongside the exact
+ * probe that produced them.
+ *
+ * Two-stage, because accuracy and cost pull in opposite directions:
+ *
+ *   1. `git grep -n -E` narrows the tree to lines whose quoted import /
+ *      require specifier could name the module (final-segment match).
+ *   2. Each candidate specifier is resolved against its own importer's
+ *      directory and compared to the deleted path. Only a real resolution
+ *      counts.
+ *
+ * The predecessor (Story #2962) grepped the basename stem as a bare word
+ * across the whole tree, so a module named `notification` or `options`
+ * reported dozens of call sites drawn from prose, schemas, and unrelated
+ * modules — and the gate that fired on that number told the operator to
+ * split a migration that did not exist. It also returned 0 without probing
+ * for any stem under three characters, under-reporting in silence. Both are
+ * gone: coupling is measured by resolution, not vocabulary (Story #4547).
+ *
+ * @returns {(arg: { path: string }) => { count: number, files: string[], probe: string }}
+ */
+export function makeDefaultFanOutCounter({ baseBranchRef, cwd, git } = {}) {
+  const spawn = git?.gitSpawn ?? gitSpawn;
+  return ({ path }) => {
+    const tails = specifierTails(path);
+    const pattern = buildProbePattern(tails);
+    const args = ['grep', '-n', '-E', '--full-name', pattern, baseBranchRef];
+    const probe = `git ${args.map(shellQuote).join(' ')}`;
+    const result = spawn(cwd ?? process.cwd(), ...args);
+    // git grep exits 1 on "no matches" — an empty result, not a failure.
+    if (result.status !== 0) return { count: 0, files: [], probe };
+    const files = new Set();
+    for (const line of result.stdout.split('\n')) {
+      if (line.trim().length === 0) continue;
+      const hit = parseGrepLine(line, baseBranchRef);
+      // The deleted module's own self-references are not call sites.
+      if (!hit || hit.path === path) continue;
+      for (const match of hit.text.matchAll(QUOTED_RE)) {
+        if (specifierResolvesTo(hit.path, match[1], path)) {
+          files.add(hit.path);
+          break;
+        }
+      }
+    }
+    const sorted = [...files].sort();
+    return { count: sorted.length, files: sorted, probe };
+  };
+}
+
+/**
+ * Resolve the cross-Story conflict-finding policy from `_config.planning`.
+ */
+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(
+      DEFAULT_REGISTRY_PATTERNS,
+      planning.crossCuttingRegistries,
+    );
+  }
+  return policy;
+}
+
+/**
+ * Resolve the ref the persist gates probe against.
+ *
+ * The canonical resolved config carries the base branch at
+ * `project.baseBranch` (`lib/config-resolver.js` defaults it to `main`).
+ * This helper used to read `config.baseBranch` — a key the resolver never
+ * produces — so every freshness / file-assumption / fan-out probe silently
+ * targeted the literal `main` regardless of configuration. Benign in a repo
+ * whose base branch *is* `main`; wrong for any consumer that configured
+ * something else (Story #4541).
+ *
+ * The flat `config.baseBranch` fallback is retained for the legacy
+ * `settings`-bag callers that pass `{ baseBranch, paths, planning }`.
+ *
+ * @param {object} [config] Resolved config, or a legacy settings bag.
+ * @returns {string}
+ */
+export function resolveBaseBranchRef(config) {
+  return config?.project?.baseBranch ?? config?.baseBranch ?? 'main';
+}
+
+export function validateTickets(tickets, config, opts = {}) {
+  const baseBranchRef = resolveBaseBranchRef(config);
+  const conflictPolicy = resolveConflictPolicy(config);
+  if (typeof opts.fanOutCounter === 'function') {
+    conflictPolicy.fanOutCounter = opts.fanOutCounter;
+  } else {
+    conflictPolicy.fanOutCounter = makeDefaultFanOutCounter({
+      baseBranchRef,
+      cwd: opts.cwd,
+    });
+  }
+  const validated = validateAndNormalizeTickets(tickets, {
+    baseBranchRef,
+    conflictPolicy,
+    modelCapacity: opts.modelCapacity,
+    // Thread the repo cwd into the AC-freshness / file-assumption git
+    // probes (#4474 PR7) — without it they silently ran against
+    // process.cwd(), which is only the repo root by coincidence.
+    cwd: opts.cwd,
+  });
+  validateTaskBodies(validated);
+  return validated;
+}