mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/git/sync-from-base.js

@@ -12,18 +12,38 @@
  * merge and reduces (does not eliminate) the residual race-with-merge
  * window. The merge queue is the proper fix for the residual race.
  *
- * Why merge (not rebase): Story branches are pushed and reviewed across
- * iterations of the watch + fix loop; a rebase would force-push and risk
- * losing in-flight reviewer context. The merge commit is squashed away
- * when the PR lands, so the cosmetic cost is zero.
+ * Why merge, not rebase (Story #5267 — settled, do not re-open):
+ *
+ *   1. Mandrel states no rebase rule anywhere. `git-conventions.md`
+ *      mandates branch shapes and commit subjects and is silent on how a
+ *      branch takes on base commits, so there is no convention to honour
+ *      here — only a trade-off to pick.
+ *   2. Story branches are pushed and reviewed across iterations of the
+ *      watch + fix loop. A rebase force-pushes, discarding in-flight
+ *      reviewer context and any review state pinned to the old SHAs.
+ *   3. A rebase would NOT save the pre-push capture stamp people reach
+ *      for it to save. The stamp is keyed on the tree, and rebasing onto
+ *      a moved base changes the tree exactly as merging it does — both
+ *      invalidate the stamp, so the credit argument is a wash. The real
+ *      remedy is the `changedPaths` reporting below: say out loud when
+ *      the sync spent the stamp, rather than change how it is spent.
+ *
+ * The merge commit is squashed away when the PR lands, so the cosmetic
+ * cost is zero.
  *
  * Outcomes (`{ synced, kind, ... }`):
  *
- *   - `{ synced: true, kind: 'noop-already-current' }` — `origin/<base>`
- *     is already an ancestor of HEAD; nothing to do.
- *   - `{ synced: true, kind: 'fast-forward' }` — merge fast-forwarded.
- *   - `{ synced: true, kind: 'merge-commit' }` — non-trivial merge
- *     succeeded; a merge commit landed on the active branch.
+ *   - `{ synced: true, kind: 'noop-already-current', changedPaths: [] }`
+ *     — `origin/<base>` is already an ancestor of HEAD; nothing to do.
+ *   - `{ synced: true, kind: 'fast-forward', changedPaths }` — merge
+ *     fast-forwarded.
+ *   - `{ synced: true, kind: 'merge-commit', changedPaths }` — non-trivial
+ *     merge succeeded; a merge commit landed on the active branch.
+ *
+ * `changedPaths` is the tracked paths the sync brought into the branch —
+ * `git diff --name-only <pre-merge HEAD> HEAD` — and is what lets a caller
+ * tell a sync that spent a pre-push capture stamp from one that did not.
+ * It is `[]` for every non-mutating and every failing outcome.
  *   - `{ synced: false, kind: 'fetch-failed', stderr }` — `git fetch`
  *     could not retrieve `origin/<base>`. No mutation occurred.
  *   - `{ synced: false, kind: 'conflict', conflictFiles }` — merge
@@ -32,17 +52,102 @@
  *   - `{ synced: false, kind: 'merge-failed', stderr }` — merge exited
  *     non-zero for a reason other than a parseable conflict (rare; treat
  *     as a hard blocker on the caller's side).
+ *   - `{ synced: false, kind: 'merge-driver-missing', stderr }` — the
+ *     worktree's `.gitattributes` routes `baselines/*.json` through the
+ *     `mandrel-baseline` merge driver and this clone has no
+ *     `merge.mandrel-baseline.driver` config, so git would text-merge
+ *     generated baselines. Nothing was fetched or merged (Story #5277).
  *
  * The helper does not mutate any ticket state, post comments, or write
  * to anything other than the worktree's git refs / index. Callers own
  * the recovery surface.
  */
 
+import {
+  BASELINE_MERGE_DRIVER_CONFIG_KEY,
+  BASELINE_MERGE_DRIVER_REMEDY,
+  probeBaselineMergeDriver,
+} from '../bootstrap/baseline-merge-driver.js';
 import {
   gitFetchWithRetry as defaultGitFetchWithRetry,
   gitSpawn as defaultGitSpawn,
 } from '../git-utils.js';
 
+/**
+ * Refuse the sync when the baseline merge driver is declared but unregistered
+ * (Story #5277). `probeBaselineMergeDriver` owns the two-part question and why
+ * each half matters; this is where the answer becomes a refusal.
+ *
+ * Base-sync is the one place the failure is catchable before it happens: it is
+ * the merge that runs unattended, immediately before the push, on exactly the
+ * files a concurrent sibling Story most often also refreshed. Refusing costs
+ * one operator command; proceeding costs a silently wrong baseline on `main`
+ * that nothing downstream re-derives.
+ *
+ * @param {string} cwd
+ * @param {typeof defaultGitSpawn} gitSpawn
+ * @returns {{ synced: false, kind: 'merge-driver-missing', stderr: string, remedy: string }|null}
+ */
+function refuseWithoutMergeDriver(cwd, gitSpawn) {
+  const { declared, command } = probeBaselineMergeDriver({
+    projectRoot: cwd,
+    runGit: (args) => gitSpawn(cwd, ...args),
+  });
+  if (!declared || command.length > 0) return null;
+  return {
+    synced: false,
+    kind: 'merge-driver-missing',
+    stderr:
+      `.gitattributes routes baselines/*.json through the mandrel-baseline merge ` +
+      `driver, but ${BASELINE_MERGE_DRIVER_CONFIG_KEY} is unset in this clone. ` +
+      'Merging origin now would text-merge generated baselines, which conflicts on ' +
+      'the generatedAt stamp and can splice rows neither branch scored. Register the ' +
+      `driver, then re-run:\n  ${BASELINE_MERGE_DRIVER_REMEDY}\n` +
+      '  (or: npm run baselines:merge-driver)',
+    remedy: BASELINE_MERGE_DRIVER_REMEDY,
+  };
+}
+
+/**
+ * Resolve the current HEAD SHA, or `null` when git cannot answer.
+ *
+ * @param {typeof defaultGitSpawn} gitSpawn
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function readHead(gitSpawn, cwd) {
+  const head = gitSpawn(cwd, 'rev-parse', 'HEAD');
+  if (head.status !== 0) return null;
+  const sha = (head.stdout ?? '').toString().trim();
+  return sha.length > 0 ? sha : null;
+}
+
+/**
+ * The tracked paths that differ between `fromSha` and the current HEAD.
+ *
+ * Returns `[]` when the pre-merge SHA could not be read or the diff itself
+ * failed. That is deliberately the quiet answer: the only consumer is the
+ * caller's "your capture stamp may be dead" warning, and manufacturing that
+ * warning out of a failed probe would cry wolf on every sync in a repo where
+ * `rev-parse` is broken — a condition the merge one line earlier would
+ * already have failed on.
+ *
+ * @param {typeof defaultGitSpawn} gitSpawn
+ * @param {string} cwd
+ * @param {string|null} fromSha
+ * @returns {string[]}
+ */
+function diffPaths(gitSpawn, cwd, fromSha) {
+  if (!fromSha) return [];
+  const diff = gitSpawn(cwd, 'diff', '--name-only', fromSha, 'HEAD');
+  if (diff.status !== 0) return [];
+  return (diff.stdout ?? '')
+    .toString()
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
 /**
  * Sync the active branch in `cwd` against `origin/<baseBranch>`. See
  * the module docstring for the full outcome envelope.
@@ -64,9 +169,9 @@ import {
  *   tests.
  *
  * @returns {Promise<
- *   | { synced: true, kind: 'noop-already-current' }
- *   | { synced: true, kind: 'fast-forward' }
- *   | { synced: true, kind: 'merge-commit' }
+ *   | { synced: true, kind: 'noop-already-current', changedPaths: string[] }
+ *   | { synced: true, kind: 'fast-forward', changedPaths: string[] }
+ *   | { synced: true, kind: 'merge-commit', changedPaths: string[] }
  *   | { synced: false, kind: 'fetch-failed', stderr: string }
  *   | { synced: false, kind: 'conflict', conflictFiles: string[] }
  *   | { synced: false, kind: 'merge-failed', stderr: string }
@@ -88,6 +193,12 @@ export async function syncBranchFromBase({
     );
   }
 
+  const driverGap = refuseWithoutMergeDriver(cwd, gitSpawn);
+  if (driverGap) {
+    log('SYNC', driverGap.stderr);
+    return driverGap;
+  }
+
   log('SYNC', `Fetching origin/${baseBranch}...`);
   const fetch = await gitFetchWithRetry(cwd, 'origin', baseBranch);
   if (fetch.status !== 0) {
@@ -111,9 +222,14 @@ export async function syncBranchFromBase({
   );
   if (originAlreadyMerged.status === 0) {
     log('SYNC', `origin/${baseBranch} already merged into HEAD — no-op.`);
-    return { synced: true, kind: 'noop-already-current' };
+    return { synced: true, kind: 'noop-already-current', changedPaths: [] };
   }
 
+  // Pin the pre-merge HEAD so a successful sync can name what it brought
+  // in. Read BEFORE the merge, because afterwards the only handle on the
+  // old tree is this SHA.
+  const preMergeHead = readHead(gitSpawn, cwd);
+
   const headBehindOrigin = gitSpawn(
     cwd,
     'merge-base',
@@ -134,6 +250,7 @@ export async function syncBranchFromBase({
     return {
       synced: true,
       kind: willFastForward ? 'fast-forward' : 'merge-commit',
+      changedPaths: diffPaths(gitSpawn, cwd, preMergeHead),
     };
   }
 

package/.agents/scripts/lib/github/framework-repo.js

@@ -1,6 +1,152 @@
 /**
- * Canonical framework repository slug used by follow-up / graduator
- * paths when the consumer config does not supply owner/repo.
+ * framework-repo.js — the follow-up **ownership routing** SSOT: which
+ * repository a finding, a retro proposal, or a CI-gap intake issue is filed
+ * in, and what to say when that question has no answer.
+ *
+ * ## Three buckets, not two
+ *
+ * A defect surfaced by one repository's CI is not necessarily that
+ * repository's to fix. Ownership splits three ways:
+ *
+ *   - `consumer`  — the repo the run is standing in (`github.owner`/`repo`).
+ *   - `framework` — the Mandrel framework itself
+ *     (`github.followUpRepos.framework`, defaulted to the mirror constant).
+ *   - `platform`  — a shared platform / infrastructure repo that neither of
+ *     the other two owns: a shared base config, a runner fleet, a
+ *     cross-repo toolchain (`github.followUpRepos.platform`, **no default**
+ *     — nothing can guess a shared repo's slug).
+ *
+ * ## Why there is no `?? currentRepo` fallback
+ *
+ * The two-bucket predecessor resolved a framework-tagged item with
+ * `frameworkRepo ? frameworkRepo : currentRepo`. When the config key was
+ * absent that expression filed framework-owned work into the **consumer's**
+ * repo while the rendered retro claimed it went to the framework repo — a
+ * silent mis-file, recorded in `retro-proposals-graduator.js`'s own file-top
+ * comment. The failure was invisible in this repository precisely because
+ * consumer === framework here.
+ *
+ * So an unresolvable bucket is a first-class outcome, never a fallback:
+ * `routeOwnership` returns `routable: false` plus the `missingKey` that
+ * would fix it, and every caller must decide **out loud** what to do with
+ * that — file locally and say so in the body (the CI-gap filer), or defer
+ * and surface it where an operator will see it (the graduators). What no
+ * caller may do is route it somewhere plausible and stay quiet.
  */
 
+/**
+ * Canonical framework repository slug, used when the consumer config does
+ * not supply `github.followUpRepos.framework`. The `framework` bucket is the
+ * one bucket with a knowable default: it is this framework.
+ */
 export const DEFAULT_FRAMEWORK_REPO = 'dsj1984/mandrel';
+
+/** The closed ownership-bucket set. */
+export const OWNERSHIP_BUCKETS = Object.freeze([
+  'consumer',
+  'framework',
+  'platform',
+]);
+
+/**
+ * The `.agentrc.json` key behind each bucket, quoted verbatim when a bucket
+ * is unroutable so the operator is told which key to set rather than that
+ * "routing failed".
+ */
+const OWNERSHIP_CONFIG_KEYS = Object.freeze({
+  consumer: 'github.owner / github.repo',
+  framework: 'github.followUpRepos.framework',
+  platform: 'github.followUpRepos.platform',
+});
+
+/**
+ * Parse an `"<owner>/<repo>"` slug into `{ owner, repo }`, or `null` when the
+ * slug is absent, empty, or malformed. A `null` return is the signal an
+ * unroutable bucket is built from — never a reason to substitute another
+ * repo.
+ *
+ * @param {string|null|undefined} slug
+ * @returns {{ owner: string, repo: string } | null}
+ */
+export function parseRepoSlug(slug) {
+  if (typeof slug !== 'string') return null;
+  const parts = slug.trim().split('/');
+  if (parts.length !== 2) return null;
+  const [owner, repo] = parts;
+  if (!owner || !repo) return null;
+  return { owner, repo };
+}
+
+/**
+ * Render a `{ owner, repo }` pair back to its slug, or `null` when the pair
+ * is absent/malformed.
+ *
+ * @param {{ owner?: string, repo?: string }|null|undefined} repo
+ * @returns {string|null}
+ */
+export function formatRepoSlug(repo) {
+  if (!repo || typeof repo !== 'object') return null;
+  const { owner, repo: name } = /** @type {{owner?: string, repo?: string}} */ (
+    repo
+  );
+  if (typeof owner !== 'string' || typeof name !== 'string') return null;
+  if (!owner.trim() || !name.trim()) return null;
+  return `${owner.trim()}/${name.trim()}`;
+}
+
+/**
+ * Resolve every ownership bucket from a resolved `.agentrc` config.
+ *
+ * `framework` falls back to {@link DEFAULT_FRAMEWORK_REPO}; `platform` has no
+ * default and stays `null` when unconfigured; `consumer` is `null` when
+ * `github.owner`/`github.repo` are unset. A `null` bucket is an honest
+ * "unknown", which {@link routeOwnership} turns into a named, reportable
+ * outcome.
+ *
+ * @param {object} [config] — resolved `.agentrc` config.
+ * @returns {{ consumer: ({owner: string, repo: string}|null), framework: ({owner: string, repo: string}|null), platform: ({owner: string, repo: string}|null) }}
+ */
+export function resolveOwnershipRepos(config) {
+  const github = config?.github ?? {};
+  const followUp = github?.followUpRepos ?? {};
+  const owner = typeof github.owner === 'string' ? github.owner.trim() : '';
+  const repo = typeof github.repo === 'string' ? github.repo.trim() : '';
+  return {
+    consumer: owner && repo ? { owner, repo } : null,
+    framework:
+      parseRepoSlug(followUp.framework) ??
+      parseRepoSlug(DEFAULT_FRAMEWORK_REPO),
+    platform: parseRepoSlug(followUp.platform),
+  };
+}
+
+/**
+ * Route one ownership bucket to the repository its work belongs in.
+ *
+ * Total: an unknown bucket, an absent repos map, and an unconfigured bucket
+ * all resolve to `routable: false` with the `missingKey` that would fix it —
+ * never to a substituted repository.
+ *
+ * @param {object} opts
+ * @param {string} opts.bucket — one of {@link OWNERSHIP_BUCKETS}.
+ * @param {{consumer?: object|null, framework?: object|null, platform?: object|null}} opts.repos
+ *   — resolved buckets, from {@link resolveOwnershipRepos} or assembled by a
+ *   caller that already holds the repo objects.
+ * @param {{owner: string, repo: string}|null} [opts.currentRepo] — the repo
+ *   the run is standing in, used only to report `crossRepo`.
+ * @returns {{ bucket: string, routedRepo: ({owner: string, repo: string}|null), routable: boolean, missingKey: (string|null), crossRepo: boolean }}
+ */
+export function routeOwnership({ bucket, repos, currentRepo = null } = {}) {
+  const known = OWNERSHIP_BUCKETS.includes(bucket);
+  const routedRepo = known ? (repos?.[bucket] ?? null) : null;
+  const routable = Boolean(routedRepo?.owner && routedRepo?.repo);
+  const missingKey = routable
+    ? null
+    : (OWNERSHIP_CONFIG_KEYS[bucket] ?? `unknown ownership bucket "${bucket}"`);
+  const crossRepo =
+    routable &&
+    Boolean(currentRepo) &&
+    (routedRepo.owner !== currentRepo.owner ||
+      routedRepo.repo !== currentRepo.repo);
+  return { bucket, routedRepo, routable, missingKey, crossRepo };
+}

package/.agents/scripts/lib/label-constants.js

@@ -119,7 +119,11 @@ export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
  * loop). `meta::framework-gap` is applied to issues that surface a defect or
  * missing capability in the framework itself; `meta::consumer-improvement`
  * is applied to issues that surface improvements to a consumer project
- * (workflow tweaks, ergonomic asks, doc polish). The `/mandrel-plan` Phase 0
+ * (workflow tweaks, ergonomic asks, doc polish); `meta::platform-gap` is
+ * applied to issues owned by neither — a shared base config, a runner fleet,
+ * a cross-repo toolchain. The three mirror the ownership buckets in
+ * `lib/github/framework-repo.js`, so a routed filing's label and its
+ * destination repository cannot disagree. The `/mandrel-plan` Phase 0
  * fetcher (see `lib/feedback-loop/prior-feedback-fetcher.js`) reads open
  * issues carrying either label and surfaces them to the planner so retro
  * signals are routed into durable substrates rather than lost in chat.
@@ -127,6 +131,7 @@ export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
 export const META_LABELS = {
   FRAMEWORK_GAP: 'meta::framework-gap',
   CONSUMER_IMPROVEMENT: 'meta::consumer-improvement',
+  PLATFORM_GAP: 'meta::platform-gap',
 };
 
 /**

package/.agents/scripts/lib/observability/source-classifier.js

@@ -101,6 +101,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-lifecycle-lint.js',
   'check-pinned-override-notes.js',
   'check-schema-references.js',
+  'check-test-portability.js',
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',
   'check-workflow-citations.js',
@@ -114,6 +115,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'diagnose.js',
   'drain-pending-cleanup.js',
   'evidence-gate.js',
+  'file-ci-gap.js',
   'generate-config-docs.js',
   'generate-lens-checklists.js',
   'generate-skills-index.js',

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -82,8 +82,16 @@ function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
   if (raw === null) return null;
   try {
     return JSON.parse(raw);
-  } catch {
-    return null;
+  } catch (cause) {
+    // Story #5277 — the same distinction one line above, applied to the
+    // second way a base read fails. `null` here means "no baseline at the base
+    // ref", which empties the head-vs-base arm on purpose; an UNPARSEABLE base
+    // blob is a read that failed, and reporting it as "no base" made a
+    // corrupted or half-merged `baselines/*.json` on the base branch report
+    // zero regressions at exit 0. Text-merged baselines are exactly how such a
+    // blob gets onto the base branch, which is the failure this Story removes
+    // upstream — this arm is what stops it being silent when it happens anyway.
+    throw buildBaseReadError({ kind, ref: scope.ref, file: rel, cause });
   }
 }
 

package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js

@@ -96,23 +96,69 @@ function resolveRefreshTrigger({ kind, gateBlock, cmp, cwd, env }) {
 }
 
 /**
- * Read the baseline rows as of one refresh commit. Returns `null` — never
- * throws and never a partial row set — when the blob is absent, unreadable or
- * unparseable at that SHA. The caller treats `null` as "this commit
- * acknowledges nothing", which keeps the ratchet at full strength rather than
- * acknowledging on a guess.
+ * Read the baseline rows as of one git ref.
+ *
+ * Returns `null` — never throws and never a partial row set — when the blob is
+ * unreadable or unparseable at that ref. The caller treats `null` as "this
+ * commit acknowledges nothing", which keeps the ratchet at full strength rather
+ * than acknowledging on a guess.
+ *
+ * A blob that is genuinely ABSENT at the ref reads as `{ rows: [] }`, not
+ * `null`. The distinction only matters for the `sha^` read below: the commit
+ * that CREATES a baseline has no blob at its parent, and treating that as
+ * unreadable would make the first refresh of any kind acknowledge nothing.
+ * `readBaseFromGit` already draws exactly this line — `null` for git's exit
+ * 128 "path does not exist in this revision", a throw for everything else — so
+ * the two cases are distinguishable rather than guessed at.
+ *
+ * @returns {{ rows: Array<object> }|null}
  */
-function readRowsAtCommit(sha, baselinePath, cwd) {
+function readRowsAtRef(ref, baselinePath, cwd) {
   let raw;
   try {
-    raw = readBaseFromGit(sha, baselinePath, { cwd });
+    raw = readBaseFromGit(ref, baselinePath, { cwd });
   } catch {
     return null;
   }
-  if (raw === null) return null;
+  if (raw === null) return { rows: [] };
   try {
     const payload = JSON.parse(raw);
-    return Array.isArray(payload?.rows) ? payload.rows : null;
+    return Array.isArray(payload?.rows) ? { rows: payload.rows } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which row identities did the tagged commit itself REWRITE (Story #5277)?
+ *
+ * This is the half Story #5179 left open. It scoped the acknowledgment to the
+ * rows present in the baseline blob *at* the tagged commit — but a blob is a
+ * whole-file snapshot, so it also contains every row an EARLIER, untagged
+ * commit on the same branch lowered. Such a row is present at the refresh
+ * commit and unchanged at head, so it classified as `ok` and was acknowledged
+ * by a commit that never touched it. The observed shape: a branch lowers a
+ * maintainability row while refactoring, later refreshes an unrelated CRAP row
+ * with a `baseline-refresh:` commit, and the first regression is waved through.
+ *
+ * Diffing `sha^ → sha` is what makes the acknowledgment a statement about the
+ * COMMIT rather than about the branch's accumulated state. No tolerance is
+ * applied: any movement at all means the commit re-scored that identity, which
+ * is the only question being asked here.
+ *
+ * @returns {Set<string>|null} null when the diff is unusable, which
+ *   acknowledges nothing from this commit.
+ */
+function keysTouchedByCommit({ mod, rowsAtSha, rowsAtParent }) {
+  try {
+    const result = mod.compare({ rows: rowsAtSha }, { rows: rowsAtParent });
+    return new Set(
+      [
+        ...(result?.regressions ?? []),
+        ...(result?.improvements ?? []),
+        ...(result?.additions ?? []),
+      ].map((entry) => entry.key),
+    );
   } catch {
     return null;
   }
@@ -179,6 +225,11 @@ function classifyAgainstRefresh({ mod, headRows, refreshRows, tolerance }) {
  *      lands in `drifted`. Drift from commits landing AFTER the refresh is what
  *      "the baseline commit must be the branch's last score-moving commit" asks
  *      for by convention and nothing enforced.
+ *   3. **The commit actually rewrote it** (Story #5277) — `keysTouchedByCommit`
+ *      diffs `sha^ → sha`. Tests 1 and 2 both read the blob AT the commit,
+ *      which is a whole-file snapshot and therefore also carries rows an
+ *      earlier untagged commit lowered; those rows passed both tests without
+ *      the tagged commit having touched them.
  *
  * Fails closed at every step: an unreadable blob, a missing `compare`, or a
  * classifier that throws contributes nothing, so those regressions stand.
@@ -212,17 +263,24 @@ function acknowledgeableKeys({
   // state the branch is asking to be held to.
   const decided = new Set();
   for (const { sha } of refreshCommits) {
-    const refreshRows = readRowsAtCommit(sha, baselinePath, cwd);
-    if (refreshRows === null) continue;
+    const atSha = readRowsAtRef(sha, baselinePath, cwd);
+    const atParent = readRowsAtRef(`${sha}^`, baselinePath, cwd);
+    if (atSha === null || atParent === null) continue;
+    const touched = keysTouchedByCommit({
+      mod,
+      rowsAtSha: atSha.rows,
+      rowsAtParent: atParent.rows,
+    });
+    if (touched === null) continue;
     const verdict = classifyAgainstRefresh({
       mod,
       headRows,
-      refreshRows,
+      refreshRows: atSha.rows,
       tolerance,
     });
     if (verdict === null) continue;
     for (const key of verdict.ok) {
-      if (decided.has(key)) continue;
+      if (decided.has(key) || !touched.has(key)) continue;
       decided.add(key);
       acknowledgeable.add(key);
     }
@@ -264,10 +322,12 @@ function logAcknowledgment({ kind, reasons, acknowledged, kept }) {
  *
  * The two trigger arms are scoped differently, deliberately:
  *
- * - **Commit tag** — scoped to the rows the tagged commits actually refreshed,
+ * - **Commit tag** — scoped to the rows the tagged commits actually rewrote,
  *   per `acknowledgeableKeys`. Before Story #5179 this cleared every regression
  *   in the range, so a branch merged carrying a stale row and the ratchet ran
- *   loose on that file; the failure recurred six times.
+ *   loose on that file; the failure recurred six times. Story #5277 closed the
+ *   remainder: the scoping read the blob at the tagged commit, which still
+ *   carried rows an earlier untagged commit had lowered.
  * - **Env parity** (`<KIND>_REFRESH=1`) — stays whole-run. There is no commit to
  *   anchor row-scoping to, and setting the variable is an explicit, deliberate
  *   operator act rather than a signal inferred from history.