yadflow 3.12.2 → 3.13.1

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) {

package/cli/ledger.mjs

@@ -79,6 +79,32 @@ export function readShips(epicDir) {
   return [...byKey.values()];
 }
 
+// Record a RETROACTIVE ship for a pre-tracking story — one merged & shipped before the back-half
+// ledger existed, so it has no build-log ship and `yad checkpoint` can't carry its `status:` flip
+// (issue #142). Writes ONE minimal ship shard, marked `retroactive: true`, so `readShips` now proves
+// the story shipped and checkpoint carries the human's already-made flip. It is NOT a fabricated real
+// ship: `task` defaults to the sentinel `retro`, `mergeCommit` is written only when the caller supplies
+// it (never invented), and `shippedAt` is the backfill date (the `retroactive` flag marks it as such).
+//
+// Guard: refuse when the story ALREADY has ANY build-log ship — then it isn't pre-tracking and the
+// normal ship/checkpoint flow applies; a retro record would only muddy the ledger. Returns
+// { written: false, reason } in that case, else { written: true, file, ship }.
+export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeCommit, shippedAt }) {
+  if (!story) throw new Error('writeRetroShip: story is required');
+  if (!repo) throw new Error('writeRetroShip: repo is required');
+  if (readShips(epicDir).some((s) => s.story === story)) {
+    return { written: false, reason: 'exists' };
+  }
+  const t = task || 'retro';
+  const ship = { story, task: t, repo, retroactive: true, note: 'pre-tracking backfill' };
+  if (mergeCommit) ship.mergeCommit = mergeCommit;
+  if (shippedAt) ship.shippedAt = shippedAt;
+  const f = epicFiles(epicDir);
+  const file = path.join(f.buildLogDir, buildShardName({ story, task: t, repo }));
+  writeJSON(file, ship);
+  return { written: true, file, ship };
+}
+
 // Find the ship matching `match(ship)` across loose shards (authoritative until folded) then the
 // folded file, apply `update(ship)`, and write back ONLY the file that holds it. Returns
 // { found, where, file, ship }; found:false writes nothing (the caller warns).

package/cli/platform.mjs

@@ -298,6 +298,86 @@ export function readPr(platform, n, opts = {}) {
   return platform === 'gitlab' ? readPrGitLab(n, opts) : readPrGitHub(n, opts);
 }
 
