mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/orchestration/spec-section-validator.js

@@ -1,5 +1,5 @@
 /**
- * spec-section-validator.js — Phase 7.5 Tech Spec post-authoring section gate.
+ * spec-section-validator.js — Tech Spec post-authoring section gate.
  *
  * `/plan` Phase 7 authors a Tech Spec from documentation and the Epic body.
  * Phase 8.3 (Holistic Consolidation) then reconciles the draft ticket array
@@ -12,19 +12,29 @@
  *
  * `validateSpecSections` parses a Tech Spec body for the required
  * `## Delivery Slicing` heading (accepting the casing/wording variants
- * below) and returns a deterministic `{ ok, missing[] }` envelope. The
- * caller (`epic-plan-spec-validate.js`) maps a non-empty `missing[]` to a
- * non-zero exit so Phase 8 decomposition cannot proceed against an
- * un-anchored spec.
+ * below) and returns a deterministic `{ ok, missing[] }` envelope.
  *
- * This is the Phase 8-side counterpart to the Phase 6 Epic Clarity Gate
+ * Story #4403 (Finding 3): this gate used to be run by a standalone
+ * `epic-plan-spec-validate.js` CLI as a separate Phase 7.5 workflow step —
+ * but by the time the documented ordering ran it, the Phase 7 persist path's
+ * `cleanupPhaseTempFiles` had already deleted the temp `techspec.md` file the
+ * gate read, so the "blocking gate" could never actually block. The CLI is
+ * retired; `runSpecPhase` (`phases/run-spec-phase.js`) now calls
+ * `validateSpecSections` directly against the in-memory authored content as
+ * part of its input validation, before any GitHub mutation. This is the
+ * Phase 8-side counterpart to the Phase 6 Epic Clarity Gate
  * ({@link ../epic-plan-clarity.js#scoreEpicBody}) — same detect-then-prompt
- * pattern, one phase later, but a hard gate (exit non-zero) rather than an
+ * pattern, one phase later, but a hard gate (fail closed) rather than an
  * advisory rubric.
  *
- * Pure ESM, no I/O.
+ * `validateSpecSections` and `formatMissingSectionMessage` are pure, I/O-free
+ * helpers. `validateSpecFile` is a thin disk-reading convenience for callers
+ * (tests, ad-hoc tooling) that hold a path rather than in-memory content.
  */
 
+import { readFile } from 'node:fs/promises';
+import { DELIVERY_SLICING_RE } from '../epic-body-sections.js';
+
 /**
  * The single required Tech Spec section, with the heading variants the
  * Architect persona may emit. Matched case-insensitively against any
@@ -39,7 +49,7 @@ const REQUIRED_SECTIONS = Object.freeze([
   {
     name: 'Delivery Slicing',
     /** Level-2 heading, allowing the `Delivery ` qualifier to be optional. */
-    re: /^##\s+(?:Delivery\s+)?Slicing\s*$/im,
+    re: DELIVERY_SLICING_RE,
   },
 ]);
 
@@ -78,3 +88,44 @@ export function validateSpecSections({ body } = {}) {
 
   return { ok: missing.length === 0, missing, present };
 }
+
+/**
+ * Validate an authored Tech Spec file for the required post-authoring
+ * sections. Thin wrapper around `validateSpecSections` that owns the file
+ * read so callers holding a path (rather than in-memory content) do not each
+ * re-implement the read-then-validate sequence.
+ *
+ * @param {{ techspecPath: string }} args
+ * @returns {Promise<{ ok: boolean, missing: string[], present: string[] }>}
+ */
+export async function validateSpecFile({ techspecPath }) {
+  const body = await readFile(techspecPath, 'utf8');
+  return validateSpecSections({ body });
+}
+
+/**
+ * Build the operator-facing failure message for a missing-section result.
+ * Names each missing section and tells the operator whether to re-author the
+ * spec or add the section by hand before continuing.
+ *
+ * @param {{ techspecPath: string, missing: string[] }} args
+ * @returns {string}
+ */
+export function formatMissingSectionMessage({ techspecPath, missing }) {
+  const list = missing.map((name) => `## ${name}`).join(', ');
+  return [
+    `[spec-section-validator] Tech Spec is missing required section(s): ${list}`,
+    `  Spec source: ${techspecPath}`,
+    '',
+    `  Phase 8 (decomposition) reconciles the draft ticket array against the`,
+    `  Tech Spec's "## Delivery Slicing" section — without it, the Phase 8.3`,
+    `  consolidation pass has no capability-boundary anchor and groups by`,
+    `  technical shape instead.`,
+    '',
+    '  To continue, do ONE of the following and re-run the Phase 7 persist step:',
+    `    1. Re-author the Tech Spec (re-run the Phase 7 spec-author step) so it`,
+    `       emits a "## Delivery Slicing" section, OR`,
+    `    2. Add a "## Delivery Slicing" section to the Tech Spec by hand,`,
+    `       describing the capability boundaries the work should be sliced along.`,
+  ].join('\n');
+}

