mandrel 2.56.0 → 2.57.0

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

@@ -1,124 +1,50 @@
 /**
- * plan-critic-conditions.js — size/heuristic-conditional dispatch decisions for
- * the /mandrel-plan author-step critics (Epic #4474 PR6, design §4).
+ * plan-critic-conditions.js — the pre-mortem critic's dispatch decision for
+ * the `/mandrel-plan` critic CLI (Epic #4474 PR6, design §4; narrowed to one
+ * arm by Story #5312).
  *
- * The collapsed plan flow keeps the consolidation and pre-mortem critics as
- * fresh-context sub-agent dispatches, but makes each dispatch
- * **conditional** instead of unconditional — the dominant plan cost is
- * turns × standing context, and an unconditional critic pays a full
- * sub-agent spawn even when it provably has nothing to find. This module
- * computes those decisions deterministically so the workflow never judges
- * its own dispatch conditions:
+ * The critic is a fresh-context sub-agent dispatch, and the dispatch is
+ * **conditional**: the dominant plan cost is turns × standing context, and an
+ * unconditional critic pays a full sub-agent spawn even when it provably has
+ * nothing to find. This module computes the decision deterministically so
+ * the workflow never judges its own dispatch condition.
  *
- *   - **Consolidation**: dispatch only when the existing
- *     `evaluateConsolidationPrecondition` gate says `dispatch: true` AND
- *     (the draft has more than `CONSOLIDATION_STORY_THRESHOLD` stories OR
- *     the precondition confirmed a divergence from the Delivery Slicing
- *     table). A fail-open precondition (missing/unparseable table) on a
- *     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**: dispatch when the ticket count is at least half
- *     of `maxTickets`, OR any configured `planning.riskHeuristics` phrase
- *     matches the plan text (case-insensitive substring), OR the
- *     **external-dependency probe** (Story #4700) finds an out-of-repo marker
- *     in the plan text. Story #4542 removed the authored-risk-verdict condition
- *     along with the verdict itself; every surviving condition reads the plan's
- *     own observable text and shape rather than a self-assessment.
- *
- * The external-dependency probe (Story #4700) is what gives the default N=1
- * path a cheap viability check: on that path the size condition is unreachable
- * (`count*2 >= maxTickets` never holds at one ticket) and a repo whose resolved
- * `planning.riskHeuristics` is empty has no phrase to match, so a plan-time
- * discoverable blocker — a scoped package the plan names that no manifest
- * declares, a cross-repo reference, an external service prerequisite — reached
+ * One trigger survives: the **external-dependency probe** (Story #4700),
+ * which finds an out-of-repo marker in the plan text — a scoped package the
+ * plan names that no manifest declares, a cross-repo reference, an external
+ * service prerequisite — so a plan-time discoverable blocker does not reach
  * delivery unquestioned (the swarm-os #757 shape). The probe is deliberately
- * **conservative**: it matches only explicit markers (npm scoped-package specs,
- * `github.com/<owner>/<repo>` URLs, prerequisite-keyword-anchored endpoints),
- * never NLP guesswork, so a plan with no such marker dispatches exactly as it
- * did before.
+ * **conservative**: it matches only explicit markers (npm scoped-package
+ * specs, `github.com/<owner>/<repo>` URLs, prerequisite-keyword-anchored
+ * endpoints), never NLP guesswork.
+ *
+ * Story #5312 deleted the two triggers that sat beside it — the ticket count
+ * reaching half a `maxTickets` budget, and a `planning.riskHeuristics` phrase
+ * matching the plan text — with the constants they read. The count trigger
+ * was unreachable at the default N=1; the phrase list was empty in every
+ * consumer that resolved it. The consolidation critic went with them: its
+ * one deterministic input was a `## Delivery Slicing` table no Story carries.
  *
- * Under-firing risk (design PR6 note): the persist validators are
- * unchanged hard gates and G2's cohort re-measures plan quality; every
- * skip decision this module produces is logged to the plan-metrics ledger
- * (`appendCriticSkip`) by the caller so under-firing is auditable.
+ * Under-firing risk (design PR6 note): the persist validators are unchanged
+ * hard gates; every skip decision this module produces is logged to the
+ * plan-metrics ledger (`appendCriticSkip`) by the caller so under-firing is
+ * auditable.
  *
  * Pure, synchronous, no I/O. The single caller is `plan-critics-evaluate.js`,
- * driven by the `plan-critics.js` CLI that `/mandrel-plan` runs between Author and
- * Persist (Story #4592); the CLI owns reading the authored artifacts and the
- * resolved config.
- */
-
-import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';
-
-/**
- * Draft-story count above which the consolidation critic fires even
- * without a confirmed slicing divergence (#4474 PR6: "> 5 stories").
+ * driven by the `plan-critics.js` CLI the operator runs between Author and
+ * Persist when they want the critic; the CLI owns reading the authored
+ * artifacts and the resolved config.
  */
