yadflow 3.13.0 → 3.13.1

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [3.13.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.0...v3.13.1) (2026-07-29)
+
+
+### Bug Fixes
+
+* **checks:** apply the Task-trailer rule to the thread gates too ([18aed8d](https://github.com/abdelrahmannasr/yadflow/commit/18aed8df958718483fe929cea84275ca86ae67be)), closes [#157](https://github.com/abdelrahmannasr/yadflow/issues/157)
+* **checks:** do not build a /-rooted lock path when product-repo is absent ([0d2a214](https://github.com/abdelrahmannasr/yadflow/commit/0d2a214a30c7fc31ad087fa127277b50637a00de))
+* **checks:** keep product-repo resolution backward-compatible and loud ([4c00c92](https://github.com/abdelrahmannasr/yadflow/commit/4c00c928642fbab4517805be14a1c6926f41b84c)), closes [#149](https://github.com/abdelrahmannasr/yadflow/issues/149) [#149](https://github.com/abdelrahmannasr/yadflow/issues/149)
+* **checks:** resolve link.md product-repo the same way in every gate ([47c9b30](https://github.com/abdelrahmannasr/yadflow/commit/47c9b30548153ef5be607cf760c3e9ec9e73699f)), closes [#149](https://github.com/abdelrahmannasr/yadflow/issues/149)
+* **checks:** spec-link resolves a Task trailer even on a maintenance commit ([d24dd83](https://github.com/abdelrahmannasr/yadflow/commit/d24dd83abadc63bb00e8c8d6d7c6008e32344db8)), closes [#157](https://github.com/abdelrahmannasr/yadflow/issues/157)
+* **doctor:** refuse a decorative contract lock, and report a gate that went stale ([1ee3296](https://github.com/abdelrahmannasr/yadflow/commit/1ee3296dbddfdd308949b8013b3bf678f638fc80)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** bound the review-branch probe so it can never hang gate open ([afa5416](https://github.com/abdelrahmannasr/yadflow/commit/afa54167efd5879537c4bc19ab29531fe08ed31b))
+* **gate:** hash the contract surface exactly as the documented recipe does ([f29e781](https://github.com/abdelrahmannasr/yadflow/commit/f29e78183b92c7baf33b46dbdfa7a4776aa06e4e)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** keep the recorded PR entry when --pr names that same PR ([b1febe1](https://github.com/abdelrahmannasr/yadflow/commit/b1febe184278109f0bafc2968648da362d68483a))
+* **gate:** make a merged review PR reachable by hand ([4ccbd17](https://github.com/abdelrahmannasr/yadflow/commit/4ccbd1736640935175d63bac15a01a94e381b44e)), closes [#158](https://github.com/abdelrahmannasr/yadflow/issues/158)
+* **gate:** never drop a done step's approval record on re-sync ([1a5e434](https://github.com/abdelrahmannasr/yadflow/commit/1a5e4348d00edd4e775a735a49fc0a86a3f0e391)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** re-bind approvals recorded before PR provenance existed ([6b7e816](https://github.com/abdelrahmannasr/yadflow/commit/6b7e816638a329d9365c6e727b2c12debdbd24aa)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156) [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** re-sync a re-opened review so its approvals re-bind ([28eabd2](https://github.com/abdelrahmannasr/yadflow/commit/28eabd222214ad2af7d18ef20c56795c9eb171d1)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** require the review branch on origin, and check before writing state ([27f0d92](https://github.com/abdelrahmannasr/yadflow/commit/27f0d92ce680c26df6ea7ff6510879a11f05d00f)), closes [#158](https://github.com/abdelrahmannasr/yadflow/issues/158)
+* **gate:** stop a done-step re-sync from churning the ledger ([68462a6](https://github.com/abdelrahmannasr/yadflow/commit/68462a622753c0d30b458d22d9e1ad890ad8e61f)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+* **gate:** validate --pr and confirm it names this artifact's review ([f5d7773](https://github.com/abdelrahmannasr/yadflow/commit/f5d7773da474784a43cc3e24298da94c8f38bbdb)), closes [#7](https://github.com/abdelrahmannasr/yadflow/issues/7) [#158](https://github.com/abdelrahmannasr/yadflow/issues/158)
+* **hub-bridge:** serialize the GitLab gate-sync job ([4294979](https://github.com/abdelrahmannasr/yadflow/commit/4294979f80cb4491d074fe27e74f9af454a2f62a)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
+
 # [3.13.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.2...v3.13.0) (2026-07-14)
 
 

package/bin/yad.mjs

@@ -74,8 +74,13 @@ ${c.bold('Where am I / what next')}
                                        --undo reverses it until the stories review opens
 
 ${c.bold('Review gate (front half)')}
-  yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
-  yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
+  yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review. The review
+                                       branch must already be on origin (it is never created here)
+  yad gate sync <epic> [artifact] [--pr <n>]
+                                       Pull PR state -> ledger; advance on approved+resolved+merged.
+                                       With no recorded PR, resolves it from the review branch; --pr
+                                       names one (and overrides a stale recorded pointer). Advisory
+                                       in bridge mode — there, recover with 'yad gate ci' below
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
   yad gate repair <epic> [--push]      Close an author step stranded behind a passed review gate
@@ -272,7 +277,7 @@ async function main() {
       // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
       // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
       if (action === 'open') await gateOpen(o.dir, { epic, artifact });
-      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
+      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, number: o.pr, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
       else if (action === 'repair') await gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });

package/cli/doctor.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
 import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS } from './manifest.mjs';
-import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants } from './epic-state.mjs';
+import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants, contractSurfaceHash, artifactHash } from './epic-state.mjs';
 import { loadDebt } from './thread.mjs';
 import { gitHead, insideWorkspace } from './setup.mjs';
 import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
@@ -280,6 +280,116 @@ export function ciTagsChecks(checks, root, hub, registry) {
   }
 }
 
+// Is `.sdlc/contract-lock.json` still the hash of the surface it claims to lock? The lock is what the
+// spec pins and what contract-check compares a code repo's slice against, but nothing ever verified it
+// against the live contract.md — so a surface edited without a re-lock (or locked with a different
+// recipe) read as "locked" while binding nothing. FAIL on a mismatch: a decorative lock is worse than
+// none, because everyone downstream treats it as proof.
+//
+// Two shapes (yad-change references/triage.md): a SURFACE lock, verified against this epic's own
+// contract.md, and a POINTER lock — a change-epic that inherited architecture, which carries no
+// contract.md at all and instead copies the parent's hash verbatim. Its integrity property is that the
+// copy still equals what the referenced lock holds, so verify it there.
+function contractLockCheck(checks, root, epic, ledger) {
+  const id = `epic:${epic}:contract-lock`;
+  const lock = ledger.contractLock;
+  const epicDir = epicRoot(root, epic);
+  // An epic that has not reached the lock yet simply has no lock file — that is the normal pre-lock
+  // state and stays silent. A lock file that EXISTS but carries no usable hash is the opposite: it is
+  // the decorative lock this check was added to catch, so it must never read as "not locked yet".
+  // `readJSONStrict` yields null both for an absent file and for one holding literal `null`, so ask the
+  // filesystem — the second is a malformed lock, not a missing one.
+  if (lock === null && !exists(ledger.files.contractLock)) return;
+  const stored = typeof lock?.hash === 'string' && /^sha256:[0-9a-f]{64}$/.test(lock.hash) ? lock.hash : null;
+  if (!stored) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract-lock.json exists but carries no usable sha256 hash`,
+      're-lock the surface (yad-architecture Step 5) or delete the file — a lock nobody can verify is worse than none');
+    return;
+  }
+  const short = (h) => `${h.slice(0, 19)}…`;
+
+  if (lock.inheritedFrom || lock.ref) {
+    // The ref is repo-controlled text, so keep it inside this hub's epics/ — a lock file must not be
+    // able to point the check at arbitrary JSON elsewhere on disk.
+    const epicsDir = path.join(root, 'epics');
+    const refPath = path.resolve(path.join(epicDir, '.sdlc'), lock.ref || `../../${lock.inheritedFrom}/.sdlc/contract-lock.json`);
+    if (refPath !== epicsDir && !refPath.startsWith(epicsDir + path.sep)) {
+      check(checks, id, 'epics', 'fail',
+        `${epic}: pointer-lock ref '${lock.ref}' resolves outside epics/`,
+        'a pointer-lock must reference another epic in this hub — fix `ref` (yad-change writes ../../EP-<parent>/.sdlc/contract-lock.json)');
+      return;
+    }
+    const parent = readJSON(refPath, null);
+    if (!parent || typeof parent.hash !== 'string') {
+      check(checks, id, 'epics', 'fail',
+        `${epic}: pointer-lock references ${lock.inheritedFrom || lock.ref}, whose contract-lock.json is missing or has no hash`,
+        're-thread the change-epic (yad-change) so it points at a real parent lock');
+      return;
+    }
+    if (parent.hash !== stored) {
+      check(checks, id, 'epics', 'fail',
+        `${epic}: pointer-lock pins ${short(stored)} but ${lock.inheritedFrom || 'its parent'} now locks ${short(parent.hash)}`,
+        'the inherited surface was re-locked upstream — re-copy the parent hash, or re-author architecture in this epic');
+      return;
+    }
+    // A pointer-lock epic has no contract.md by construction (the surface physically cannot drift).
+    // One that DOES have a contract.md is a change-epic that re-authored architecture but left the
+    // inherited fields behind, so verify the live surface as well rather than trusting the pointer.
+    if (!exists(path.join(epicDir, 'contract.md'))) {
+      check(checks, id, 'epics', 'ok', `${epic}: pointer-lock matches ${lock.inheritedFrom || 'its parent'} (${short(stored)})`);
+      return;
+    }
+    check(checks, `${id}:inherited`, 'epics', 'warn',
+      `${epic}: lock is marked inherited from ${lock.inheritedFrom || lock.ref} but this epic has its own contract.md`,
+      're-authored architecture? drop `inheritedFrom`/`ref` and re-lock against this epic\'s surface');
+    // and fall through to verify the live surface too
+  }
+
+  if (!exists(path.join(epicDir, 'contract.md'))) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract-lock.json pins ${short(stored)} but there is no contract.md to lock`,
+      'restore contract.md, or record the lock as inherited (`inheritedFrom` + `ref`) if this epic threads off a parent');
+    return;
+  }
+  const current = contractSurfaceHash(epicDir);
+  if (current === null) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract-lock.json pins ${short(stored)} but contract.md has no readable CONTRACT-SURFACE block`,
+      'restore the BEGIN/END markers around the surface, then re-lock (see yad-architecture Step 5)');
+    return;
+  }
+  if (current !== stored) {
+    check(checks, id, 'epics', 'fail',
+      `${epic}: contract surface drifted from its lock — contract.md hashes ${short(current)}, contract-lock.json pins ${short(stored)}`,
+      'the surface changed without a re-lock: re-run the yad-architecture Step 5 recipe and re-open the architecture gate');
+    return;
+  }
+  check(checks, id, 'epics', 'ok', `${epic}: contract surface matches its lock (${short(stored)})`);
+}
+
+// A review step that is `done` but whose approvals no longer bind to the artifact as it stands today.
+// The gate is deliberately one-way — nothing pulls a chain backward once work is built on it — so the
+// only way this surfaces is if something reports it. `gate sync` records the gap on the step it is
+// syncing; this reports it for the whole epic, so a re-locked surface that was never re-approved is
+// visible in the one command people run when something looks wrong. WARN, not FAIL: the state is a
+// fact about history, and the fix (re-open the review) is a human decision.
+function staleGateCheck(checks, root, epic, ledger) {
+  const epicDir = epicRoot(root, epic);
+  for (const s of ledger.state.steps) {
+    if (s.type !== 'review+approve' || s.status !== 'done' || s.inherited || s.skipped) continue;
+    const cur = artifactHash(epicDir, s.artifact);
+    if (!cur) continue; // nothing to bind to (no locked surface / incomplete set) — not a staleness claim
+    const forStep = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved');
+    if (!forStep.length) continue; // solo mode waives approvals entirely; absence is not staleness
+    const live = forStep.filter((a) => !a.artifactHash || a.artifactHash === cur);
+    if (live.length) continue;
+    check(checks, `epic:${epic}:${s.id}:stale`, 'epics', 'warn',
+      `${epic}: ${s.id} is done, but all ${forStep.length} approval(s) are bound to an older ${s.artifact}`,
+      'the artifact changed after it was approved — re-open the review (a fresh PR/MR) so the record matches what shipped');
+  }
+}
+
 export function epicChecks(checks, root) {
   const epicsDir = path.join(root, 'epics');
   if (!exists(epicsDir)) return;
@@ -308,6 +418,8 @@ export function epicChecks(checks, root) {
         if (openPr) check(checks, `epic:${e}:migration`, 'epics', 'warn',
           `${e}: an open review PR (${openPr.artifact}${openPr.number ? ` #${openPr.number}` : ''}) is recorded on the default branch`,
           'opened under a pre-3.0 yadflow? merge/close it before continuing — CI now records the gate ledger on the default branch only at merge');
+        contractLockCheck(checks, root, e, ledger);
+        staleGateCheck(checks, root, e, ledger);
       }
     } catch (err) {
       check(checks, `epic:${e}`, 'epics', 'fail', `${e}: ${err.message} [${err.code || 'YAD-STATE-001'}]`, err.hint || 'fix the file or restore it from git');

package/cli/epic-state.mjs

@@ -57,11 +57,19 @@ export function upsertHubPr(hubPrs = [], rec) {
   return [...hubPrs.filter((p) => p.artifact !== rec.artifact), rec];
 }
 
-// SHA-256 of the contract surface block (architecture only). Mirrors
-// yad-architecture/references/contract-format.md (awk markers + sha256).
-// Line endings are normalized to LF so the same surface hashes identically across
-// platforms (a CRLF re-save must not revoke approvals). A BEGIN without an END is
-// malformed and yields null — never a silent hash of everything to end-of-file.
+// SHA-256 of the contract surface block (architecture only). Byte-for-byte identical to the recipe
+// yad-architecture/references/contract-format.md publishes — the one the architect runs to write
+// contract-lock.json:
+//
+//   awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' contract.md \
+//     | tr -d '\r' | shasum -a 256
+//
+// Canonicalization, in the order awk applies it: every line strictly between the markers, CRLF
+// normalized to LF (so a CRLF re-save never revokes approvals), joined by LF, and TERMINATED by a
+// trailing LF — awk emits a newline after every line it prints, so that last newline is part of the
+// hashed bytes. Omitting it made the CLI digest and the documented recipe disagree by exactly one
+// byte on every surface, so contract-lock.json could never equal what approvals bind to (issue #156).
+// A BEGIN without an END is malformed and yields null — never a silent hash of everything to EOF.
 export function contractSurfaceHash(epicDir) {
   const file = path.join(epicDir, 'contract.md');
   if (!fs.existsSync(file)) return null;
@@ -75,7 +83,7 @@ export function contractSurfaceHash(epicDir) {
     if (inside) body.push(ln);
   }
   if (!terminated || !body.length) return null;
-  return 'sha256:' + createHash('sha256').update(body.join('\n')).digest('hex');
+  return 'sha256:' + createHash('sha256').update(body.join('\n') + '\n').digest('hex');
 }
 
 // Deterministic fingerprint of the whole stories/ set: hash each story file, sort, combine. Lets an

package/cli/gate.mjs

@@ -16,7 +16,7 @@ import {
 import { hubGit, preflightGuardReadiness, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
 import {
   readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin,
-  getPrBody, editPrBody, postComment,
+  getPrBody, editPrBody, postComment, findPrForBranch, prBranch, branchExists,
 } from './platform.mjs';
 import { isNoBlock, upsertTrailerBlock, nudgeMessage, parseEngagement } from './companion.mjs';
 import { sequenceDiff } from './walkthrough.mjs';
@@ -127,32 +127,54 @@ const requireEngagement = (hub) => !!(hub && (hub.review?.requireEngagement ===
 // revocations vanish idempotently; manual approvals are never touched). Preserve the artifactHash a
 // reviewer first approved against unless their review is newer (a genuine re-approval) — that is what
 // makes "revoke only when the artifact changed" work.
-function upsertBridge(approvals, recs, { stepId, artifact, curHash, today }) {
+// `closed`: the step already advanced. Drop-and-re-add is what makes a dismissal or revocation vanish
+// idempotently on an OPEN step — the platform is the live source of truth there. On a CLOSED step it
+// is destructive instead: the gate passed, and the approvals that passed it are the audit record of
+// why. A roster edit, a GitLab approval reset, or any degraded-but-`ok` read yields an empty `recs`
+// and would erase them, leaving `done` with zero approvals — the very state issue #156 is about,
+// reached from the other side. So a closed step's record is only ever added to or refreshed in place.
+function upsertBridge(approvals, recs, { stepId, artifact, curHash, today, prNumber = null, closed = false }) {
   const keyOf = (name, role, domain) => `${stepId}|${name}|${role}|${domain || ''}`;
   const prior = new Map(
     approvals.filter((a) => a.step === stepId && a.source === 'bridge')
       .map((a) => [keyOf(a.approver, a.role, a.domain), a]),
   );
-  const kept = approvals.filter((a) => !(a.step === stepId && a.source === 'bridge'));
+  const seen = new Set(recs.map((r) => keyOf(r.name, r.role, r.domain)));
+  const kept = approvals.filter((a) => {
+    if (!(a.step === stepId && a.source === 'bridge')) return true;
+    // Closed step: keep a prior approval the platform no longer reports. It is history, not state.
+    return closed && !seen.has(keyOf(a.approver, a.role, a.domain));
+  });
   for (const r of recs) {
     const was = prior.get(keyOf(r.name, r.role, r.domain));
     let artHash = curHash;            // first time we see this approval => bind to current content
     let approvedAt = r.submittedAt || today;
+    let recordedOn = today;
     if (was) {
-      // We only adopt the new hash when the platform PROVES a genuinely newer review (a later
-      // submittedAt). Otherwise — same review, or a platform that gives no timestamp (GitLab) — we
-      // KEEP the hash they originally approved, so a later artifact change still revokes the approval.
-      const genuinelyNewer = r.submittedAt && was.approvedAt && r.submittedAt > was.approvedAt;
-      if (!genuinelyNewer) {
+      // We only adopt the new hash when the platform PROVES a genuinely newer review. Otherwise —
+      // the same review read again — we KEEP the hash they originally approved, so a later artifact
+      // change still revokes the approval. Two independent proofs, because one platform lacks each:
+      //   - a later submittedAt (GitHub; GitLab approvals carry no timestamp at all), or
+      //   - a DIFFERENT PR/MR than the one this approval was recorded against. A re-opened review is
+      //     always a new PR, so an approval arriving on it cannot be the old one read again. Without
+      //     this, a GitLab re-review after a re-lock re-recorded the pre-edit hash and stayed
+      //     permanently stale — the step read `done` with zero live approvals (issue #156).
+      const newerReview = r.submittedAt && was.approvedAt && r.submittedAt > was.approvedAt;
+      const newerPr = prNumber != null && was.pr != null && was.pr !== prNumber;
+      if (!newerReview && !newerPr) {
         artHash = was.artifactHash ?? curHash;
         approvedAt = was.approvedAt ?? approvedAt;
+        // Same review, re-read: keep the date it was RECORDED too, so re-syncing an unchanged
+        // approval is a byte-identical no-op instead of a daily one-line ledger commit.
+        recordedOn = was.date ?? recordedOn;
       }
     }
     kept.push({
       artifact, step: stepId, approver: r.name, role: r.role,
       ...(r.domain ? { domain: r.domain } : {}),
-      status: 'approved', date: today, source: 'bridge',
+      status: 'approved', date: recordedOn, source: 'bridge',
       artifactHash: artHash, approvedAt,
+      ...(prNumber != null ? { pr: prNumber } : {}),
       engagement: r.engagement === 'verified' ? 'verified' : 'none',
       ...(r.unverified ? { unverified: true } : {}),
     });
@@ -160,6 +182,20 @@ function upsertBridge(approvals, recs, { stepId, artifact, curHash, today }) {
   return kept;
 }
 
+// Mutates in place, returns how many it stamped. Backfill `pr` on this step's bridge approvals that
+// predate approvals recording which PR they arrived on. `prNumber` must be the pointer they were
+// recorded against — callers stamp only at the moment that pointer is about to be replaced, so nothing
+// is invented: it is exactly the PR those approvals came from.
+export function stampLegacyPr(approvals, stepId, prNumber) {
+  let n = 0;
+  for (const a of approvals) {
+    if (a.step !== stepId || a.source !== 'bridge' || a.pr != null) continue;
+    a.pr = prNumber;
+    n++;
+  }
+  return n;
+}
+
 function writeComments(epicDir, base, today, blocking) {
   if (!blocking.length) return;
   const file = path.join(epicDir, 'reviews', `${base}--${today}--comments.md`);
@@ -192,7 +228,57 @@ function recordComments(comments, { artifact, stepId, today, roster, blocking })
 
 // ---- actions ------------------------------------------------------------------------------------
 
-export async function gateSync(root, { epic, artifact, today, reader = readPr, local = false, dryRun = false } = {}) {
+// The review PR/MR(s) to sync. Normally the ledger's own pointer — but under the bridge the ledger
+// records that pointer only at merge (CI is the sole writer), so a review a human needs to push
+// through by hand has NO recorded pointer at all. Fall back to the PR number the caller named
+// (`--pr`), else resolve it from the review branch on the platform. Without this, `gate sync` reported
+// "no open review PR recorded" for a PR sitting merged on the platform and the advance was
+// unreachable by hand (issue #158).
+// `--pr` is a recovery flag, so an explicit one WINS over the recorded pointer (a re-opened review is a
+// new PR the ledger has not seen). It is also the one number a human types, so it is checked before it
+// can bind approvals: it must be a positive integer, and — when the platform can be asked — it must be
+// the PR for this artifact's review branch. Without that confirmation a typo'd number naming some
+// unrelated merged-and-approved PR would have its reviewers bound to this artifact's hash and satisfy
+// the gate.
+function resolveTargets(hubPrs, { epic, artifact, state, platform, number, finder, branchOf, cwd }) {
+  const recorded = hubPrs.filter((p) => !artifact || p.artifact === artifact);
+  const named = number == null || number === '' ? null : Number(number);
+  if (named !== null && (!Number.isInteger(named) || named <= 0)) {
+    return { targets: [], discovered: false, reason: `--pr must be a positive integer, got '${number}'` };
+  }
+  if (named === null && recorded.length) return { targets: recorded, discovered: false };
+  if (!artifact) return { targets: [], discovered: false, reason: 'name the artifact to resolve its review PR' };
+  const step = findReviewStep(state, artifact);
+  if (!step) return { targets: [], discovered: false, reason: `no review step for ${artifact}` };
+  const branch = `review/${epic}/${base(artifact)}`;
+  // `upsertHubPr` replaces the whole entry for an artifact, so a record built from scratch DROPS
+  // whatever the recorded one carried. That matters when `--pr` names the PR already on file: `nudged`
+  // is the idempotency set for the engagement nudge, so losing it makes the next writer run
+  // re-@-mention every bare approver on the PR — a platform write, not just a ledger one — and `url`
+  // would churn to null. Carry the recorded entry forward whenever the number is the same one.
+  const entry = (n, url) => {
+    const prev = recorded.find((p) => p.number === n) || {};
+    return [{ ...prev, step: step.id, artifact, platform, number: n, url: url ?? prev.url ?? null, branch, lastSyncedAt: prev.lastSyncedAt ?? null }];
+  };
+  if (named !== null) {
+    // Confirm the number names THIS artifact's review before its reviewers are bound to this
+    // artifact's hash. A platform that cannot answer (no CLI, no auth, offline) is not evidence
+    // against it — warn and take the human at their word — but a definite mismatch is refused.
+    const head = branchOf(platform, named, { cwd });
+    if (head.ok && head.branch !== branch) {
+      return { targets: [], discovered: false, reason: `#${named} is on '${head.branch}', not this artifact's review branch '${branch}'` };
+    }
+    if (!head.ok) warn(`could not confirm #${named} belongs to ${branch} (${head.reason}) — using it as given`);
+    if (recorded.length && recorded[0].number !== named) info(`--pr #${named} overrides the recorded review PR #${recorded[0].number}`);
+    return { targets: entry(named, null), discovered: true };
+  }
+  const found = finder(platform, branch, { cwd });
+  if (!found.ok) return { targets: [], discovered: false, reason: found.reason };
+  info(`no recorded review PR — resolved #${found.number}${found.state ? ` (${found.state})` : ''} from ${branch}`);
+  return { targets: entry(found.number, found.url), discovered: true };
+}
+
+export async function gateSync(root, { epic, artifact, today, reader = readPr, finder = findPrForBranch, branchOf = prBranch, poster = postComment, number = null, local = false, dryRun = false } = {}) {
   const { hub, repos } = loadHub(root);
   if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — file-only gate, nothing to sync'); return { synced: 0 }; }
   const platform = hub.platform;
@@ -211,17 +297,42 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
   if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { synced: 0 }; }
 
   let { approvals, comments, hubPrs, state } = ledger;
-  const targets = hubPrs.filter((p) => !artifact || p.artifact === artifact);
-  if (!targets.length) { warn(`no open review PR recorded for ${epic}${artifact ? ` / ${artifact}` : ''} (run \`yad gate open\` first)`); return { synced: 0 }; }
+  // Migration (see stampLegacyPr): an approval written before PR provenance existed carries no `pr`,
+  // so it can never be told apart from one arriving on a replacement PR — and on GitLab, with no
+  // submittedAt either, the other proof is unavailable too. The pointer recorded here IS the PR those
+  // approvals came from, so stamp them before anything replaces it.
+  for (const p of hubPrs) {
+    const s = p.number != null ? findReviewStep(state, p.artifact) : null;
+    if (s) stampLegacyPr(approvals, s.id, p.number);
+  }
+  const resolved = resolveTargets(hubPrs, { epic, artifact, state, platform, number, finder, branchOf, cwd: root });
+  const targets = resolved.targets;
+  if (!targets.length) {
+    warn(`no review PR recorded for ${epic}${artifact ? ` / ${artifact}` : ''}${resolved.reason ? ` — ${resolved.reason}` : ''}`);
+    hand(`run \`yad gate open ${epic} ${artifact || '<artifact>'}\`, or name the PR: \`yad gate sync ${epic} ${artifact || '<artifact>'} --pr <n>\``);
+    return { synced: 0 };
+  }
+  // A pointer resolved from the platform is adopted into the ledger on the WRITER path only. In
+  // bridge mode this run is advisory and writes nothing, so the human never ends up with a gate-state
+  // file in their working tree for the ledger-guard check to reject.
+  if (resolved.discovered && !readOnly) hubPrs = upsertHubPr(hubPrs, targets[0]);
 
   let synced = 0;
   let advanced = 0;
+  // Targets whose step is still open. The dated approval-roster file is regenerated only for these —
+  // an already-done step is re-synced for its approvals alone, and would otherwise drop a new
+  // reviews/<artifact>--<today>--approved.md every time the scheduled sweep re-visits it.
+  const open = [];
   for (const pr of targets) {
     const step = findReviewStep(state, pr.artifact);
     if (!step) { warn(`no review step for ${pr.artifact}`); continue; }
-    // Already advanced: a re-sync must not re-run advance (it would reset the next step's status /
-    // currentStep backward). The gate is one-way per step.
-    if (step.status === 'done') { info(`${pr.artifact}: ${step.id} already done — skipping`); continue; }
+    // A step that already advanced is never advanced AGAIN (that would reset the next step's status /
+    // currentStep backward) — the gate is one-way per step. But it is still SYNCED: in bridge mode
+    // nothing ever moves a step back to in_review (CI is the sole ledger writer), so a re-opened
+    // review — surface re-locked, fresh PR, fresh approvals, merged — used to hit a blanket skip here
+    // and write nothing but the PR pointer. The step then read `done` while its approvals were all
+    // stale: work proceeded on an audit trail saying the re-review never happened (issue #156).
+    const alreadyDone = step.status === 'done';
     const domains = touchedDomains(epicDir, step);
     const pull = reader(platform, pr.number, { cwd: root });
     // A failed platform read must not pass as a green no-op: flag the run non-zero so CI surfaces it
@@ -231,8 +342,9 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
     const curHash = artifactHash(epicDir, pr.artifact);
     warnUnlockedContract(epicDir, pr.artifact);
     warnIncompleteDiscovery(epicDir, pr.artifact);
+    const approvalsBefore = JSON.stringify(approvals);
     const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains, headOid: pull.headOid });
-    approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today });
+    approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today, prNumber: pr.number ?? null, closed: alreadyDone });
 
     const changeRequested = pull.reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
     // 2f: companion scaffolding + nudge threads carry the noblock marker and are EXCLUDED from the
@@ -245,17 +357,27 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
       ...unresolved,
     ];
     // Advisory (read-only) sync must not touch the working tree — defer the reviews/*.md write.
-    if (!readOnly) writeComments(epicDir, base(pr.artifact), today, blocking);
-    comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, roster, repos, blocking });
+    //
+    // An already-done step is re-synced for its APPROVALS ONLY. Everything else here is per-round
+    // bookkeeping for a review still in flight, and re-running it on a closed one is pure churn: both
+    // wired sweeps drive `gate ci --branch … --merged` (event mode) over a 7-day window, so a merged
+    // review that still carries one unresolved thread would append a fresh comment round — and a fresh
+    // `chore(gate): advance … [skip ci]` commit on the default branch — every 15 minutes for a week.
+    // That is the same churn the resource_group fix exists to stop, so it must not be reintroduced here.
+    if (!alreadyDone) {
+      if (!readOnly) writeComments(epicDir, base(pr.artifact), today, blocking);
+      comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, roster, repos, blocking });
+    }
 
     // Social nudge: a bare APPROVE (no verified engagement) still counts (soft default), but the bot
     // posts a friendly public @-mention inviting the reviewer to run the companion. Idempotent via
-    // pr.nudged; only on the writer path (a platform comment, not a ledger write).
-    if (!readOnly) {
+    // pr.nudged; only on the writer path (a platform comment, not a ledger write) — and never on a
+    // closed step, where it would @-mention reviewers on an already-merged PR.
+    if (!readOnly && !alreadyDone) {
       const nudged = new Set(pr.nudged || []);
       for (const rv of pull.reviews) {
         if (rv.state !== 'APPROVED' || parseEngagement(rv.body) === 'verified' || !rv.login || nudged.has(rv.login)) continue;
-        if (postComment(platform, pr.number, nudgeMessage(rv.login), { cwd: root }).ok) nudged.add(rv.login);
+        if (poster(platform, pr.number, nudgeMessage(rv.login), { cwd: root }).ok) nudged.add(rv.login);
       }
       pr.nudged = [...nudged];
     }
@@ -266,7 +388,15 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
     });
 
     log(`  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number}, rule: ${pred.rule})`)}`);
-    if (pred.passed) {
+    if (alreadyDone) {
+      // The step keeps its `done` status and the chain is untouched — re-advancing would reset the
+      // next step, and moving it back to in_review would un-ship work already built on it. What this
+      // pass DOES do is record the approvals that arrived, so `gate status` tells the truth about how
+      // many of them are live against the current artifact.
+      const verdict = pred.passed ? 'the rule still holds' : `the rule no longer holds${pred.staleDropped ? ` (${pred.staleDropped} stale)` : ''}`;
+      info(`${step.id} already done — approvals re-synced, chain not re-advanced; ${verdict}`);
+      for (const m of pred.missing) hand(`recorded gap: ${m}`);
+    } else if (pred.passed) {
       state = advanceState(state, step);
       advanced++;
       ok(`gate PASSED — ${step.id} → done; next: ${state.currentStep}`);
@@ -274,7 +404,12 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
       state = markInReview(state, step);
       for (const m of pred.missing) hand(`still needed: ${m}`);
     }
-    pr.lastSyncedAt = today;
+    // Stamp when this run actually learned something: an open step every time, and a closed one only
+    // when the approval record genuinely changed (a re-opened review that was re-approved). Otherwise
+    // an identical re-sync would rewrite the date daily and churn the ledger, while a real re-review
+    // would leave no trace of when it was reconciled.
+    if (!alreadyDone) { pr.lastSyncedAt = today; open.push(pr); }
+    else if (JSON.stringify(approvals) !== approvalsBefore) pr.lastSyncedAt = today;
     synced++;
   }
 
@@ -286,7 +421,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
   writeJSON(ledger.files.comments, comments);
   writeJSON(ledger.files.hubPrs, hubPrs);
   writeJSON(ledger.files.state, state);
-  refreshRoster(epicDir, targets, approvals, today);
+  refreshRoster(epicDir, open, approvals, today);
   return { synced, advanced };
 }
 
@@ -370,6 +505,16 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
     // build the entry from the event itself so the advance commit carries it onto the default branch.
     const existing = (ledger.hubPrs || []).find((x) => x.artifact === job.artifact);
     const number = Number(job.pr) || existing?.number || null;
+    // Same migration as gateSync, at the one point CI knows the OLD pointer: stamp the approvals it
+    // recorded before replacing it, or a re-review on the replacement PR can never be told from a
+    // re-read of the old one and stays permanently stale.
+    if (existing?.number != null && number !== existing.number) {
+      const stamped = stampLegacyPr(ledger.approvals, step.id, existing.number);
+      if (stamped) {
+        writeJSON(ledger.files.approvals, ledger.approvals);
+        info(`${job.epic}: recorded PR #${existing.number} on ${stamped} approval(s) that predate PR provenance`);
+      }
+    }
     if (!existing || existing.number !== number || existing.branch !== job.branch) {
       ledger.hubPrs = upsertHubPr(ledger.hubPrs, {
         step: step.id, artifact: job.artifact, platform: hub.platform, number,
@@ -555,7 +700,7 @@ export async function gateRepair(root, { epic, push = false, allowBranch = false
 // the user's checked-out branch, which for a per-story review (review/EP-*/stories-S01) does NOT equal
 // the branch this would otherwise recompute (artifactFromBase collapses stories-S01 → stories/). Pass
 // the real pushed head so the PR targets a branch that exists. `creator` is injected in tests.
-export async function gateOpen(root, { epic, artifact, head, creator = createPr } = {}) {
+export async function gateOpen(root, { epic, artifact, head, creator = createPr, hasBranch = branchExists } = {}) {
   const { hub, repos } = loadHub(root);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
@@ -570,6 +715,27 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr
   warnIncompleteDiscovery(epicDir, artifact);
 
   const bridge = isBridge(hub);
+  // The review branch must exist ON ORIGIN: this command opens a PR against it, it never creates or
+  // pushes it, and `gh pr create --head` explicitly does NOT push either — so a branch that is only
+  // local still fails inside the platform CLI, which is the opaque error this guard exists to replace.
+  // `open-pr` pushes the checked-out branch first and passes it as `head`, so that path is unaffected;
+  // only the branch this command COMPUTED is checked. A null answer means git could not be asked (no
+  // checkout, unreachable origin) — not evidence of absence, so it warns rather than blocks.
+  //
+  // Checked BEFORE any state is written: marking the step in_review and then refusing would leave the
+  // ledger claiming a review is open that was never opened.
+  if (!head && hub?.platform) {
+    const present = hasBranch(root, branch);
+    if (present === false) {
+      fail(`review branch '${branch}' is not on origin`);
+      hand(`git push -u origin ${branch}`);
+      hand('or run `yad open-pr` from the branch — it pushes, then opens the review PR');
+      process.exitCode = 1;
+      return;
+    }
+    if (present === null) warn(`could not verify that '${branch}' is on origin — opening the PR against it anyway`);
+  }
+
   // Outside bridge mode (file-only, OR a platform with no gate-sync CI) there is no CI to write the
   // ledger, so the local command marks the step in_review. In bridge mode CI is the sole writer.
   if (!bridge) {