mandrel 2.8.0 → 2.10.0

package/.agents/scripts/lib/orchestration/story-close/phases/local-lens-review.js

@@ -13,10 +13,17 @@
  */
 
 import {
+  evaluateLensDiffFloor,
+  resolveLensDiffFloor,
   runAuditSuite,
   selectLocalLenses,
 } from '../../../audit-suite/index.js';
+import { resolveConfig } from '../../../config-resolver.js';
 import { gitSpawn } from '../../../git-utils.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../../observability/runtime-friction.js';
 import { computeChangeSet } from '../../change-set.js';
 
 /**
@@ -180,10 +187,21 @@ function resolveLensChangeSet({
  * this the default review provider dropped the materialized envelope, so the
  * pass was a progress log line with no reader.
  *
+ * Story #4699 — the **lens diff-floor**. When the caller supplies a known
+ * `changedLineCount` and the diff sits strictly below the configured floor
+ * (`delivery.review.lensDiffFloor`, default 40) with zero sensitive-path
+ * hits, the pass records the matched roster but skips materialization
+ * entirely (`skipped: true` with the lenses retained and a `floorSkip`
+ * verdict) — the maker-blind code-review pillar and every hard gate are
+ * untouched. An unknown line count, a disabled floor, or a sensitive-path
+ * hit all fail open to the full materialization.
+ *
  * @param {{
  *   baseRef: string,
  *   headRef: string,
  *   changedFiles?: string[]|null,
+ *   changedLineCount?: number|null,
+ *   lensDiffFloor?: number,
  *   storyId?: number|string|null,
  *   artifactPrefix?: string,
  *   progress: (tag: string, msg: string) => void,
@@ -191,11 +209,15 @@ function resolveLensChangeSet({
  *   gitSpawnFn?: import('../../change-set.js').GitSpawnFn,
  *   selectLocalLensesFn?: typeof selectLocalLenses,
  *   runAuditSuiteFn?: typeof runAuditSuite,
+ *   resolveConfigFn?: typeof resolveConfig,
+ *   evaluateLensDiffFloorFn?: typeof evaluateLensDiffFloor,
+ *   emitToolDegradationFn?: typeof emitRuntimeFriction,
  * }} args
  * @returns {Promise<{
  *   depth: 'light',
  *   lenses: string[],
  *   skipped: boolean,
+ *   floorSkip: object|null,
  *   materialized: object|null,
  *   artifactPaths: string[],
  * }>}
@@ -204,6 +226,8 @@ export async function runLocalLensReview({
   baseRef,
   headRef,
   changedFiles: injectedChangedFiles,
+  changedLineCount = null,
+  lensDiffFloor,
   storyId,
   artifactPrefix,
   progress,
@@ -211,11 +235,15 @@ export async function runLocalLensReview({
   gitSpawnFn = gitSpawn,
   selectLocalLensesFn = selectLocalLenses,
   runAuditSuiteFn = runAuditSuite,
+  resolveConfigFn = resolveConfig,
+  evaluateLensDiffFloorFn = evaluateLensDiffFloor,
+  emitToolDegradationFn = emitRuntimeFriction,
 }) {
   const empty = {
     depth: STORY_SCOPE_LENS_DEPTH,
     lenses: [],
     skipped: true,
+    floorSkip: null,
     materialized: null,
     artifactPaths: [],
   };
@@ -234,6 +262,34 @@ export async function runLocalLensReview({
       );
       return empty;
     }
+
+    // Lens diff-floor (Story #4699). Deliberately evaluated AFTER lens
+    // selection so a floor-skip still records WHICH lenses it skipped —
+    // the findings-yield ledger needs the roster either way.
+    const floorVerdict = evaluateLensDiffFloorFn({
+      changedFiles,
+      changedLineCount,
+      floor:
+        typeof lensDiffFloor === 'number'
+          ? lensDiffFloor
+          : resolveLensDiffFloor(safeResolveConfig(resolveConfigFn)),
+    });
+    if (floorVerdict.skip) {
+      progress(
+        progressTag,
+        `Lens diff-floor: ${floorVerdict.changedLineCount} changed line(s) < ` +
+          `floor ${floorVerdict.floor} with zero sensitive-path hits — ` +
+          `skipping materialization of ${lenses.join(', ')}.`,
+      );
+      return {
+        depth: STORY_SCOPE_LENS_DEPTH,
+        lenses,
+        skipped: true,
+        floorSkip: floorVerdict,
+        materialized: null,
+        artifactPaths: [],
+      };
+    }
     // Scope the artifact filenames to this Story so concurrent closes on a
     // shared audit output dir cannot clobber each other's prompts.
     const effectivePrefix =
@@ -256,16 +312,48 @@ export async function runLocalLensReview({
       depth: STORY_SCOPE_LENS_DEPTH,
       lenses,
       skipped: false,
+      floorSkip: floorVerdict,
       materialized,
       artifactPaths,
     };
   } catch (err) {
     // The lens pass is advisory: a git or materialization failure must not
-    // fail the close. Log and degrade to a skipped envelope.
+    // fail the close. Log, route the tool-execution degradation to friction
+    // telemetry (Story #4699 — degradations are operational signals, not
+    // findings), and degrade to a skipped envelope.
     progress(
       progressTag,
       `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
     );
+    try {
+      await emitToolDegradationFn({
+        storyId,
+        category: RUNTIME_FRICTION_CATEGORIES.TOOL_DEGRADED,
+        tool: 'local-lens-review',
+        details: {
+          surface: 'lens-materialization',
+          reason: String(err?.message ?? err).slice(0, 500),
+        },
+      });
+    } catch {
+      // Observability must never fail the close (best-effort contract).
+    }
     return empty;
   }
 }
+
+/**
+ * Resolve config for the floor read without letting a resolver failure
+ * fail the (advisory) lens pass. Module-local: a degraded config simply
+ * yields the framework-default floor.
+ *
+ * @param {typeof resolveConfig} resolveConfigFn
+ * @returns {object|undefined}
+ */
+function safeResolveConfig(resolveConfigFn) {
+  try {
+    return resolveConfigFn();
+  } catch {
+    return undefined;
+  }
+}