-export const CONSOLIDATION_STORY_THRESHOLD = 5;
 
 /**
  * @typedef {Object} CriticDispatchDecision
- * @property {'consolidation'|'pre-mortem'} critic
+ * @property {'pre-mortem'} critic
  * @property {boolean} dispatch
  * @property {string[]} reasons Why the critic fires — or why it is safe to
  *   skip. Never empty: a skip's reasons are the audit trail the
  *   plan-metrics ledger records.
  */
 
-/**
- * Decide the consolidation dispatch: precondition AND size/divergence.
- *
- * @param {object} input
- * @param {object[]} input.draftStories - The draft `tickets.json` array
- *   (raw Story objects with top-level `slug` / `depends_on` / `body`).
- * @param {string} input.specText - The text carrying the `## Delivery
- *   Slicing` table. At author time this is the authored `techspec.md`
- *   content (the Epic body carries the same folded section post-persist).
- * @returns {CriticDispatchDecision}
- */
-export function evaluateConsolidationDispatch({ draftStories, specText }) {
-  const precondition = evaluateConsolidationPrecondition({
-    draftStories,
-    epicBody: specText,
-  });
-
-  if (!precondition.dispatch) {
-    return {
-      critic: 'consolidation',
-      dispatch: false,
-      reasons: precondition.reasons,
-    };
-  }
-
-  const storyCount = draftStories.length;
-  const oversized = storyCount > CONSOLIDATION_STORY_THRESHOLD;
-  const diverges = precondition.cause === 'divergence';
-
-  if (!oversized && !diverges) {
-    return {
-      critic: 'consolidation',
-      dispatch: false,
-      reasons: [
-        `Draft has ${storyCount} story(ies) (≤ ${CONSOLIDATION_STORY_THRESHOLD}) and no confirmed Delivery Slicing divergence — gate #2's single-view review covers a draft this small.`,
-        ...precondition.reasons,
-      ],
-    };
-  }
-
-  const reasons = [];
-  if (diverges) reasons.push(...precondition.reasons);
-  if (oversized) {
-    reasons.push(
-      `Draft has ${storyCount} stories (> ${CONSOLIDATION_STORY_THRESHOLD}) — large enough that a distorted shape can hide from the gate #2 single view.`,
-    );
-  }
-  if (!diverges && precondition.cause === 'fail-open') {
-    reasons.push(...precondition.reasons);
-  }
-  return { critic: 'consolidation', dispatch: true, reasons };
-}
-
 /**
  * Explicit npm scoped-package marker: `@scope/name`. Requires the leading `@`
  * and an interior `/`, so bare GitHub handles (`@dsj1984`) and the
@@ -215,8 +141,8 @@ function matchExternalServicePrereqs(planText) {
 /**
  * The external-dependency probe (Story #4700): a conservative, marker-only
  * scan of the draft plan text for artifacts outside the current repo that the
- * plan depends on. A match is the pre-mortem's third dispatch condition; a
- * no-match plan behaves exactly as it did before this probe existed.
+ * plan depends on. A match is the pre-mortem's dispatch condition; a no-match
+ * plan skips the critic.
  *
  * @param {object} input
  * @param {string} [input.planText] - Concatenated plan text (tech spec +
@@ -262,19 +188,12 @@ export function evaluateExternalDependencyProbe({
 }
 
 /**
- * Decide the pre-mortem dispatch: size ≥ ½ budget, a risk-heuristic phrase
- * match, or an external-dependency probe match (Story #4700).
+ * Decide the pre-mortem dispatch: an external-dependency probe match
+ * (Story #4700) — the one deterministic trigger left after Story #5312.
  *
  * @param {object} input
- * @param {number} input.ticketCount - Draft ticket count (0 in the
- *   single-delivery shape — no tickets exist).
- * @param {number} input.maxTickets - The reviewability budget
- *   (`getLimits(config).maxTickets`).
- * @param {string[]} [input.riskHeuristics] - `planning.riskHeuristics`
- *   phrases from the resolved config.
- * @param {string} [input.planText] - Concatenated plan text the heuristics and
- *   the external-dependency probe match against (tech spec + serialized
- *   tickets).
+ * @param {string} [input.planText] - Concatenated plan text the probe
+ *   matches against (tech spec + serialized tickets).
  * @param {string[]} [input.knownPackages] - Package specifiers the repo's own
  *   manifests declare (own name + dependency maps + workspace package names),
  *   passed to the external-dependency probe.
@@ -284,58 +203,28 @@ export function evaluateExternalDependencyProbe({
  * @returns {CriticDispatchDecision}
  */
 export function evaluatePremortemDispatch({
-  ticketCount,
-  maxTickets,
-  riskHeuristics = [],
   planText = '',
   knownPackages = [],
   ownerRepo = null,
 }) {
-  if (!Number.isInteger(maxTickets) || maxTickets <= 0) {
-    throw new TypeError(
-      'evaluatePremortemDispatch: maxTickets must be a positive integer',
-    );
-  }
-  const reasons = [];
-
-  const count = Number.isInteger(ticketCount) ? ticketCount : 0;
-  if (count * 2 >= maxTickets) {
-    reasons.push(
-      `Ticket count ${count} is at least half the reviewability budget (maxTickets ${maxTickets}).`,
-    );
-  }
-
-  const haystack = String(planText).toLowerCase();
-  const matched = riskHeuristics.filter(
-    (phrase) =>
-      typeof phrase === 'string' &&
-      phrase.trim().length > 0 &&
-      haystack.includes(phrase.trim().toLowerCase()),
-  );
-  if (matched.length > 0) {
-    reasons.push(
-      `planning.riskHeuristics match(es) in the plan text: ${matched.map((p) => `"${p.trim()}"`).join(', ')}.`,
-    );
-  }
-
   const externalDeps = evaluateExternalDependencyProbe({
     planText,
     knownPackages,
     ownerRepo,
   });
   if (externalDeps.matched) {
-    reasons.push(...externalDeps.reasons);
-  }
-
-  if (reasons.length > 0) {
-    return { critic: 'pre-mortem', dispatch: true, reasons };
+    return {
+      critic: 'pre-mortem',
+      dispatch: true,
+      reasons: externalDeps.reasons,
+    };
   }
 
   return {
     critic: 'pre-mortem',
     dispatch: false,
     reasons: [
-      `Ticket count ${count} is under half the budget (maxTickets ${maxTickets}), no planning.riskHeuristics phrase matches the plan text, and the external-dependency probe found no out-of-repo markers.`,
+      'The external-dependency probe found no out-of-repo markers in the plan text.',
     ],
   };
 }

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