+// ---- find the PR/MR for a branch ----------------------------------------------------------------
+// The review PR/MR opened for `review/EP-<slug>/<artifact>`, by HEAD/source branch. Under the bridge
+// the ledger records that pointer only at merge (CI is the sole writer), so without this a human has
+// no way to name the review a merged PR belongs to — `gate sync` would just report "no open review PR
+// recorded" for a PR that is sitting merged on the platform (issue #158).
+//
+// State is deliberately UNfiltered: the interesting case is a MERGED PR that never advanced. Newest
+// first, so a re-opened review resolves to its current PR and not a superseded one. Returns
+// { ok, number, url } — never throws; `ok:false` carries the reason.
+export function findPrForBranch(platform, branch, { cwd } = {}) {
+  if (!branch) return { ok: false, reason: 'no branch given' };
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'gitlab') {
+    const r = run('glab', ['api', `projects/:id/merge_requests?source_branch=${encodeURIComponent(branch)}&order_by=updated_at&sort=desc&per_page=1`], { cwd });
+    if (!r.ok) return { ok: false, reason: r.stderr || 'glab api merge_requests failed' };
+    let rows;
+    try { rows = JSON.parse(r.stdout); } catch { return { ok: false, reason: 'unreadable glab api response' }; }
+    const mr = Array.isArray(rows) ? rows[0] : null;
+    if (!mr?.iid) return { ok: false, reason: `no merge request found for source branch ${branch}` };
+    return { ok: true, number: Number(mr.iid), url: mr.web_url || null };
+  }
+  const r = run('gh', ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '1', '--json', 'number,url'], { cwd });
+  if (!r.ok) return { ok: false, reason: r.stderr || 'gh pr list failed' };
+  let rows;
+  try { rows = JSON.parse(r.stdout); } catch { return { ok: false, reason: 'unreadable gh pr list response' }; }
+  const pr = Array.isArray(rows) ? rows[0] : null;
+  if (!pr?.number) return { ok: false, reason: `no pull request found for head branch ${branch}` };
+  return { ok: true, number: Number(pr.number), url: pr.url || null };
+}
+
+// The head/source branch of a PR/MR, so a caller can confirm a number a human typed actually belongs
+// to the review it is about to bind approvals to. Returns { ok, branch }; never throws.
+export function prBranch(platform, n, { cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'gitlab') {
+    const r = run('glab', ['api', `projects/:id/merge_requests/${Number(n)}`], { cwd });
+    if (!r.ok) return { ok: false, reason: r.stderr || 'glab api merge_request failed' };
+    try {
+      const mr = JSON.parse(r.stdout);
+      return mr?.source_branch ? { ok: true, branch: mr.source_branch } : { ok: false, reason: `MR !${n} has no source_branch` };
+    } catch { return { ok: false, reason: 'unreadable glab api response' }; }
+  }
+  const r = run('gh', ['pr', 'view', String(n), '--json', 'headRefName'], { cwd });
+  if (!r.ok) return { ok: false, reason: r.stderr || 'gh pr view failed' };
+  try {
+    const pr = JSON.parse(r.stdout);
+    return pr?.headRefName ? { ok: true, branch: pr.headRefName } : { ok: false, reason: `PR #${n} has no headRefName` };
+  } catch { return { ok: false, reason: 'unreadable gh pr view response' }; }
+}
+
+// Is `branch` on ORIGIN? `gate open` opens a PR against the review branch but never creates or pushes
+// it — and neither does the platform CLI, since `gh pr create --head <b>` explicitly disables its
+// automatic push. So a branch that exists only locally is just as unusable as one that does not exist
+// at all, and checking locally would wave it through into the opaque platform error this replaces.
+// Returns null when git cannot answer (not a checkout, no origin, network/auth failure) — "unknown"
+// must never read as "missing" and block.
+export function branchExists(cwd, branch) {
+  if (!run('git', ['rev-parse', '--git-dir'], { cwd }).ok) return null;
+  // This runs synchronously on the `gate open` path, so "cannot ask" has to be FAST — a blocked probe
+  // is a hung command, not the intended null. Three separate ways it could block:
+  //   GIT_TERMINAL_PROMPT=0  — git's own credential prompt (https origins)
+  //   GIT_SSH_COMMAND        — ssh's passphrase / host-key prompts, which git's flag does NOT cover
+  //                            (an unset host key otherwise waits on "Are you sure…?" forever)
+  //   timeout                — anything else that stalls: a black-holed host, a wedged helper
+  // A caller's own GIT_SSH_COMMAND wins; we only supply the default.
+  const remote = run('git', ['ls-remote', '--exit-code', '--heads', 'origin', branch], {
+    cwd,
+    timeout: 10_000,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: '0',
+      GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -oBatchMode=yes -oStrictHostKeyChecking=accept-new',
+    },
+  });
+  if (remote.ok) return true;
+  // exit 2 is ls-remote's own "no matching ref" — the only definite negative. Anything else (no
+  // remote configured, auth, offline) is a question we could not ask.
+  return remote.code === 2 ? false : null;
+}
+
 // ---- create a PR/MR -----------------------------------------------------------------------------
 // `assignees` = the committer/PR-opener (always set, so the PR is owned by whoever pushed it);
 // `reviewers` = the scope's reviewers + domain-owners (computed by reviewersForScopes). On GitHub an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.12.2",
+  "version": "3.13.1",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
@@ -62,8 +62,8 @@
   ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
     "eslint": "^10.5.0",
     "semantic-release": "^25.0.3"
   }

package/skills/yad-architecture/SKILL.md

@@ -155,16 +155,28 @@ themselves) and write `{project-root}/epics/EP-<slug>/.sdlc/contract-lock.json`:
 ```
 
 Canonicalization (so the hash round-trips): hash the surface region as written between the markers,
-LF line endings, no leading/trailing blank-line normalization beyond what is in the file. Recompute
-the same way later; if it differs, the contract surface changed. The reference command:
+LF line endings, including the newline that terminates the last surface line, and no leading/trailing
+blank-line normalization beyond what is in the file. Recompute the same way later; if it differs, the
+contract surface changed. The command below **is** the definition — `yad` computes the identical
+digest, so `yad doctor` can verify `contract-lock.json` against the live `contract.md` and FAIL when
+the surface drifted from its lock:
 
 ```bash
 awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
