mandrel 2.56.0 → 2.58.0

package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js

@@ -0,0 +1,305 @@
+/**
+ * changes-repair.js — repair-before-judging for `changes[]` entries
+ * (Story #5312).
+ *
+ * The `{ path, assumption }` object shape is a deterministic, mechanically
+ * derivable formality. The validator already knew how to salvage a path from
+ * a plain-string bullet (`suggestPathEntryFix`) — then rejected the plan
+ * anyway and charged the author a full re-drafting round to paste that exact
+ * object back. Story #5005 made the same call for the verify-tier suffix and
+ * repaired it instead; the suffix is gone now, and the repair moves to the
+ * one formality left: this module applies the inference the validator
+ * trusts, so the dry-run rewrites and **reports** each repair rather than
+ * refusing on it.
+ *
+ * Two shapes are repaired, on both authoring surfaces (a structured object
+ * body's `changes[]` array and a serialized string body's `## Changes`
+ * section):
+ *
+ *   - a **plain-string bullet** (`src/app.js`, `` `src/app.js` ``,
+ *     `src/app.js — adds the route`) becomes `{ path, assumption }`, the
+ *     assumption resolved by probing the base branch — a path present at
+ *     base is a `refactors-existing`, an absent one a `creates`;
+ *   - a **trailing parenthetical** on a path (`src/app.js (new)`,
+ *     `` `src/app.js (creates)` — refactors-existing ``) is stripped; an
+ *     authored assumption is kept, an absent one probed as above.
+ *
+ * A string nothing path-shaped can be salvaged from is left untouched and
+ * still fails the body-shape validator — that is the one `changes[]` failure
+ * only the author can resolve.
+ *
+ * It lives beside the validator rather than inside it because the validator's
+ * job is to *judge*: mixing a mutating repair pass into a module of pure
+ * collectors muddies both. `persist-helpers.js#validateTickets` calls this
+ * first, then the validators.
+ *
+ * @module lib/orchestration/plan-persist/changes-repair
+ */
+
+import { FILE_ASSUMPTION_VALUES } from '../file-assumption-enum.js';
+
+/** The `## Changes` heading (either level the parser accepts). */
+const CHANGES_HEADING_RE = /^#{2,3}\s+Changes\s*$/i;
+
+/** Any heading — the end of the `## Changes` section. */
+const ANY_HEADING_RE = /^#{1,6}\s+\S/;
+
+/** A trailing `(…)` on a path token. */
+const TRAILING_PARENTHETICAL_RE = /\s*\([^)]*\)\s*$/;
+
+/** The humanized canonical bullet: `` `path` — assumption ``. */
+const HUMANIZED_RE = /^`([^`]+)`\s+—\s+(\S+)$/;
+
+// A token that looks like a file path / glob / module id: it carries a `/` or a
+// `.`-separated segment. Deliberately loose — a false positive only produces a
+// `{ path, assumption }` entry the base-branch probes then judge.
+const PATH_LIKE_RE = /^[\w@*-]*[/.][\w@./*-]+$/;
+
+/**
+ * Strip a trailing parenthetical from a path token, reporting whether one
+ * was present.
+ *
+ * @param {string} raw
+ * @returns {{ path: string, stripped: boolean }}
+ */
+function stripParenthetical(raw) {
+  const path = raw.replace(TRAILING_PARENTHETICAL_RE, '').trim();
+  return { path, stripped: path !== raw.trim() };
+}
+
+/**
+ * Salvage the path token from a plain-string bullet: drop a leading list
+ * marker, take the segment before any humanized ` — ` tail, peel quotes and
+ * backticks, strip a trailing parenthetical. Returns `null` when nothing
+ * path-shaped survives.
+ *
+ * @param {string} raw
+ * @returns {string|null}
+ */
+function salvagePath(raw) {
+  let s = raw
+    .trim()
+    .replace(/^[-*]\s+/, '')
+    .trim();
+  s = s.split('—')[0].trim();
+  s = s
+    .replace(/^[`'"]+/, '')
+    .replace(/[`'"]+$/, '')
+    .trim();
+  s = stripParenthetical(s).path;
+  return s !== '' && PATH_LIKE_RE.test(s) ? s : null;
+}
+
+/**
+ * Resolve the assumption for a path with none authored: present at base →
+ * `refactors-existing`, absent → `creates`.
+ *
+ * @param {string} path
+ * @param {(path: string) => boolean} existsAtBase
+ * @returns {'refactors-existing'|'creates'}
+ */
+function probeAssumption(path, existsAtBase) {
+  return existsAtBase(path) ? 'refactors-existing' : 'creates';
+}
+
+/**
+ * Repair one structured `changes[]` item. Returns the corrected entry and a
+ * repair record, or `null` when the item needs no repair (or cannot be
+ * repaired).
+ *
+ * @param {unknown} item
+ * @param {(path: string) => boolean} existsAtBase
+ * @returns {{ entry: { path: string, assumption: string }, repair: object }|null}
+ */
+function repairStructuredItem(item, existsAtBase) {
+  if (typeof item === 'string') {
+    const path = salvagePath(item);
+    if (path === null) return null;
+    const assumption = probeAssumption(path, existsAtBase);
+    return {
+      entry: { path, assumption },
+      repair: { from: item, path, assumption, reason: 'plain-string' },
+    };
+  }
+  if (item === null || typeof item !== 'object') return null;
+  if (typeof item.path !== 'string') return null;
+  const { path, stripped } = stripParenthetical(item.path);
+  const authored = FILE_ASSUMPTION_VALUES.includes(item.assumption);
+  if (!stripped && authored) return null;
+  if (path === '') return null;
+  const assumption = authored
+    ? item.assumption
+    : probeAssumption(path, existsAtBase);
+  return {
+    entry: { path, assumption },
+    repair: {
+      from: item.path,
+      path,
+      assumption,
+      reason: stripped ? 'trailing-parenthetical' : 'missing-assumption',
+    },
+  };
+}
+
+/**
+ * Repair one line of a serialized `## Changes` section. Returns the rewritten
+ * line and a repair record, or `null` when the line is already canonical or
+ * cannot be repaired.
+ *
+ * @param {string} line
+ * @param {(path: string) => boolean} existsAtBase
+ * @returns {{ line: string, repair: object }|null}
+ */
+function repairSectionLine(line, existsAtBase) {
+  const marker = line.match(/^(\s*[-*]\s+)/);
+  if (!marker) return null;
+  const content = line.slice(marker[1].length).trim();
+  if (content === '') return null;
+  const humanized = content.match(HUMANIZED_RE);
+  if (humanized) {
+    const { path, stripped } = stripParenthetical(humanized[1]);
+    const authored = FILE_ASSUMPTION_VALUES.includes(humanized[2]);
+    if (!stripped && authored) return null;
+    if (path === '') return null;
+    const assumption = authored
+      ? humanized[2]
+      : probeAssumption(path, existsAtBase);
+    return {
+      line: `${marker[1]}\`${path}\` — ${assumption}`,
+      repair: {
+        from: content,
+        path,
+        assumption,
+        reason: stripped ? 'trailing-parenthetical' : 'missing-assumption',
+      },
+    };
+  }
+  if (content.startsWith('{')) {
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      return null;
+    }
+    const repaired = repairStructuredItem(parsed, existsAtBase);
+    if (repaired === null) return null;
+    return {
+      line: `${marker[1]}\`${repaired.entry.path}\` — ${repaired.entry.assumption}`,
+      repair: repaired.repair,
+    };
+  }
+  const path = salvagePath(content);
+  if (path === null) return null;
+  const assumption = probeAssumption(path, existsAtBase);
+  return {
+    line: `${marker[1]}\`${path}\` — ${assumption}`,
+    repair: { from: content, path, assumption, reason: 'plain-string' },
+  };
+}
+
+/**
+ * Repair the `## Changes` section of a serialized body in place. Only lines
+ * between the heading and the next heading are touched; the rest of the
+ * body is byte-identical.
+ *
+ * @param {string} body
+ * @param {(path: string) => boolean} existsAtBase
+ * @returns {{ body: string, repairs: object[] }}
+ */
+function repairSerializedBody(body, existsAtBase) {
+  const lines = body.split('\n');
+  const repairs = [];
+  let inChanges = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (CHANGES_HEADING_RE.test(line.trim())) {
+      inChanges = true;
+      continue;
+    }
+    if (!inChanges) continue;
+    if (ANY_HEADING_RE.test(line) || line.trim().startsWith('---')) {
+      inChanges = false;
+      continue;
+    }
+    const repaired = repairSectionLine(line, existsAtBase);
+    if (repaired === null) continue;
+    lines[i] = repaired.line;
+    repairs.push(repaired.repair);
+  }
+  return { body: lines.join('\n'), repairs };
+}
+
+/**
+ * Repair the `changes[]` of one ticket, on whichever surface carries it.
+ *
+ * @param {object} ticket Mutated in place.
+ * @param {(path: string) => boolean} existsAtBase
+ * @returns {object[]} The repairs applied to this ticket.
+ */
+function repairTicket(ticket, existsAtBase) {
+  const body = ticket.body;
+  if (typeof body === 'string') {
+    const { body: next, repairs } = repairSerializedBody(body, existsAtBase);
+    if (repairs.length > 0) ticket.body = next;
+    return repairs;
+  }
+  const changes =
+    body && typeof body === 'object' && Array.isArray(body.changes)
+      ? body.changes
+      : Array.isArray(ticket.changes)
+        ? ticket.changes
+        : null;
+  if (changes === null) return [];
+  const repairs = [];
+  for (let i = 0; i < changes.length; i += 1) {
+    const repaired = repairStructuredItem(changes[i], existsAtBase);
+    if (repaired === null) continue;
+    changes[i] = repaired.entry;
+    repairs.push(repaired.repair);
+  }
+  return repairs;
+}
+
+/**
+ * Render one `changes[]` repair as the dry-run line the operator reads.
+ *
+ * The dry-run's repair list is mixed — an `acceptance[]` handle strip is
+ * reported on it too — but the dispatch across kinds lives in
+ * [`acceptance-handle-repair.js`](acceptance-handle-repair.js)`#renderRepair`,
+ * which delegates here for this kind. Each producer owns its own line.
+ *
+ * @param {{ slug: string, from: string, path: string, assumption: string, reason: string }} repair
+ * @returns {string}
+ */
+export function renderChangeRepair({ slug, from, path, assumption, reason }) {
+  const why =
+    reason === 'plain-string'
+      ? 'plain-string bullet'
+      : reason === 'trailing-parenthetical'
+        ? 'trailing parenthetical'
+        : 'missing assumption';
+  return `Story "${slug}": changes[] entry "${from}" (${why}) repaired to {"path":"${path}","assumption":"${assumption}"} by probing base.`;
+}
+
+/**
+ * Rewrite every repairable `changes[]` entry across the draft, probing the
+ * base branch for the assumption where none was authored. Mutates `tickets`
+ * in place (the persist pipeline threads this same array on to assembly)
+ * and returns the repairs, each tagged with the Story's slug. Total — a
+ * non-array argument and non-Story tickets are no-ops.
+ *
+ * @param {object[]} tickets
+ * @param {{ existsAtBase: (path: string) => boolean }} args
+ * @returns {Array<{ slug: string, from: string, path: string, assumption: string, reason: string }>}
+ */
+export function repairChangeEntries(tickets, { existsAtBase }) {
+  const repairs = [];
+  for (const ticket of Array.isArray(tickets) ? tickets : []) {
+    if (!ticket || ticket.type !== 'story') continue;
+    const slug = ticket.slug ?? ticket.title ?? '<unknown>';
+    for (const repair of repairTicket(ticket, existsAtBase)) {
+      repairs.push({ slug, ...repair });
+    }
+  }
+  return repairs;
+}

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