@@ -1,13 +1,13 @@
 /**
  * plan-critics-evaluate.js — shared critic-dispatch evaluation for the
- * collapsed /mandrel-plan flow (#4496 fix 6).
+ * collapsed /mandrel-plan flow (#4496 fix 6; pre-mortem only since Story #5312).
  *
- * One consumer: the `plan-critics.js` CLI, which `/mandrel-plan` runs between its
- * Author and Persist steps. The CLI loads the draft artifacts, calls this
- * module, prints the verdict as JSON, and records every skip on the
- * plan-metrics ledger; the workflow dispatches a fresh-context critic
- * sub-agent on a `dispatch: true` verdict and folds the findings into a
- * re-author round before persist.
+ * One consumer: the `plan-critics.js` CLI, which the operator runs between
+ * Author and Persist when they want the pre-mortem. The CLI loads the draft
+ * artifacts, calls this module, prints the verdict as JSON, and records a
+ * skip on the plan-metrics ledger; the workflow dispatches a fresh-context
+ * critic sub-agent on a `dispatch: true` verdict and folds the findings into
+ * a re-author round before persist.
  *
  * Story #4592 moved that evaluation here from `run-plan-persist.js`, which
  * ran it after authoring was finished and immediately before
@@ -21,26 +21,7 @@
  * @module lib/orchestration/plan-critics-evaluate
  */
 