-  epics/EP-<slug>/contract.md | shasum -a 256
+  epics/EP-<slug>/contract.md | tr -d '\r' | shasum -a 256
 ```
 
 (See `references/contract-format.md` for the altitude rule and the exact hashing recipe.)
 
+> **Upgrading from a yadflow before this recipe and the CLI agreed.** The CLI used to omit the final
+> newline, so the digest it bound approvals to differed from the one the recipe above wrote into
+> `contract-lock.json` — always, on every surface. Lock files are unaffected (they were written by the
+> recipe and are now verifiable), but **architecture approvals recorded under the old CLI are bound to
+> the old digest and go stale once**. An in-flight `architecture-review` therefore needs re-approval
+> after the upgrade; a step already `done` stays done and is reported by `yad doctor` (see the
+> `…:stale` check) rather than silently re-opened. Nothing else re-binds on its own — that is the point
+> of hash-binding.
+
 ### Step 6 — Advance the authoring step (NOT the gate)
 In `state.json`: set `architecture.status: "done"`, set `architecture-review.status: "in_review"`, and
 set `currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only

package/skills/yad-architecture/references/contract-format.md

@@ -49,7 +49,10 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 ```
 
 - `awk` emits every line strictly between the two markers (the `next` after BEGIN skips the BEGIN
-  line; setting `f=0` on END stops before printing END).
+  line; setting `f=0` on END stops before printing END), each **terminated by a newline** — so the
+  hashed bytes are the surface lines joined by LF **plus a trailing LF**. That trailing byte is part
+  of the digest; `yad` computes the identical value (`contractSurfaceHash`, `cli/epic-state.mjs`), so
+  the lock file and what the gate binds approvals to are the same number.
 - `tr -d '\r'` normalizes CRLF line endings to LF before hashing — the same surface must hash
   identically no matter which platform last saved the file (the CLI normalizes the same way).
 - `shasum -a 256` (BSD/macOS) or `sha256sum` (GNU/Linux) produce the same hex digest for identical

package/skills/yad-checks/references/check-gates.md

@@ -26,6 +26,10 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 - Maintenance commits are **exempt**: a Conventional-Commits subject of type `ci`, `chore`, `build`,
   or `test` (optional `(scope)` / breaking `!`) **PASSes** without a link — CI wiring, dependency
   bumps, and test-infra changes legitimately link no story.
+- The exemption waives the **requirement** for a link, never the **validity** of one that is claimed.
+  A maintenance commit that *does* carry a `Task:` trailer is resolved like any other: a malformed id
+  or a missing `specs/<story>/link.md` **FAILS**. Otherwise the trailer is decorative on exempt
+  commits and an unlinked `chore:` is indistinguishable from one naming a story that never existed.
 - For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
 - The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
   `EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
@@ -168,10 +172,23 @@ After the contract locks and code ships, a change must not mutate a locked artif
 epic threaded to its parent (`config.yaml` `change:`). These three gates keep that discipline. All three
 resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md` (`epic` + `product-repo`)
 → the hub epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
-commits are exempt. When the **product hub is not reachable** from CI (the usual case for a code-repo
+commits **with no `Task:` trailer** are exempt — like spec-link, the exemption waives the requirement
+for an owning epic, never the validity of one that is claimed, so a maintenance subject cannot buy a
+pass past the sealed-epic / orphan-thread / frozen-thread checks. When the **product hub is not reachable** from CI (the usual case for a code-repo
 PR), each degrades to a **PASS-with-note** — the hub-side check (`yad doctor` / `yad reconcile`) covers
 that path, and spec-link still proves the story link.
 
+**Resolving `product-repo` (shared by all four hub-reading gates, contract-check included).** An
+**absolute** value is used as-is; a **relative** value is joined to the `link.md`'s own directory,
+`specs/<story>/`, falling back to a repo-root reading when only that resolves (what contract-check
+historically did, so `link.md` files written for it keep working). The `link.md` itself is read from
+its frontmatter block, falling back to a whole-file scan for a pre-frontmatter one. Every gate applies
+the identical rule — when they disagree, a value one gate can resolve becomes an unreachable path for
+another, and "unreachable" is a PASS-with-note, so the gate silently stops gating (issue #149). Each
+gate now **prints that note**, so a deferred check is never mistaken for a passed one. The block is
+duplicated verbatim across the four scripts (they are standalone by design) and a test asserts the
+four copies stay byte-identical.
+
 - **lineage-check** — reads the hub epic's `kind`/`parent` frontmatter. A `feature` (genesis) epic
   passes. A `change`/`defect`/`hotfix` epic **FAILS** unless it declares a `parent:` that resolves to a
   real `epics/<parent>/` in the hub (no orphan threads). This is the "every code change has an owning