@@ -3,224 +3,192 @@
  *
  * 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.
+ *     which branch name the operator configured.
+ *
+ * The ref the probes read is resolved per checkout (`resolveProbeRef`): the
+ * local branch when it exists, else its `origin/` tracking ref (a PR
+ * checkout on CI has no local `main`), else nothing — a shallow checkout
+ * with no base at all skips the probes instead of reading every path as
+ * absent.
+ *   - `validateTickets(tickets, config, opts)` — normalises the authored
+ *     `acceptance[]` handles and repairs the mechanical `changes[]`
+ *     formalities against the base branch, then runs the cross-link,
+ *     freshness, and task-body validators in one pass.
+ *
+ * Story #5312 deleted the fan-out probe that lived here: the delete
+ * blast-radius count never refused a real plan, and the `git grep` it paid
+ * for on every persist bought a warning nobody acted on.
  *
  * @module lib/orchestration/plan-persist/persist-helpers
  */
 
-import posix from 'node:path/posix';
 import { gitSpawn } from '../../git-utils.js';
 import { validateTaskBodies } from '../task-body-validator.js';
 import { validateAndNormalizeTickets } from '../ticket-validator.js';
-import { resolveConflictPolicy } from '../ticket-validator-conflicts.js';
-import { normalizeVerifyTiers } from '../verify-tier-repair.js';
+import { normalizeAcceptanceHandles } from './acceptance-handle-repair.js';
+import { repairChangeEntries } from './changes-repair.js';
 
 /**
- * Extensions an import specifier may elide. Probed longest-path-first when
- * resolving an extensionless specifier back onto a concrete repo path.
+ * 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 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}
  */