package/.agents/scripts/lib/orchestration/story-close/phases/review-core.js

@@ -9,7 +9,9 @@
  * file (Story #3653 established the shared-spine contract).
  */
 
+import { countChangedLines } from '../../../audit-suite/index.js';
 import { gitSpawn } from '../../../git-utils.js';
+import { appendFindingsYield } from '../../../observability/metrics-ledger.js';
 import { computeChangeSet } from '../../change-set.js';
 import { runCodeReview } from '../../code-review.js';
 import { runLocalLensReview } from './local-lens-review.js';
@@ -57,6 +59,8 @@ import { runLocalLensReview } from './local-lens-review.js';
  *   computeChangeSetFn?: typeof computeChangeSet,
  *   runCodeReviewFn?: typeof runCodeReview,
  *   runLocalLensReviewFn?: typeof runLocalLensReview,
+ *   countChangedLinesFn?: typeof countChangedLines,
+ *   appendFindingsYieldFn?: typeof appendFindingsYield,
  * }} args
  * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
  *   with a `localLensReview` field carrying the Story-scope local-lens pass
@@ -75,6 +79,8 @@ export async function runStoryReviewCore({
   computeChangeSetFn = computeChangeSet,
   runCodeReviewFn = runCodeReview,
   runLocalLensReviewFn = runLocalLensReview,
+  countChangedLinesFn = countChangedLines,
+  appendFindingsYieldFn = appendFindingsYield,
 }) {
   const storyIdNum = Number(storyId);
 
@@ -84,6 +90,16 @@ export async function runStoryReviewCore({
   // honour without retrying (Story #4603).
   const changeSet = computeChangeSetFn({ baseRef, headRef, gitSpawnFn });
 
+  // The one changed-LINE enumeration (Story #4699 — the lens diff-floor's
+  // size signal). Probed only when the file enumeration succeeded with a
+  // non-empty set: a null/empty set already yields an empty lens roster, so
+  // a second git spawn would buy nothing. `null` = count unknown → the
+  // floor fails open (no skip).
+  const changedLineCount =
+    Array.isArray(changeSet.files) && changeSet.files.length > 0
+      ? countChangedLinesFn({ baseRef, headRef, gitSpawnFn })
+      : null;
+
   const opts = {
     scope: 'story',
     ticketId: storyIdNum,
@@ -110,6 +126,7 @@ export async function runStoryReviewCore({
     baseRef,
     headRef,
     changedFiles: changeSet.files,
+    changedLineCount,
     storyId: storyIdNum,
     progress,
     progressTag,
@@ -117,5 +134,61 @@ export async function runStoryReviewCore({
   });
 
   const result = await runCodeReviewFn(opts);
+
+  // Findings-yield ledger (Story #4699) — record what this close's lens
+  // pass produced (or floor-skipped) so the roster can later be tuned on
+  // measurement. Best-effort: a ledger failure never fails the review.
+  try {
+    const yieldEntries = buildLensYieldEntries(localLensReview);
+    if (yieldEntries !== null) {
+      await appendFindingsYieldFn({
+        storyId: storyIdNum,
+        cli: 'story-close-review',
+        lenses: yieldEntries,
+        diffFloor: localLensReview?.floorSkip ?? null,
+      });
+    }
+  } catch (err) {
+    progress(
+      progressTag,
+      `⚠️ findings-yield ledger append failed (continuing): ${err?.message ?? err}`,
+    );
+  }
+
   return { ...result, localLensReview, changeSet };
 }
+
+/**
+ * Fold the lens-pass envelope into per-lens findings-yield entries
+ * (Story #4699). One entry per lens in the matched roster: the lens name,
+ * the count of materialization findings attributed to it, and whether the
+ * diff-floor skipped its materialization. Returns `null` when the roster is
+ * empty (nothing ran, nothing skipped — no record to write).
+ *
+ * Module-local: an implementation detail of {@link runStoryReviewCore},
+ * asserted through the appended record's shape rather than imported
+ * directly.
+ *
+ * @param {object|null|undefined} localLensReview
+ * @returns {Array<{ lens: string, findings: number, skippedByFloor: boolean }>|null}
+ */
+function buildLensYieldEntries(localLensReview) {
+  const lenses = Array.isArray(localLensReview?.lenses)
+    ? localLensReview.lenses.filter((l) => typeof l === 'string' && l.length)
+    : [];
+  if (lenses.length === 0) return null;
+  const skippedByFloor = localLensReview?.floorSkip?.skip === true;
+  const findingsByLens = new Map();
+  for (const finding of localLensReview?.materialized?.findings ?? []) {
+    if (typeof finding?.audit !== 'string') continue;
+    findingsByLens.set(
+      finding.audit,
+      (findingsByLens.get(finding.audit) ?? 0) + 1,
+    );
+  }
+  return lenses.map((lens) => ({
+    lens,
+    findings: skippedByFloor ? 0 : (findingsByLens.get(lens) ?? 0),
+    skippedByFloor,
+  }));
+}

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -263,8 +263,11 @@ export function emitTerminalEnvelope(
   envelope,
   { write = (s) => process.stdout.write(s) } = {},
 ) {
+  // Story #4685 — compact (not 2-space pretty) JSON. The envelope is a
+  // machine contract callers recover with `JSON.parse`, so pretty-printing
+  // only adds turn-resident bytes without helping any consumer.
   write(
-    `\n${TERMINAL_BEGIN_MARKER}\n${JSON.stringify(envelope, null, 2)}\n${TERMINAL_END_MARKER}\n`,
+    `\n${TERMINAL_BEGIN_MARKER}\n${JSON.stringify(envelope)}\n${TERMINAL_END_MARKER}\n`,
   );
 }
 

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -52,6 +52,10 @@
  * at a time.
  */
 
+import {
+  suggestPathEntryFix,
+  suggestVerifyFix,
+} from '../story-body/body-format-lints.js';
 import {
   parse as parseStoryBody,
   StoryBodyParseError,
@@ -73,44 +77,6 @@ export const VERIFY_TIER_VALUES = Object.freeze([
   'validate',
 ]);
 
-const PATH_LIKE_RE = /[/.][\w@\-./*]+|\*\*?\/?\*?\.\w+|[a-z][\w-]*\/[\w-./*]+/i;
-const VAGUE_VERBS = [
-  'clean up',
-  'refactor',
-  'improve',
-  'polish',
-  'tighten',
-  'tidy',
-  'simplify',
-];
-
-/**
- * @param {string} bullet
- * @returns {boolean}
- */
-function bulletNamesPath(bullet) {
-  const colonIdx = bullet.indexOf(':');
-  if (colonIdx <= 0) return PATH_LIKE_RE.test(bullet);
-  const head = bullet.slice(0, colonIdx);
-  // The conventional shape is "<path>: <verb> <object>" — head is the path.
-  return PATH_LIKE_RE.test(head) || PATH_LIKE_RE.test(bullet);
-}
-
-/**
- * @param {string} bullet
- * @returns {string|null} reason if the bullet uses a vague verb without a named target, else null.
- */
-function vagueVerbWithoutTarget(bullet) {
-  const lower = bullet.toLowerCase();
-  for (const verb of VAGUE_VERBS) {
-    if (!lower.includes(verb)) continue;
-    if (!bulletNamesPath(bullet)) {
-      return verb;
-    }
-  }
-  return null;
-}
-
 /**
  * Predicate: should the validator skip this ticket entirely? Skip when:
  *   - it is not a Story (only `type: 'story'` tickets are validated here),
@@ -297,8 +263,13 @@ function collectChangesErrors(prefix, rawChanges) {
   }
   for (const entry of changes) {
     if (typeof entry === 'string') {
+      const fix = suggestPathEntryFix(entry);
+      const fixIt =
+        fix === null
+          ? ''
+          : ` Suggested fix: ${fix} (adjust the assumption to creates|deletes if this is a new file or a removal).`;
       errors.push(
-        `${prefix}: body.changes entry must be a { path, assumption } object; plain string bullets are no longer accepted: "${entry}".`,
+        `${prefix}: body.changes entry must be a { path, assumption } object; plain string bullets are no longer accepted: "${entry}".${fixIt}`,
       );
       continue;
     }
@@ -385,8 +356,10 @@ function collectVerifyErrors(prefix, rawVerify) {
       continue;
     }
     if (!VERIFY_TIER_RE.test(v)) {
+      const fix = suggestVerifyFix(v);
+      const fixIt = fix === null ? '' : ` Suggested fix: "${fix}".`;
       errors.push(
-        `${prefix}: body.verify entry must end with a tier in parentheses — one of (${VERIFY_TIER_VALUES.join('|')}). Got: "${v}".`,
+        `${prefix}: body.verify entry must end with a tier in parentheses — one of (${VERIFY_TIER_VALUES.join('|')}). Got: "${v}".${fixIt}`,
       );
     }
   }

package/.agents/scripts/lib/story-body/body-format-lints.js

@@ -0,0 +1,215 @@
+/**
+ * body-format-lints.js — SSOT for the deterministic body-format lints that can
+ * REJECT an authored Story body at persist time, plus the mechanical auto-fix
+ * inference a failing dry-run surfaces (Story #4684).
+ *
+ * The problem this closes: deterministic format rules (structured `## Changes`
+ * bullet shape, verify-tier suffixes) used to be discovered only as persist
+ * dry-run failures — every miss cost a full re-author round-trip at
+ * resident-context prices. This module is the single home for two remedies:
+ *
+ *   1. `BODY_FORMAT_LINTS` — the enumerated rejecting lints, each carrying a
+ *      concrete good/bad example. `templates/decomposer-prompts.js` renders
+ *      them into the story-author system prompt so the first draft is
+ *      lint-clean by construction; a test enumerates the registry against the
+ *      rendered prompt (Story #4684 AC-1).
+ *   2. `suggestPathEntryFix` / `suggestVerifyFix` — the mechanical rewrites.
+ *      `story-body.js` (`parsePathEntry`) and `task-body-validator.js`
+ *      (`collectChangesErrors` / `collectVerifyErrors`) call them so a failing
+ *      lint emits the corrected form ready to paste rather than a bare reject
+ *      (AC-2).
+ *
+ * Import hygiene: this module imports only the cycle-free
+ * `file-assumption-enum.js` leaf. It must NOT import `story-body.js` or
+ * `task-body-validator.js` — both import this module, and either back-edge
+ * would introduce a cycle (see the note in `file-assumption-enum.js`).
+ */
+
+import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
+
+/**
+ * Canonical testing-tier vocabulary an inferred verify suffix may name. Kept in
+ * sync with `task-body-validator.js`'s `VERIFY_TIER_VALUES` by a test rather
+ * than an import (importing that module here would create a cycle).
+ *
+ * @type {readonly ['unit','contract','e2e','validate']}
+ */
+const INFERABLE_VERIFY_TIERS = Object.freeze([
+  'unit',
+  'contract',
+  'e2e',
+  'validate',
+]);
+
+/**
+ * The default assumption a mechanical `## Changes` auto-fix proposes. Most
+ * bare-path bullets an author drops are in-place edits, so `refactors-existing`
+ * is the safe default — the fix-it text tells the author to switch it to
+ * `creates` / `deletes` when the edit is net-new or a removal.
+ */
+const DEFAULT_SUGGESTED_ASSUMPTION = 'refactors-existing';
+
+// A token that looks like a file path / glob / module id: it carries a `/` or a
+// `.`-separated segment. Deliberately loose — the suggestion is best-effort, and
+// a false positive only produces an unhelpful (still-valid) fix-it string.
+const PATH_LIKE_RE = /[\w@*-]*[/.][\w@./*-]+/;
+
+/**
+ * Infer the testing tier a bare `verify[]` command implies, when it is
+ * unambiguous. Returns `null` when no confident inference is possible (the
+ * author must then choose the tier themselves — the lint still fires, just
+ * without a fix-it).
+ *
+ * @param {unknown} command
+ * @returns {'unit'|'contract'|'e2e'|'validate'|null}
+ */
+function inferVerifyTier(command) {
+  if (typeof command !== 'string') return null;
+  const c = command.toLowerCase();
+  if (/\bvalidate\b/.test(c)) return 'validate';
+  if (/playwright|\.spec\.|\be2e\b/.test(c)) return 'e2e';
+  if (/\.test\.|node --test|node:test|\bvitest\b|\bjest\b/.test(c)) {
+    return 'unit';
+  }
+  if (/\bcontract\b/.test(c)) return 'contract';
+  return null;
+}
+
+/**
+ * Propose the corrected form of a `verify[]` entry that is missing its tier
+ * suffix, when the tier is inferable from the command. Returns `null` when the
+ * entry is a `manual:` escape, is empty, or the tier cannot be inferred.
+ *
+ * @param {unknown} entry
+ * @returns {string|null} e.g. `"npm run validate (validate)"`.
+ */
+export function suggestVerifyFix(entry) {
+  if (typeof entry !== 'string') return null;
+  const trimmed = entry.trim();
+  if (trimmed === '' || trimmed.startsWith('manual:')) return null;
+  const tier = inferVerifyTier(trimmed);
+  if (tier === null) return null;
+  // Drop any trailing (…) — a wrong/partial tier suffix — before appending the
+  // inferred one, so `npm test (smoke)` becomes `npm test (unit)` not a double.
+  const base = trimmed.replace(/\s*\([^)]*\)\s*$/, '').trim();
+  if (base === '') return null;
+  return `${base} (${tier})`;
+}
+
+/**
+ * Propose the canonical `{ path, assumption }` object form for a `## Changes` /
+ * `## References` bullet an author wrote as a bare path string (or a humanized
+ * bullet with a bad assumption). Returns `null` when no path-shaped token can
+ * be salvaged.
+ *
+ * The returned string is inline-JSON that round-trips cleanly back through the
+ * story-body parser, so it is paste-ready.
+ *
+ * @param {unknown} raw
+ * @returns {string|null} e.g. `{"path":"src/app.js","assumption":"refactors-existing"}`.
+ */
+export function suggestPathEntryFix(raw) {
+  if (typeof raw !== 'string') return null;
+  // Strip a leading markdown bullet marker.
+  let s = raw
+    .trim()
+    .replace(/^[-*]\s+/, '')
+    .trim();
+  // Take the segment before any humanized "— assumption" tail.
+  s = s.split('—')[0].trim();
+  // Peel surrounding backticks / quotes.
+  s = s
+    .replace(/^[`'"]+/, '')
+    .replace(/[`'"]+$/, '')
+    .trim();
+  if (s === '' || !PATH_LIKE_RE.test(s)) return null;
+  return JSON.stringify({ path: s, assumption: DEFAULT_SUGGESTED_ASSUMPTION });
+}
+
+/**
+ * A single deterministic body-format lint the persist path enforces.
+ *
+ * @typedef {object} BodyFormatLint
+ * @property {string}  id          Stable identifier (also the prompt anchor).
+ * @property {string}  summary     One-line statement of the requirement.
+ * @property {string}  badExample  A form the lint rejects.
+ * @property {string}  goodExample The lint-clean form to author instead.
+ * @property {boolean} autoFixable Whether a failing dry-run emits a fix-it.
+ */
+
+/**
+ * The enumerated deterministic lints that can reject an authored Story body at
+ * persist time. Each carries a concrete example so the story-author prompt can
+ * state the requirement example-first (Story #4684 AC-1). The two `autoFixable`
+ * lints are the mechanical rewrites whose dry-run failure carries the corrected
+ * form (AC-2).
+ *
+ * @type {ReadonlyArray<BodyFormatLint>}
+ */
+export const BODY_FORMAT_LINTS = Object.freeze([
+  {
+    id: 'body-is-string',
+    summary:
+      'The Story `body` MUST be the serialized markdown string produced by `serialize()`, never a JSON object.',
+    badExample: '"body": { "goal": "…" }',
+    goodExample: '"body": "## Goal\\n…"',
+    autoFixable: false,
+  },
+  {
+    id: 'goal-non-empty',
+    summary: 'The body MUST open with a non-empty `## Goal` sentence.',
+    badExample: '## Goal\n\n## Spec',
+    goodExample:
+      '## Goal\nExchange short-lived JWTs so sessions survive a restart.',
+    autoFixable: false,
+  },
+  {
+    id: 'changes-path-entry-shape',
+    summary:
+      'Every `## Changes` / `## References` bullet MUST be a `{ path, assumption }` object (assumption ∈ ' +
+      `${FILE_ASSUMPTION_VALUES.join(' | ')}); plain path strings are rejected.`,
+    badExample: '- src/app.js',
+    goodExample: '- {"path": "src/app.js", "assumption": "refactors-existing"}',
+    autoFixable: true,
+  },
+  {
+    id: 'changes-non-empty',
+    summary: 'A Story MUST declare at least one `## Changes` bullet.',
+    badExample: '## Changes\n\n## Acceptance',
+    goodExample: '- {"path": "src/app.js", "assumption": "creates"}',
+    autoFixable: false,
+  },
+  {
+    id: 'verify-tier-suffix',
+    summary:
+      'Every `verify[]` entry MUST end with a tier in parentheses — one of ' +
+      `(${INFERABLE_VERIFY_TIERS.join(' | ')}) — or be a \`manual:<reason>\` escape.`,
+    badExample: 'npm test -- src/app.test.js',
+    goodExample: 'npm test -- src/app.test.js (unit)',
+    autoFixable: true,
+  },
+  {
+    id: 'verify-non-empty',
+    summary:
+      'A Story MUST list at least one `verify[]` entry (use `manual:<reason>` only when truly unverifiable in isolation).',
+    badExample: '"verify": []',
+    goodExample: '"verify": ["npm run validate (validate)"]',
+    autoFixable: false,
+  },
+  {
+    id: 'verify-manual-reason',
+    summary:
+      'A `manual:` verify entry MUST carry a reason after the colon; a bare `manual:` is rejected.',
+    badExample: 'manual:',
+    goodExample: 'manual: copy-only edit an auditor eyeballs',
+    autoFixable: false,
+  },
+  {
+    id: 'acceptance-non-empty',
+    summary:
+      'A Story MUST list at least one observable `acceptance[]` criterion.',
+    badExample: '"acceptance": []',
+    goodExample: '"acceptance": ["`npm run build` exits 0"]',
+    autoFixable: false,
+  },
+]);

package/.agents/scripts/lib/story-body/story-body.js

@@ -48,6 +48,7 @@ import {
   authoredMarkerLine,
 } from '../framework-version.js';
 import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js';
+import { suggestPathEntryFix } from './body-format-lints.js';
 
 // ---------------------------------------------------------------------------
 // Public types (JSDoc only — no runtime schema file)
@@ -229,7 +230,7 @@ function parsePathEntry(raw, warnings) {
     }
     // Recognized the humanized shape but the fields are invalid: fail closed.
     throw new StoryBodyParseError(
-      `changes/references entry is a humanized bullet but not a valid PathEntry: ${str.slice(0, 120)}`,
+      `changes/references entry is a humanized bullet but not a valid PathEntry: ${str.slice(0, 120)}${pathEntryFixIt(str)}`,
       { field: 'changes', raw: str },
     );
   }
@@ -261,11 +262,26 @@ function parsePathEntry(raw, warnings) {
   }
 
   throw new StoryBodyParseError(
-    `changes/references entry must be a { path, assumption } object; plain string bullets are no longer accepted: ${str.slice(0, 120)}`,
+    `changes/references entry must be a { path, assumption } object; plain string bullets are no longer accepted: ${str.slice(0, 120)}${pathEntryFixIt(str)}`,
     { field: 'changes', raw: str },
   );
 }
 
+/**
+ * Build the ` Suggested fix: …` suffix for a rejected changes/references
+ * bullet, when a `{ path, assumption }` object can be salvaged from it. Returns
+ * an empty string when nothing is inferable, so callers can append it
+ * unconditionally (Story #4684 — mechanical auto-fix in the failure output).
+ *
+ * @param {string} raw The rejected bullet text.
+ * @returns {string}
+ */
+function pathEntryFixIt(raw) {
+  const suggestion = suggestPathEntryFix(raw);
+  if (suggestion === null) return '';
+  return ` — Suggested fix: ${suggestion} (adjust the assumption to creates|deletes if this is a new file or a removal).`;
+}
+
 /**
  * Extract the `blocked by #N` lines from the footer block (text after
  * the last `---` separator). Returns an array of "#N" strings.