-import { getLimits } from '../config-resolver.js';
-import {
-  evaluateConsolidationDispatch,
-  evaluatePremortemDispatch,
-} from './plan-critic-conditions.js';
-import { evaluateTextHygiene } from './plan-text-hygiene.js';
-
-/**
- * Resolve the planning risk heuristics list from the canonical config
- * block (same resolution `plan-context.js` and the decompose context use).
- *
- * @param {object} config
- * @returns {string[]}
- */
-function resolveRiskHeuristics(config = {}) {
-  if (Array.isArray(config.planning?.riskHeuristics)) {
-    return config.planning.riskHeuristics;
-  }
-  return [];
-}
+import { evaluatePremortemDispatch } from './plan-critic-conditions.js';
 
 /**
  * Resolve the `{ owner, repo }` the external-dependency probe's cross-repo arm
@@ -57,24 +38,11 @@ function resolveOwnerRepo(config = {}) {
 }
 
 /**
- * Evaluate the consolidation + pre-mortem critic dispatch conditions over
- * the authored planning artifacts (#4474 PR6 conditions, unchanged):
- *
- *   - 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: ticket count at least half `maxTickets`, OR any
- *     `planning.riskHeuristics` phrase matching the plan text, OR the
- *     external-dependency probe (Story #4700) matching an out-of-repo marker
- *     — a scoped package absent from `knownPackages`, a cross-repo
- *     `github.com/<owner>/<repo>` reference, or a named external service
- *     prerequisite. Story #4542 retired its authored-risk-level condition with
- *     the verdict itself.
- *   - Text hygiene (Story #4599, advisory-only): deterministic body lints
- *     (dangling-citation / open-question / slicing-mass) over the draft
- *     stories. It has no `dispatch` semantics and spawns nothing — its
- *     `findings[]` are re-author-round input, and the consolidation /
- *     premortem dispatch verdicts are untouched by it.
+ * Evaluate the pre-mortem critic's dispatch condition over the authored
+ * planning artifacts: the external-dependency probe (Story #4700) matching an
+ * out-of-repo marker — a scoped package absent from `knownPackages`, a
+ * cross-repo `github.com/<owner>/<repo>` reference, or a named external
+ * service prerequisite.
  *
  * @param {{
  *   techSpecContent: string,
@@ -88,9 +56,7 @@ function resolveOwnerRepo(config = {}) {
  *   that gathers them; this module stays pure. Empty when unresolved, which
  *   only widens what the probe treats as external.
  * @returns {{
- *   consolidation: { critic: string, dispatch: boolean, reasons: string[] },
  *   premortem: { critic: string, dispatch: boolean, reasons: string[] },
- *   textHygiene: { critic: string, findings: Array<object> },
  * }}
  */
 export function evaluatePlanCritics({
@@ -100,24 +66,7 @@ export function evaluatePlanCritics({
   knownPackages = [],
 }) {
   const ticketList = Array.isArray(tickets) ? tickets : null;
-  const consolidation =
-    ticketList === null
-      ? {
-          critic: 'consolidation',
-          dispatch: false,
-          reasons: [
-            'single-delivery shape — no draft tickets exist to consolidate.',
-          ],
-        }
-      : evaluateConsolidationDispatch({
-          draftStories: ticketList,
-          specText: techSpecContent,
-        });
-
   const premortem = evaluatePremortemDispatch({
-    ticketCount: ticketList?.length ?? 0,
-    maxTickets: getLimits(config).maxTickets,
-    riskHeuristics: resolveRiskHeuristics(config),
     planText: [
       techSpecContent ?? '',
       ticketList ? JSON.stringify(ticketList) : '',
@@ -126,10 +75,5 @@ export function evaluatePlanCritics({
     ownerRepo: resolveOwnerRepo(config),
   });
 
-  const textHygiene = {
-    critic: 'text-hygiene',
-    findings: evaluateTextHygiene({ draftStories: ticketList }).findings,
-  };
-
-  return { consolidation, premortem, textHygiene };
+  return { premortem };
 }

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

@@ -0,0 +1,300 @@
+/**
+ * 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 repair as the dry-run line the operator reads.
+ *
+ * @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;
+}