-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, '\\$&');
+export function resolveBaseBranchRef(config) {
+  return config?.project?.baseBranch ?? config?.baseBranch ?? 'main';
 }
 
 /**
- * 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.
+ * Does `ref` name a commit in the repo at `cwd`?
+ *
+ * @param {string} ref
+ * @param {string} cwd
+ * @returns {boolean}
  */
-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);
+function refResolves(ref, cwd) {
+  return (
+    gitSpawn(cwd, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`)
+      .status === 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`.
+ * Resolve the configured base branch to a ref the footprint probes can read
+ * in this checkout, or `null` when none exists.
+ *
+ * A developer checkout carries a local `main`; a CI pull-request checkout
+ * (`actions/checkout` at the merge ref, detached) carries only
+ * `origin/main`; a shallow smoke checkout carries neither. Probing the
+ * bare branch name in the last two answers "absent" for every path, which
+ * turns each bare-path repair into a `creates` and every declared path into
+ * a stale reference. So: the local branch when it resolves, else its
+ * `origin/` tracking ref when that does, else `null` — the caller then
+ * skips the probes and says so, rather than reporting the tree as missing.
+ *
+ * @param {{ baseBranch: string, cwd?: string }} opts
+ * @returns {string|null}
  */
-function buildProbePattern(tails) {
-  const alt = tails.map(escapeRegExp).join('|');
-  return `(from|require|import)[[:space:]]*\\(?[[:space:]]*['"]([^'"]*/)?(${alt})['"]`;
+function resolveProbeRef({ baseBranch, cwd }) {
+  const repo = cwd ?? process.cwd();
+  const candidates = [baseBranch, `origin/${baseBranch}`];
+  return candidates.find((ref) => refResolves(ref, repo)) ?? null;
 }
 
 /**
- * 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.
+ * Default git probe: returns true when `path` exists at `ref` in the cwd repo.
+ * `git cat-file -e <ref>:<path>` is the standard low-cost existence check —
+ * the same probe the validator's own gates run, so the repair pass and the
+ * gates cannot disagree about what is at base.
+ *
+ * @param {{ baseBranchRef: string, path: string, cwd?: string }} opts
+ * @returns {boolean}
  */
-function specifierResolvesTo(importerPath, specifier, deletedPath) {
-  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return false;
-  const resolved = posix.normalize(
-    posix.join(posix.dirname(importerPath), specifier),
+function defaultGitRunner({ baseBranchRef, path, cwd }) {
+  const result = gitSpawn(
+    cwd ?? process.cwd(),
+    'cat-file',
+    '-e',
+    `${baseBranchRef}:${path}`,
   );
-  for (const ext of RESOLVABLE_EXTENSIONS) {
-    if (`${resolved}${ext}` === deletedPath) return true;
-    if (ext && `${resolved}/index${ext}` === deletedPath) return true;
-  }
-  return false;
+  return result.status === 0;
 }
 
 /**
- * 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).
+ * The `existsAtBase` predicate the `changes[]` repair pass probes with. With
+ * no base to read, a bare bullet is taken as the in-place edit it almost
+ * always is.
+ *
+ * @param {{ baseBranchRef: string|null, cwd?: string, gitRunner?: Function }} opts
+ * @returns {(path: string) => boolean}
  */
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_./-]+$/.test(value)) return value;
-  return `'${value.replaceAll("'", "'\\''")}'`;
+function makeExistsAtBase({ baseBranchRef, cwd, gitRunner }) {
+  if (baseBranchRef === null) return () => true;
+  const runner = gitRunner ?? defaultGitRunner;
+  return (path) => Boolean(runner({ baseBranchRef, path, cwd }));
 }
 
 /**
- * Parse one `git grep -n` output line of the form `<ref>:<path>:<lineno>:<text>`.
+ * The one warning a checkout with no readable base leaves on the dry-run.
+ *
+ * @param {string} baseBranch
+ * @param {string|null} baseBranchRef
+ * @returns {string[]}
  */
-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) };
+function probeSkipWarnings(baseBranch, baseBranchRef) {
+  if (baseBranchRef !== null) return [];
+  return [
+    `base branch ${baseBranch} does not resolve in this checkout (tried ` +
+      `${baseBranch} and origin/${baseBranch}) — footprint probes skipped; ` +
+      'the plan summary reports its references as ambiguous, not stale.',
+  ];
 }
 
 /**
- * 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 }}
+ * Attach non-enumerable bookkeeping to the validated array.
+ *
+ * @param {object[]} validated
+ * @param {Record<string, unknown>} extras
  */
-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 };
-  };
+function defineHidden(validated, extras) {
+  for (const [key, value] of Object.entries(extras)) {
+    Object.defineProperty(validated, key, {
+      value,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    });
+  }
 }
 
 /**
- * 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).
+ * Repair the mechanical `changes[]` formalities, then validate.
  *
- * The flat `config.baseBranch` fallback is retained for the legacy
- * `settings`-bag callers that pass `{ baseBranch, paths, planning }`.
+ * Repair before judging (Story #5312, the shape Story #5005 set for the
+ * verify tier): a plain-string bullet or a trailing parenthetical is
+ * rewritten into `{ path, assumption }` by probing the base branch, and
+ * each rewrite is reported on the returned array's `repairs` so the dry-run
+ * can print it. An entry nothing path-shaped can be salvaged from survives
+ * untouched and still hard-errors in `validateTaskBodies`.
  *
- * @param {object} [config] Resolved config, or a legacy settings bag.
- * @returns {string}
+ * @param {object[]} tickets Mutated in place.
+ * @param {object} config Resolved config.
+ * @param {{ cwd?: string, gitRunner?: Function }} [opts]
+ * @returns {object[] & { findings: object[], errors: string[], warnings: string[], normalizations: object[], repairs: object[], probeRef: string|null }}
  */