package/.agents/scripts/lib/orchestration/story-close/auto-refresh-runner.js

@@ -376,7 +376,7 @@ function filterToStoryDiff({ miRows, crapRows, storyDiffPaths }) {
 
 /**
  * Check whether a `baseline-refresh-regression` signal tagged with the
- * runner's `source.tool === 'auto-refresh-runner'` already exists in the
+ * runner's `emitter.tool === 'auto-refresh-runner'` already exists in the
  * Story's signals stream. Backs the AC3 idempotent-re-run contract.
  */
 async function priorRefusalSignalExists({
@@ -391,7 +391,7 @@ async function priorRefusalSignalExists({
       typeof record === 'object' &&
       record.kind === 'friction' &&
       record.category === FRICTION_CATEGORY &&
-      record?.source?.tool === RUNNER_SOURCE_TOOL
+      record?.emitter?.tool === RUNNER_SOURCE_TOOL
     ) {
       found = true;
     }
@@ -413,12 +413,14 @@ function buildRefusalSignal({
 }) {
   return {
     kind: 'friction',
-    timestamp: new Date().toISOString(),
+    ts: new Date().toISOString(),
     epicId,
     storyId,
     category: FRICTION_CATEGORY,
-    source: { tool: RUNNER_SOURCE_TOOL },
-    details: `Auto-refresh refused: ${refusalReasons.length} row(s) breach configured caps (miDropCap=${caps.miDropCap}, crapJumpCap=${caps.crapJumpCap}).`,
+    emitter: { tool: RUNNER_SOURCE_TOOL },
+    details: {
+      message: `Auto-refresh refused: ${refusalReasons.length} row(s) breach configured caps (miDropCap=${caps.miDropCap}, crapJumpCap=${caps.crapJumpCap}).`,
+    },
     refusalReasons,
     miOverCap,
     crapOverCap,

package/.agents/scripts/lib/orchestration/story-close/merge-runner.js

@@ -55,6 +55,10 @@ import {
   buildMergeMessageWithCap,
   loadHeaderMaxLength,
 } from './merge-subject.js';
+import {
+  assertNoForeignEpicLock as defaultAssertNoForeignEpicLock,
+  assertSharedCheckoutAvailable as defaultAssertSharedCheckoutAvailable,
+} from './shared-checkout-guard.js';
 
 /**
  * Render the lock-file path for a given main-repo `cwd` + `epicId`. Pure;
@@ -424,7 +428,7 @@ export async function runFinalizeMerge({
   storyBranch,
   storyTitle,
   storyId,
-  epicId: _epicId,
+  epicId,
   cwd,
   config,
   bus = null,
@@ -432,6 +436,7 @@ export async function runFinalizeMerge({
   logger = DefaultLogger,
   gitSync = defaultGitSync,
   gitSpawn = defaultGitSpawn,
+  assertSharedCheckoutAvailable = defaultAssertSharedCheckoutAvailable,
 }) {
   rebaseStoryOnEpic({
     config,
@@ -443,6 +448,15 @@ export async function runFinalizeMerge({
     gitSpawn,
   });
 
+  // Story #4460 — cross-epic shared-checkout guard. Runs AFTER the
+  // per-Epic merge lock is already held (acquired around the whole close
+  // flow in story-close.js) so it composes with, rather than replaces,
+  // that same-epic serialization. Fails fast with an actionable
+  // diagnostic instead of letting a raw `git checkout` error surface
+  // when another epic's merge phase (or unrelated dirt) holds the
+  // shared checkout.
+  assertSharedCheckoutAvailable({ cwd, epicId, gitSpawn });
+
   log('GIT', `Checking out ${epicBranch}...`);
   gitSync(cwd, 'checkout', epicBranch);
   gitSpawn(cwd, 'pull', '--rebase', 'origin', epicBranch);
@@ -582,13 +596,21 @@ export async function runResumeMerge({
   storyBranch,
   storyTitle,
   storyId,
-  epicId: _epicId,
+  epicId,
   config,
   bus = null,
   logger = DefaultLogger,
   log = () => {},
   gitSpawn = defaultGitSpawn,
+  assertNoForeignEpicLockFn = defaultAssertNoForeignEpicLock,
 }) {
+  // Story #4460 follow-up: the resume path re-enters the shared checkout
+  // just like the finalize path, so another epic's live merge phase is
+  // the same hazard here. Only the foreign-lock half of the guard runs —
+  // a resume's own partial merge legitimately leaves the tree dirty, so
+  // the dirty-tree probe would false-positive against our own state.
+  assertNoForeignEpicLockFn({ cwd, epicId });
+
   const resumeMergeMessage = await buildMergeMessage(storyTitle, storyId, {
     cwd,
     logger,

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

@@ -5,9 +5,9 @@
  * Sits between the close-validation gate chain and the merge into
  * `epic/<id>` inside `runStoryCloseLocked` (locked-pipeline.js). The
  * configured ReviewProvider runs against the
- * `epic/<id>`…`story-<id>` diff. The structured `code-review` comment
- * is posted to the Story issue (default `commentTargetId === ticketId`
- * inside `runCodeReview`). Outcomes:
+ * `epic/<id>`…`story-<id>` diff. The unified `verification-results`
+ * structured comment is posted to the Story issue (default
+ * `commentTargetId === ticketId` inside `runCodeReview`). Outcomes:
  *
  *   - clean / non-critical findings → `{ blocked: null }`; the pipeline
  *     proceeds to merge.
@@ -32,10 +32,141 @@
  * invocation pattern (Story #3653).
  */
 
+import {
+  runAuditSuite,
+  selectLocalLenses,
+} from '../../../audit-suite/index.js';
+import { gitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
 import { runCodeReview } from '../../code-review.js';
 import { emitBlockedCloseResult } from '../merge-runner.js';
 
+/**
+ * The review depth the Story-scope local-lens pass runs at. Shift-left
+ * (Epic #4405): local concerns are cheap to decide on a single Story's diff, so
+ * the maker-blind Story-scope review runs its matched local lenses at `light`
+ * depth here rather than paying a deeper pass at Epic close. Fixed for this
+ * tier — it is not risk-scaled like the code-review pillar depth.
+ */
+export const STORY_SCOPE_LENS_DEPTH = 'light';
+
+/**
+ * Enumerate the files changed in the `baseRef...headRef` diff via
+ * `git diff --name-only`. Best-effort: returns `[]` when the diff cannot be
+ * enumerated (git failure, missing ref) and never throws, mirroring the
+ * advisory posture of the surrounding review phase. Synchronous `gitSpawn`
+ * (returns `{ status, stdout }`) is the same seam `code-review.js#countChangedFiles`
+ * uses.
+ *
+ * @param {{ baseRef: string, headRef: string, gitSpawnFn?: typeof gitSpawn }} args
+ * @returns {string[]} Changed file paths, or `[]` on any failure.
+ */
+export function enumerateChangedFiles({
+  baseRef,
+  headRef,
+  gitSpawnFn = gitSpawn,
+}) {
+  try {
+    const result = gitSpawnFn(
+      process.cwd(),
+      'diff',
+      '--name-only',
+      `${baseRef}...${headRef}`,
+    );
+    if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
+      return [];
+    }
+    return result.stdout
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Run the Story-scope local-lens pass: select the LOCAL-tier lenses whose
+ * `filePatterns` match the actual Story diff (`baseRef...headRef`) and
+ * materialize their lens-prompt bodies at `light` depth. This is the
+ * shift-left tier from Epic #4405 — it runs **inside** the story-close
+ * subprocess spine (called only from {@link runStoryReviewCore}), never in the
+ * delivering child's (maker's) context, so a maker never grades its own work.
+ *
+ * A diff that matches no local lens adds **no** lens work: the roster is empty
+ * and `runAuditSuite` is never invoked. Best-effort and total — a git or
+ * materialization failure degrades to `{ skipped: true, lenses: [] }` and is
+ * logged via `progress`, matching the advisory posture the review phase already
+ * takes for provider/transport failures.
+ *
+ * @param {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ *   gitSpawnFn?: typeof gitSpawn,
+ *   selectLocalLensesFn?: typeof selectLocalLenses,
+ *   runAuditSuiteFn?: typeof runAuditSuite,
+ * }} args
+ * @returns {Promise<{
+ *   depth: 'light',
+ *   lenses: string[],
+ *   skipped: boolean,
+ *   materialized: object|null,
+ * }>}
+ */
+export async function runLocalLensReview({
+  baseRef,
+  headRef,
+  progress,
+  progressTag = 'CODE-REVIEW',
+  gitSpawnFn = gitSpawn,
+  selectLocalLensesFn = selectLocalLenses,
+  runAuditSuiteFn = runAuditSuite,
+}) {
+  const empty = {
+    depth: STORY_SCOPE_LENS_DEPTH,
+    lenses: [],
+    skipped: true,
+    materialized: null,
+  };
+  let lenses;
+  try {
+    const changedFiles = enumerateChangedFiles({
+      baseRef,
+      headRef,
+      gitSpawnFn,
+    });
+    lenses = selectLocalLensesFn({ changedFiles });
+    if (lenses.length === 0) {
+      progress(
+        progressTag,
+        'No local lens matched the Story diff — skipping the lens pass.',
+      );
+      return empty;
+    }
+    const materialized = await runAuditSuiteFn({ auditWorkflows: lenses });
+    progress(
+      progressTag,
+      `Ran ${lenses.length} local lens(es) at ${STORY_SCOPE_LENS_DEPTH} depth: ${lenses.join(', ')}.`,
+    );
+    return {
+      depth: STORY_SCOPE_LENS_DEPTH,
+      lenses,
+      skipped: false,
+      materialized,
+    };
+  } catch (err) {
+    // The lens pass is advisory: a git or materialization failure must not
+    // fail the close. Log and degrade to a skipped envelope.
+    progress(
+      progressTag,
+      `⚠️ local lens pass failed (continuing without it): ${err?.message ?? err}`,
+    );
+    return empty;
+  }
+}
+
 /**
  * Collect the extra fields for the code-review-critical blocked envelope.
  * Pure; used by `runStoryCodeReview` to populate the `extra` argument of
@@ -92,8 +223,13 @@ function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
  *   progressTag?: string,
  *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
  *   runCodeReviewFn?: typeof runCodeReview,
+ *   runLocalLensReviewFn?: typeof runLocalLensReview,
  * }} args
- * @returns {Promise<object>} Raw result envelope from `runCodeReview`.
+ * @returns {Promise<object>} Raw result envelope from `runCodeReview`, augmented
+ *   with a `localLensReview` field carrying the Story-scope local-lens pass
+ *   outcome (Epic #4405, Story #4409). Both close entry points reach the lens
+ *   pass through this single spine, so it runs on the Epic-attached and
+ *   standalone paths alike and always inside the close subprocess.
  */
 export async function runStoryReviewCore({
   storyId,
@@ -105,6 +241,7 @@ export async function runStoryReviewCore({
   progressTag = 'CODE-REVIEW',
   planningRisk = null,
   runCodeReviewFn = runCodeReview,
+  runLocalLensReviewFn = runLocalLensReview,
 }) {
   const storyIdNum = Number(storyId);
   const opts = {
@@ -127,7 +264,21 @@ export async function runStoryReviewCore({
   if (planningRisk != null) {
     opts.planningRisk = planningRisk;
   }
-  return runCodeReviewFn(opts);
+
+  // Shift-left local-lens pass (Epic #4405). Runs matched local lenses at
+  // `light` depth against the actual Story diff, inside this close-subprocess
+  // spine so the maker never grades its own work. Advisory — it never blocks
+  // the close and its outcome rides on the returned envelope for downstream
+  // consumers.
+  const localLensReview = await runLocalLensReviewFn({
+    baseRef,
+    headRef,
+    progress,
+    progressTag,
+  });
+
+  const result = await runCodeReviewFn(opts);
+  return { ...result, localLensReview };
 }
 
 /**
@@ -155,8 +306,12 @@ export async function runStoryReviewCore({
  *   progress: (tag: string, msg: string) => void,
  *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
  *   runCodeReviewFn?: typeof runCodeReview,
+ *   runLocalLensReviewFn?: typeof runLocalLensReview,
  * }} args
- * @returns {Promise<{ blocked: object|null }>}
+ * @returns {Promise<{ blocked: object|null, localLensReview?: object }>}
+ *   `localLensReview` carries the Story-scope local-lens pass outcome
+ *   (Epic #4405, Story #4409) when the review completed; it is absent only when
+ *   the whole review phase threw (advisory failure).
  */
 export async function runStoryCodeReview(args) {
   const {
@@ -168,6 +323,7 @@ export async function runStoryCodeReview(args) {
     progress,
     planningRisk = null,
     runCodeReviewFn = runCodeReview,
+    runLocalLensReviewFn = runLocalLensReview,
   } = args;
 
   const storyIdNum = Number(storyId);
@@ -186,6 +342,7 @@ export async function runStoryCodeReview(args) {
       progress,
       planningRisk,
       runCodeReviewFn,
+      runLocalLensReviewFn,
     });
   } catch (err) {
     // Adapter / wiring failure — log and proceed. The review is advisory
@@ -197,6 +354,8 @@ export async function runStoryCodeReview(args) {
     return { blocked: null };
   }
 
+  const localLensReview = reviewResult?.localLensReview;
+
   if (reviewResult?.halted) {
     const blocked = await emitBlockedCloseResult({
       storyId: storyIdNum,
@@ -208,7 +367,7 @@ export async function runStoryCodeReview(args) {
       blockedMessage: `Story #${storyIdNum} blocked: code-review reported ${reviewResult.severity.critical} critical blocker(s).`,
       logger: Logger,
     });
-    return { blocked };
+    return { blocked, localLensReview };
   }
 
   const counts = reviewResult?.severity ?? {};
@@ -216,5 +375,5 @@ export async function runStoryCodeReview(args) {
     'CODE-REVIEW',
     `Review complete — high=${counts.high ?? 0} medium=${counts.medium ?? 0} suggestion=${counts.suggestion ?? 0} (posted=${reviewResult?.posted ?? false}).`,
   );
-  return { blocked: null };
+  return { blocked: null, localLensReview };
 }

package/.agents/scripts/lib/orchestration/story-close/shared-checkout-guard.js

@@ -0,0 +1,163 @@
+/**
+ * shared-checkout-guard.js — cross-epic contention guard for the merge
+ * phase's `git checkout <epicBranch>` in the shared main checkout
+ * (Story #4460).
+ *
+ * `story-close.js`'s merge phase (`runFinalizeMerge` in `merge-runner.js`)
+ * runs `git checkout <epicBranch>` directly in the shared main repo
+ * checkout — `close-inputs.js` resolves `cwd` to `PROJECT_ROOT`, not an
+ * isolated worktree. The only exclusivity guard around that shared
+ * checkout is the per-Epic `epic-merge-lock.js` mutex, which only
+ * serializes concurrent runs for the SAME epic. Nothing stops a
+ * DIFFERENT epic's concurrently-running `story-close.js` from treating
+ * the same shared checkout as scratch space at the same time.
+ *
+ * This was observed live: while delivering Epic #4425 Stories #4427/#4428,
+ * the shared checkout repeatedly carried uncommitted stray changes
+ * belonging to a concurrently-running Epic #4405 delivery (parked on
+ * `epic/4405` with dirty edits), which blocked the `git checkout epic/4425`
+ * merge step with a raw `error: Your local changes ... would be
+ * overwritten by checkout`.
+ *
+ * `assertSharedCheckoutAvailable` runs immediately before that checkout
+ * and fails fast with an actionable, story-close-specific diagnostic
+ * instead of letting the raw git error surface. It COMPOSES with (does
+ * not replace) the per-Epic lock: by the time this guard runs, the
+ * caller's own epic lock is already held (acquired around the whole
+ * close flow in `story-close.js`), so this guard only inspects OTHER
+ * epics' lock files plus the tree's overall dirty state — it never
+ * contends with same-epic concurrent runs, which continue to serialize
+ * solely via `withEpicMergeLock` before this guard ever executes.
+ *
+ * Breadth trade-off (deliberate): the foreign-lock probe keys on the
+ * OTHER epic's per-epic merge lock, which that run holds for its WHOLE
+ * close flow — so any overlapping story-close of another epic trips this
+ * guard even when that run never actually touches the shared checkout
+ * during the overlap. The refusal is deterministic and loud (throws with
+ * a diagnostic naming the holder pid), never a deadlock (no waiting),
+ * and stale/dead-pid foreign locks are ignored via the pid-liveness
+ * probe. Narrowing the window (a dedicated checkout-phase lock) was
+ * considered and rejected: the coarse refusal is rare, cheap to retry,
+ * and far simpler than a second lock tier.
+ */
+
+import { findForeignActiveEpicLock as defaultFindForeignActiveEpicLock } from '../../epic-merge-lock.js';
+import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+
+const MAX_LISTED_DIRTY_FILES = 20;
+
+function describeForeignLock(foreign) {
+  const acquired = Number.isFinite(foreign.acquiredAt)
+    ? new Date(foreign.acquiredAt).toISOString()
+    : 'an unknown time';
+  return (
+    `[story-close] shared-checkout guard: refusing to touch the shared main checkout — ` +
+    `it is currently held by epic #${foreign.epicId}'s story-close merge phase ` +
+    `(lock ${foreign.filePath}, pid ${foreign.pid}, acquired ${acquired}). ` +
+    `Wait for that epic's story-close run to finish before retrying this merge. ` +
+    `If you have independently confirmed that process is no longer running, remove ` +
+    `the lock file by hand — never force a checkout past a live foreign lock. ` +
+    `See .agents/rules/git-conventions.md § Shared-checkout contention (Story #4460).`
+  );
+}
+
+function listDirtyFiles(porcelainOutput) {
+  // `git status --porcelain` lines are `XY <path>` — a fixed 2-char status
+  // column, a space, then the path. Strip only a trailing `\r` (Windows)
+  // before slicing off that 3-char prefix; trimming the whole line first
+  // would shift the slice offset whenever the status column starts with a
+  // space (the common "unstaged modification" case), truncating the path.
+  const lines = porcelainOutput
+    .split('\n')
+    .map((line) => line.replace(/\r$/, ''))
+    .filter((line) => line.length > 0);
+  const shown = lines
+    .slice(0, MAX_LISTED_DIRTY_FILES)
+    .map((line) => line.slice(3).trim() || line);
+  const overflow = lines.length - shown.length;
+  return overflow > 0
+    ? `${shown.join(', ')}, … (+${overflow} more)`
+    : shown.join(', ');
+}
+
+function describeDirtyCheckout({ cwd, epicId, currentBranch, dirtyFiles }) {
+  return (
+    `[story-close] shared-checkout guard: refusing to check out the epic branch for ` +
+    `epic #${epicId} — the shared main checkout at ${cwd} is dirty (currently on ` +
+    `\`${currentBranch}\`). Dirty files: ${dirtyFiles}. This usually means another ` +
+    `epic's story-close run left uncommitted work in the shared checkout, or a prior ` +
+    `run crashed mid-merge. Resolve manually (stash/commit/reset in ${cwd}) before ` +
+    `retrying. See .agents/rules/git-conventions.md § Shared-checkout contention ` +
+    `(Story #4460).`
+  );
+}
+
+/**
+ * Fail fast when the shared main checkout is not safely available for this
+ * epic's merge-phase `git checkout <epicBranch>` — either because another
+ * epic's story-close merge phase currently holds it (a live foreign lock),
+ * or because it is simply dirty (regardless of whose branch is checked
+ * out). Silent no-op when the checkout is clean and uncontended.
+ *
+ * @param {{
+ *   cwd: string,
+ *   epicId: number|string,
+ *   gitSpawn?: typeof defaultGitSpawn,
+ *   findForeignActiveEpicLock?: typeof defaultFindForeignActiveEpicLock,
+ * }} opts
+ * @throws {Error} with an actionable, story-close-specific diagnostic.
+ */
+/**
+ * Foreign-lock-only variant for the RESUME merge path (Story #4460
+ * follow-up): a resume legitimately re-enters a shared checkout that is
+ * dirty with THIS story's own in-progress merge, so the dirty-tree half
+ * of `assertSharedCheckoutAvailable` would false-positive there. The
+ * cross-epic hazard — another epic's live merge phase holding the
+ * checkout — still applies and is the only probe this variant runs.
+ */
+export function assertNoForeignEpicLock({
+  cwd,
+  epicId,
+  findForeignActiveEpicLock = defaultFindForeignActiveEpicLock,
+}) {
+  const foreign = findForeignActiveEpicLock(epicId, { repoRoot: cwd });
+  if (foreign) {
+    throw new Error(describeForeignLock(foreign));
+  }
+}
+
+export function assertSharedCheckoutAvailable({
+  cwd,
+  epicId,
+  gitSpawn = defaultGitSpawn,
+  findForeignActiveEpicLock = defaultFindForeignActiveEpicLock,
+}) {
+  const foreign = findForeignActiveEpicLock(epicId, { repoRoot: cwd });
+  if (foreign) {
+    throw new Error(describeForeignLock(foreign));
+  }
+
+  const statusRes = gitSpawn(cwd, 'status', '--porcelain');
+  if (statusRes.status !== 0) {
+    // Can't determine dirtiness from here — let the downstream checkout
+    // surface whatever git itself reports rather than guessing.
+    return;
+  }
+  const porcelain = statusRes.stdout || '';
+  if (porcelain.trim().length === 0) return;
+
+  const branchRes = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+  const currentBranch =
+    branchRes.status === 0
+      ? (branchRes.stdout || '').trim() || 'unknown'
+      : 'unknown';
+
+  throw new Error(
+    describeDirtyCheckout({
+      cwd,
+      epicId,
+      currentBranch,
+      dirtyFiles: listDirtyFiles(porcelain),
+    }),
+  );
+}

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -59,7 +59,17 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'friction',
   'notification',
   // Extended set (Story #449 — retro follow-ons)
-  'code-review',
+  // Story #4411 (Epic #4405) — the former `code-review` structured comment
+  // is unified with the former `audit-results` comment into the single
+  // `verification-results` findings contract. `runCodeReview` (the sole code
+  // producer) upserts `verification-results`; the feedback-loop graduators and
+  // the auto-merge integration gate read it. Both the `code-review` and (as of
+  // Story #4412's slim-Epic-close cutover) the `audit-results` markers are
+  // retired here — the Phase 4 standalone lens walk folded into the Phase 5
+  // code-review pass, whose single `verification-results` comment now carries
+  // the Epic-close lens findings. Hard cutover, no dual-shape reader per
+  // `git-conventions.md`.
+  'verification-results',
   'retro',
   'retro-partial',
   'epic-run-state',
@@ -98,14 +108,6 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // operator can correct drift before Phase 8 decomposes from a stale
   // spec. Advisory: the run continues regardless of the report contents.
   'spec-freshness',
-  // Story #2681 — `/deliver` Phase 4 epic-audit helper upserts an
-  // `audit-results` comment on the Epic listing the per-lens findings
-  // returned by the change-set audit pass. The marker was prescribed by
-  // `helpers/epic-audit.md` Step 4 long before it was added to this
-  // registry; without the entry the helper's `post-structured-comment.js`
-  // invocation always failed with "Invalid structured-comment type". One
-  // entry per Epic; re-runs replace prior content.
-  'audit-results',
   // Story #2813 — the per-Task progress writer (since retired under
   // #3157) upserted a `model-attribution` comment on a Task ticket at
   // the moment it transitioned to `agent::executing`, recording which
@@ -160,6 +162,15 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // refuses with the claim age. One entry per Epic; re-acquires upsert
   // in place.
   'plan-lease',
+  // Story #4415 (Epic #4406) — the feedback-loop graduators
+  // (`audit-results-graduator.js` / `retro-proposals-graduator.js`) upsert a
+  // `cross-repo-deferred` comment on the Epic listing findings that route
+  // to a different repository and were therefore not filed here. Replaces
+  // the prior log-line-only trace so the deferral survives the finalize
+  // run as a durable, operator-visible record. Discriminated by a
+  // `graduator="audit-results|code-review"` attr so the two graduators
+  // upsert independent comments; re-runs upsert in place.
+  'cross-repo-deferred',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;