-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 baseBranch = resolveBaseBranchRef(config);
+  const baseBranchRef = resolveProbeRef({ baseBranch, cwd: opts.cwd });
+  const repairs = [
+    ...normalizeAcceptanceHandles(tickets),
+    ...repairChangeEntries(tickets, {
+      existsAtBase: makeExistsAtBase({
+        baseBranchRef,
+        cwd: opts.cwd,
+        gitRunner: opts.gitRunner,
+      }),
+    }),
+  ];
   const validated = validateAndNormalizeTickets(tickets, {
-    baseBranchRef,
-    conflictPolicy,
-    modelCapacity: opts.modelCapacity,
+    baseBranchRef: baseBranchRef ?? undefined,
+    gitRunner: opts.gitRunner,
     // 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,
   });
-  // Repair before judging (Story #5005): a `verify[]` entry whose tier the
-  // validator can already infer is auto-corrected rather than rejected, so a
-  // mechanically-fixable formality no longer costs a re-authoring round. An
-  // uninferable entry survives untouched and still hard-errors below.
-  normalizeVerifyTiers(validated);
+  validated.warnings.push(...probeSkipWarnings(baseBranch, baseBranchRef));
   validateTaskBodies(validated);
+  defineHidden(validated, { repairs, probeRef: baseBranchRef });
   return validated;
 }