yadflow 3.15.2 → 3.15.3

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [3.15.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.2...v3.15.3) (2026-08-11)
+
+
+### Bug Fixes
+
+* **bridge:** pass the PR head ref through env, not into the run script ([306f49f](https://github.com/abdelrahmannasr/yadflow/commit/306f49f569c5398bbfb36ce9aa3fb38d8341336c))
+* **gate:** make the reconcile sweep converge instead of committing forever ([6bcb8fd](https://github.com/abdelrahmannasr/yadflow/commit/6bcb8fd8cd296b669bcf11226013fcd2e107f650)), closes [#163](https://github.com/abdelrahmannasr/yadflow/issues/163)
+* **gate:** stage the merge commit from an allowlist, not the whole epic dir ([8142ddc](https://github.com/abdelrahmannasr/yadflow/commit/8142ddcce0f889505a29558c6664e42548d9d671))
+
 ## [3.15.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.1...v3.15.2) (2026-08-11)
 
 

package/cli/artifact-status.mjs

@@ -59,9 +59,15 @@ export async function syncStatuses(root, { epic, dryRun = false } = {}) {
   const epics = epic
     ? [epic]
     : (fs.existsSync(epicsDir) ? fs.readdirSync(epicsDir).filter((e) => fs.statSync(path.join(epicsDir, e)).isDirectory()).sort() : []);
-  if (!epics.length) { info('no epics found — nothing to sync'); return { changed: 0 }; }
+  if (!epics.length) { info('no epics found — nothing to sync'); return { changed: 0, files: [] }; }
 
   let changed = 0;
+  // The root-relative paths actually rewritten. `gate ci` stages its merge commit from an explicit
+  // allowlist — the ledger, the generated reviews, and exactly these artifacts — so a run on a dirty
+  // checkout (the documented manual recovery) can never sweep an unrelated file onto the default
+  // branch. Reporting the paths is what lets the caller be that specific. Named `written`, not
+  // `files`: the per-epic loop below already binds a local `files` (its candidate list).
+  const written = [];
   for (const e of epics) {
     const dir = epicRoot(root, e);
     const state = readJSONStrict(epicFiles(dir).state, null);
@@ -98,10 +104,10 @@ export async function syncStatuses(root, { epic, dryRun = false } = {}) {
         continue;
       }
       const prev = setFrontmatterStatus(file, want);
-      if (prev) { ok(`${path.relative(root, file)}: ${prev} → ${want}`); changed++; }
+      if (prev) { ok(`${path.relative(root, file)}: ${prev} → ${want}`); changed++; written.push(path.relative(root, file)); }
     }
   }
   if (!changed) info(dryRun ? 'no status changes needed' : 'all artifact statuses already in sync');
   else if (!dryRun) ok(`updated ${changed} artifact status(es)`);
-  return { changed };
+  return { changed, files: written };
 }

package/cli/epic-state.mjs

@@ -52,9 +52,45 @@ export function artifactPaths(base) {
   return [`${base}.md`];
 }
 
+// ---- canonical ledger order ---------------------------------------------------------------------
+// Every epic-ledger upsert in this codebase is drop-and-re-append: the records being refreshed are
+// filtered out of the array and pushed back at the TAIL. That makes the file's bytes depend on WHICH
+// step was synced last, not on what the ledger holds — and the wired sweep drives one `gate ci` per
+// merged PR/MR, so a pass over N merged reviews ROTATES the array:
+//
+//   [A,B,C,D,E] -sync A-> [B,C,D,E,A] -sync B-> [C,D,E,A,B] -> … -sync E-> [A,B,C,D,E]
+//
+// Every hop is a non-empty diff, so every hop commits and pushes, and the pass lands back where it
+// started — an unbounded commit loop with zero semantic change (issue #163). Sorting the array on
+// write makes the bytes a pure function of the record SET, so an unchanged re-sync is byte-identical
+// and `gate ci`'s existing "nothing staged -> nothing to commit" guard finally holds.
+//
+// The per-record JSON.stringify tiebreak is what makes the order TOTAL. `Array#sort` is stable, so
+// records tying on the tuple key would keep their (rotating) insertion order — and a manual,
+// skill-written approval can tie with a bridge one on (step, approver, role, domain). The tiebreak is
+// position-independent, so ties resolve by content instead.
+//
+// Compared by CODE UNIT (`<`), not localeCompare: the ledger is written by CI and read/re-written by
+// every teammate's machine, and localeCompare's order depends on the host locale and ICU build. Two
+// machines disagreeing on where one record sorts would reintroduce exactly the churn this prevents.
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const canonical = (list, keyOf) => [...list].sort(
+  (x, y) => cmp(keyOf(x), keyOf(y)) || cmp(JSON.stringify(x), JSON.stringify(y)),
+);
+const field = (v) => (v == null ? '' : String(v));
+
+export const canonicalApprovals = (approvals = []) => canonical(approvals, (a) =>
+  [a.step, a.artifact, a.role, a.domain, a.approver, a.source, a.approvedAt, a.date].map(field).join('|'));
+
+export const canonicalComments = (comments = []) => canonical(comments, (cm) =>
+  [cm.step, String(cm.round ?? '').padStart(6, '0'), cm.commenter, cm.role, cm.date].map(field).join('|'));
+
+export const canonicalHubPrs = (hubPrs = []) => canonical(hubPrs, (p) =>
+  [p.artifact, p.step].map(field).join('|'));
+
 // Replace-not-append upsert into hub-prs.json, keyed by artifact (one live review PR per artifact).
 export function upsertHubPr(hubPrs = [], rec) {
-  return [...hubPrs.filter((p) => p.artifact !== rec.artifact), rec];
+  return canonicalHubPrs([...hubPrs.filter((p) => p.artifact !== rec.artifact), rec]);
 }
 
 // SHA-256 of the contract surface block (architecture only). Byte-for-byte identical to the recipe

package/cli/gate.mjs

@@ -12,6 +12,7 @@ import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
   upsertHubPr, stateInvariants, repairState, DISCOVERY_FILES,
+  canonicalApprovals, canonicalComments, canonicalHubPrs,
 } from './epic-state.mjs';
 import { hubGit, preflightGuardReadiness, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
 import {
@@ -179,7 +180,11 @@ function upsertBridge(approvals, recs, { stepId, artifact, curHash, today, prNum
       ...(r.unverified ? { unverified: true } : {}),
     });
   }
-  return kept;
+  // Canonical order, not insertion order: this function re-appends at the tail, so without it the
+  // bytes depend on which step was synced last and the sweep rotates the file forever (issue #163 —
+  // see canonicalApprovals). Sorting here also makes the in-memory before/after comparison below
+  // (`approvalsBefore`) mean what it says, so an unchanged re-sync no longer re-stamps lastSyncedAt.
+  return canonicalApprovals(kept);
 }
 
 // Mutates in place, returns how many it stamped. Backfill `pr` on this step's bridge approvals that
@@ -216,14 +221,28 @@ function recordComments(comments, { artifact, stepId, today, roster, blocking })
   if (!blocking.length) return comments;
   const byName = (login) => (roster.find((r) => r.login === login)?.name) || login || 'reviewer';
   const roleOf = (login) => (roster.find((r) => r.login === login)?.role) || 'reviewer';
-  const round = (comments.filter((cm) => cm.step === stepId).reduce((m, cm) => Math.max(m, cm.round || 0), 0)) + 1;
   const counts = new Map();
   for (const t of blocking) counts.set(t.login, (counts.get(t.login) || 0) + 1);
+  // A round is a CHANGE in the thread state, not a sync. Allocating max+1 on every call made an
+  // unchanged re-read append a whole new record set each pass — and the sweep re-reads a merged review
+  // every 15 minutes for a week. A step whose gate never passes (one unresolved thread, or a missing
+  // approval) is never `alreadyDone`, so it kept reaching here: ~96 ledger commits a day per stuck
+  // review, the same unbounded loop as #163 from the other side. So when the latest recorded round
+  // already describes exactly these commenters and counts, REWRITE it in place instead.
+  const rounds = comments.filter((cm) => cm.step === stepId);
+  const latest = rounds.reduce((m, cm) => Math.max(m, cm.round || 0), 0);
+  const prior = rounds.filter((cm) => cm.round === latest);
+  const now = new Map([...counts].map(([login, count]) => [byName(login), count]));
+  const same = latest > 0 && prior.length === now.size && prior.every((cm) => now.get(cm.commenter) === cm.count);
+  const round = same ? latest : latest + 1;
   const kept = comments.filter((cm) => !(cm.step === stepId && cm.round === round));
   for (const [login, count] of counts) {
-    kept.push({ artifact, step: stepId, commenter: byName(login), role: roleOf(login), round, count, date: today });
+    // An unchanged round keeps its original date, so re-syncing it is byte-identical rather than a
+    // daily one-line churn (the same rule upsertBridge applies to an unchanged approval).
+    const was = prior.find((cm) => cm.commenter === byName(login));
+    kept.push({ artifact, step: stepId, commenter: byName(login), role: roleOf(login), round, count, date: (same && was?.date) || today });
   }
-  return kept;
+  return canonicalComments(kept); // same drop-and-re-append churn as approvals — see canonicalApprovals
 }
 
 // ---- actions ------------------------------------------------------------------------------------
@@ -306,7 +325,19 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
     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;
+  // Advance in CHAIN order, never in ledger order. `advanceState` opens the step that FOLLOWS the one
+  // it closes, so syncing two passing gates out of chain order rewinds the epic: closing
+  // architecture-review first (next: ui-design) and epic-review second (next: architecture) reopens the
+  // already-done `architecture` author step and points currentStep backward — the YAD-STATE-005 chain
+  // inconsistency `yad gate repair` exists to undo. This used to hold only by accident, because
+  // hub-prs.json happened to be in insertion order; now that the file is written sorted by artifact
+  // (see canonicalHubPrs) the accident is gone, so make the ordering explicit. `gate ci` is unaffected
+  // either way — it always names a single artifact.
+  const stepIndex = (p) => {
+    const s = findReviewStep(state, p.artifact);
+    return s ? state.steps.indexOf(s) : Number.MAX_SAFE_INTEGER;
+  };
+  const targets = [...resolved.targets].sort((a, b) => stepIndex(a) - stepIndex(b));
   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>\``);
@@ -417,11 +448,17 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
     info('bridge mode: advisory view — CI owns the ledger, nothing written locally');
     return { synced, advanced };
   }
+  // Belt-and-braces: the upserts above already return canonical order, but a ledger this run only
+  // READ (no matching target, or a pre-canonical file written by an older release) still gets sorted
+  // here, so the first sweep after the upgrade converges the file once and never churns it again.
+  approvals = canonicalApprovals(approvals);
+  comments = canonicalComments(comments);
+  hubPrs = canonicalHubPrs(hubPrs);
   writeJSON(ledger.files.approvals, approvals);
   writeJSON(ledger.files.comments, comments);
   writeJSON(ledger.files.hubPrs, hubPrs);
   writeJSON(ledger.files.state, state);
-  refreshRoster(epicDir, open, approvals, today);
+  refreshRoster(epicDir, open, approvals, today); // the dated side file lists them in the same order
   return { synced, advanced };
 }
 
@@ -482,6 +519,7 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
   let synced = 0;
   const touched = new Set();
   const advancedEpics = new Set(); // epics whose step actually passed this run (merge OR a swept merge)
+  const statusFiles = new Map();   // epic -> the artifact files syncStatuses rewrote (staging allowlist)
   for (const job of jobs) {
     const epicDir = epicRoot(root, job.epic);
     // Event mode (--branch) targets a single epic: fail loudly. Sweep mode skips the bad epic.
@@ -508,10 +546,18 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
     // 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) {
+    //
+    // MERGE PHASE ONLY. This is the one approvals.json write gateCi itself performs, and pre-merge the
+    // run persists nothing and commits nothing — so a stamp there would be a working-tree edit with no
+    // purpose, left behind for `ledger-guard` to reject (and a `git checkout` broad enough to undo it
+    // would also revert approvals this run never wrote, e.g. a human's uncommitted manual record). The
+    // stamp loses nothing by waiting: pre-merge writes nothing, so the OLD pointer is still on disk when
+    // the merge event arrives and re-runs this. In sweep mode `job.pr` comes from the ledger itself, so
+    // `number === existing.number` and the condition is false regardless.
+    if (merged && existing?.number != null && number !== existing.number) {
       const stamped = stampLegacyPr(ledger.approvals, step.id, existing.number);
       if (stamped) {
-        writeJSON(ledger.files.approvals, ledger.approvals);
+        writeJSON(ledger.files.approvals, canonicalApprovals(ledger.approvals));
         info(`${job.epic}: recorded PR #${existing.number} on ${stamped} approval(s) that predate PR provenance`);
       }
     }
@@ -535,7 +581,13 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
       // reflect it in the artifact frontmatter (draft → approved). Keyed off the advance, not the
       // --merged flag, so the GitLab scheduled sweep also flips status on a merge it catches. Never
       // on a held step: CI must not touch the artifact while the owner is editing it pre-merge.
-      if (r.advanced > 0) { advancedEpics.add(job.epic); await syncStatuses(root, { epic: job.epic }); }
+      if (r.advanced > 0) {
+        advancedEpics.add(job.epic);
+        const st = await syncStatuses(root, { epic: job.epic });
+        // Remember exactly which artifacts were rewritten — that, and nothing else, is what the
+        // commit below may stage outside the ledger (see the staging allowlist).
+        statusFiles.set(job.epic, [...(statusFiles.get(job.epic) || []), ...(st.files || [])]);
+      }
     } catch (err) {
       if (branch) throw err; // event mode: one epic — surface the failure
       warn(`${job.epic}: sync failed — ${err.message} — skipping this epic`);
@@ -554,10 +606,18 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
   // unaffected: the merge phase re-reads approvals fresh from the platform (readPr).
   const advancedAny = advancedEpics.size > 0;
   if (!merged && !advancedAny) {
-    // Pre-merge is read-only (Path B): the gate was evaluated with a dry sync that persists nothing.
-    // The one working-tree write is the hub-prs.json seed above (so the dry sync could find the PR);
-    // restore exactly that file per epic so the checkout stays clean — never touching anything else,
-    // so a local `yad gate ci --branch` cannot disturb unrelated files.
+    // EVENT mode (--branch) pre-merge is read-only (Path B): the gate was evaluated with a dry sync
+    // that persists nothing, so the one working-tree write is the hub-prs.json seed above (which let
+    // the dry sync find the PR). Restore exactly that file per epic so the checkout stays clean —
+    // never touching anything else, so a local `yad gate ci --branch` cannot disturb unrelated files.
+    // The stampLegacyPr backfill is gated on `merged` above precisely so there is no second file to
+    // undo: a restore wide enough to cover approvals.json would also revert records this run never
+    // wrote — a human's uncommitted manual approval, or an untracked ledger seed `git clean` deletes.
+    //
+    // SWEEP mode (no --branch) reaches here too, and its sync was NOT dry, so state.json/comments.json
+    // and reviews/*.md may be modified and are deliberately left alone: reverting a sync that genuinely
+    // ran would discard platform state the run just recorded. A bare `yad gate ci` that advances
+    // nothing therefore leaves those files dirty for the operator to inspect and commit (or discard).
     for (const e of touched) {
       const hp = path.join('epics', e, '.sdlc', 'hub-prs.json');
       git('checkout', '-q', '--', hp); // restore it if it was tracked
@@ -568,13 +628,22 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
   }
   const target = defaultBranch; // CI only ever commits the ledger to the default branch
 
-  // Stage what this merge-phase run owns, per epic (everything lands on the default branch):
-  //  - advanced → the whole epic (ledger advance + the status flip syncStatuses wrote into the .md).
-  //  - merged but not advanced (merged before the rule passed) → the ledger (.sdlc) + the generated
-  //    reviews/ summaries only; the artifact is the owner's, left untouched.
+  // Stage what this merge-phase run owns, per epic, by an EXPLICIT ALLOWLIST — never `git add -A`
+  // over the whole epic directory:
+  //  - always → the ledger (.sdlc) + the generated reviews/ summaries.
+  //  - advanced → plus exactly the artifact files syncStatuses rewrote (the draft → approved flip).
+  //    The owner's artifact is otherwise theirs, and is left untouched.
+  //
+  // `git add -A -- epics/<e>` would also sweep up anything else sitting in that directory. In CI the
+  // checkout is fresh, so it is invisible there — but `yad gate ci … --merged` on the default branch
+  // is the DOCUMENTED manual recovery for a stuck gate, and a human's checkout is rarely pristine.
+  // Half-finished edits to another artifact, or a stray untracked file, would be committed and pushed
+  // straight to the default branch under a `chore(gate)` subject with [skip ci] — unreviewed, and
+  // contradicting the "CI commits only the ledger" contract every doc in this repo states.
   for (const e of touched) {
-    if (advancedEpics.has(e)) git('add', '-A', '--', path.join('epics', e));
-    else { git('add', '-A', '--', path.join('epics', e, '.sdlc')); git('add', '-A', '--', path.join('epics', e, 'reviews')); }
+    git('add', '-A', '--', path.join('epics', e, '.sdlc'));
+    git('add', '-A', '--', path.join('epics', e, 'reviews'));
+    for (const f of statusFiles.get(e) || []) git('add', '--', f);
   }
   if (git('diff', '--cached', '--quiet').ok) { info('ledger unchanged — nothing to commit'); return { synced }; }
   // [skip ci]: the advance lands on the default branch (no PR trigger) but keeps the marker to guard

package/cli/lib.mjs

@@ -123,6 +123,13 @@ export function readJSONStrict(p, def = null) {
 // file, and a failed rename never leaves a stray .tmp for `git add -A` to pick up.
 export function writeJSON(p, obj) {
   const data = JSON.stringify(obj, null, 2) + '\n';
+  // Byte-identical content is not a write. The ledger writers are unconditional — they re-serialize
+  // whether or not anything changed — so this keeps an unchanged sync from touching the file at all
+  // (no mtime churn, nothing for a watcher or a `git add -A` to notice). A backstop, not the fix: the
+  // load-bearing guarantee is that the serialized bytes are canonically ordered (see #163).
+  try {
+    if (fs.readFileSync(p, 'utf8') === data) return;
+  } catch { /* missing or unreadable — fall through and write it */ }
   fs.mkdirSync(path.dirname(p), { recursive: true });
   const tmp = `${p}.${process.pid}.tmp`;
   fs.writeFileSync(tmp, data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.15.2",
+  "version": "3.15.3",
   "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",

package/skills/yad-hub-bridge/SKILL.md

@@ -103,6 +103,10 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
    - GitLab → `.gitlab/ci/yad-gate-sync.yml` (from `templates/gitlab/yad-gate-sync.gitlab-ci.yml`)
    - plus the hub-side **verified-commits** gate (`checks/verified-commits.sh` + its workflow/fragment,
      owned by `yad-checks`) so review PRs accept only signed commits from roster-known authors
+   - the wired job runs `yadflow@${YAD_VERSION}`, defaulting to the floating major `3` so a published
+     fix reaches the schedule on its own. To pin an exact version, set a `YAD_VERSION` CI/CD (GitLab) or
+     Actions (GitHub) **variable** — never edit it into the wired file, which `yad check --fix` rewrites
+     from the template. See `references/bridge.md`.
 2. **GitLab only — two one-time steps** (see the fragment's header for the exact recipes):
    - add `include: - local: '.gitlab/ci/yad-gate-sync.yml'` to the root `.gitlab-ci.yml`, or write
      `templates/gitlab/gitlab-ci.include-root.yml` as the root when none exists;

package/skills/yad-hub-bridge/references/bridge.md

@@ -95,9 +95,23 @@ login and requested too — otherwise an escalated step is structurally unsatisf
 - Update the step's `hub-prs.json` `lastSyncedAt` when the sync **learned something** — every sync on
   an open step, and on a closed one only when the approval record actually changed (a re-opened review
   that was re-approved). An identical re-sync leaves it alone, so the ledger does not churn.
+- **Write the ledgers in a canonical order.** `approvals.json`, `comments.json` and `hub-prs.json` are
+  sorted on write, so the bytes are a function of the record *set* and never of which step was synced
+  last. Without this the upsert above — which drops the records it refreshes and re-appends them at the
+  tail — makes the file depend on sync order, and the wired sweep (one `gate ci --branch <ref>
+  --merged` per merged PR/MR, every 15 minutes) walks a rotation:
+  `[A,B,C] → sync A → [B,C,A] → sync B → [C,A,B] → sync C → [A,B,C]`. Every hop is a non-empty diff, so
+  every hop commits and pushes, and the pass ends where it began — an unbounded commit loop with zero
+  semantic change. That is issue #163: ~1,800 bot commits/day on the hub that reported it. Sorting is
+  what makes the "nothing staged → nothing to commit" guard in `gate ci` actually hold.
 - Running `sync` twice with no platform change is a no-op on the ledger — byte-identical, including
   `comments.json` and the dated `reviews/*.md` side files.
 
+**Upgrading past #163.** The first sweep on a yadflow carrying the fix writes one canonicalizing
+reorder commit per epic (the records are the same; only their order changes), then converges
+permanently. On an older yadflow the workaround is to disable the pipeline schedule — merges still
+advance gates via the push path; only the catch-up for squash merges and bare approvals is lost.
+
 ## Contract re-lock invalidates prior platform approvals too
 
 For the **architecture+contract** review, the gate already drops approvals when the contract-surface hash
@@ -165,6 +179,22 @@ other way — up through its first review PR/MR; see "the seed of a new epic" be
 | PR/MR closed **and merged** (the human act) | merge | `gate ci --branch <head> --pr <n> --merged` → re-read approvals, advance the step + flip the artifact `status:` **on the default branch** |
 | Schedule (`*/15`) | reconcile | Safety net: enumerate recently-**merged** `review/EP-*` PRs/MRs via the API and advance any not yet `done` (idempotent). Recovers a merge whose merge-time run failed transiently, and on GitLab also picks up a squash merge whose commit dropped the branch name (and a bare approval — GitLab fires no pipeline on one). **GitHub:** a scheduled workflow, automatic once committed. **GitLab:** a pipeline schedule with `SDLC_GATE_SYNC=true` (one-time setup) |
 
+**Which yadflow the wired job runs.** Both fragments resolve the version from a `YAD_VERSION` variable
+and fall back to `3`:
+
+| Platform | Where the job reads it | Where you set the pin |
+|---|---|---|
+| GitHub | workflow `env: YAD_VERSION: ${{ vars.YAD_VERSION \|\| '3' }}` | Settings → Secrets and variables → Actions → **Variables** |
+| GitLab | `npx -y -p "yadflow@${YAD_VERSION:-3}"` | Settings → CI/CD → **Variables** (beside `SDLC_GATE_TOKEN`) |
+
+The default `3` floats on the major, so a published fix reaches a scheduled job on its next pass with
+nobody in the loop — which is how you want a correctness or gate-churn fix to arrive (this page's own
+issue #163 is the example). To adopt releases deliberately instead, set `YAD_VERSION` to an exact
+version.
+The pin lives in **platform config, not in the wired file**: `yad` owns that file and `yad check --fix`
+rewrites it byte-for-byte from the template, so a version edited into it would be silently reverted on
+the next sync. A hub that pins then owns its own upgrade decision — including for fixes.
+
 **Why no pre-merge write fixes the gate.** Keeping CI off the PR head means an in-flight approval is
 never dismissed by a CI commit, and the PR's required checks never strand on a `[skip ci]` CI commit.
 Correctness is unaffected: at merge CI re-reads the PR/MR approvals from the platform and re-checks

package/skills/yad-hub-bridge/templates/github/yad-gate-sync.yml

@@ -17,10 +17,14 @@
 #   RECONCILE (schedule, every 15 min): the safety net. The merge job's `closed` event fires once and
 #   never repeats, so a transient API/GraphQL/push failure (or a fail-closed degraded approval read)
 #   would otherwise strand a merged review until someone reran it by hand. This periodic job discovers
-#   recently-merged review PRs from the API and advances any not yet done. Idempotent: a step that is
-#   already `done` is never re-advanced (the chain is one-way), and re-syncing it writes nothing unless
-#   its approvals genuinely changed — so re-visiting a merged review for a week costs one no-op read per
-#   pass, not a commit. On GitHub a scheduled workflow runs automatically once committed (no setup).
+#   recently-merged review PRs from the API and advances any not yet done. Idempotent DOWN TO THE
+#   BYTES: a step that is already `done` is never re-advanced (the chain is one-way), and re-syncing it
+#   rewrites the ledger in a canonical order, so an unchanged approval record produces an unchanged file
+#   and nothing is committed — re-visiting a merged review for a week costs one no-op read per pass. That
+#   last part is load-bearing: before the #163 fix the re-sync re-appended each step's approvals at the
+#   tail, so this job rotated approvals.json and committed the reorder every 15 minutes, forever (issue
+#   #163). If you pin YAD_VERSION (below) to something older, disable the schedule.
+#   On GitHub a scheduled workflow runs automatically once committed (no setup).
 #
 # CI never approves and never merges — the merge click is the human approval act.
 #
@@ -40,6 +44,15 @@ permissions:
   contents: write # push the merge-advance ledger commit to the default branch
   pull-requests: read # gh pr view + reviewThreads GraphQL
 
+env:
+  # Which yadflow these jobs run. The default `3` floats on the major, so a published fix reaches the
+  # schedule on its next pass with nobody in the loop — which is how you want a correctness or
+  # gate-churn fix to arrive. To adopt releases deliberately instead, pin an exact version by setting a
+  # repository (or organization) Actions **variable** named YAD_VERSION to e.g. `3.15.2`:
+  # Settings → Secrets and variables → Actions → Variables. It lives there, deliberately NOT in this
+  # file, which `yad` owns and rewrites on every sync. A pinned hub then owns its own upgrade decision.
+  YAD_VERSION: ${{ vars.YAD_VERSION || '3' }}
+
 jobs:
   mergesync:
     # The human merge of a review branch: advance the step + flip the artifact status on the default
@@ -57,20 +70,27 @@ jobs:
       GH_TOKEN: ${{ github.token }}
     steps:
       # Check out the default branch — the merge already landed the artifact here.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.base.ref }}
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "20"
       - name: Advance the gate on merge
+        # The head ref reaches the shell through `env:`, never through `${{ }}` inside `run:`. A
+        # branch name may legally contain `$`, backticks and parentheses, so a PR opened from
+        # `review/EP-x$(curl …)` would otherwise execute on a runner holding `contents: write` — and
+        # the `if:` guard above does not stop it, since that name still starts with `review/EP-`.
+        env:
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
           git config user.name  "yad-gate-sync[bot]"
           git config user.email "yad-gate-sync[bot]@users.noreply.github.com"
-          npx -y -p yadflow@3 yad gate ci \
-            --branch "${{ github.event.pull_request.head.ref }}" \
-            --pr "${{ github.event.pull_request.number }}" \
+          npx -y -p "yadflow@${YAD_VERSION}" yad gate ci \
+            --branch "$HEAD_REF" \
+            --pr "$PR_NUMBER" \
             --merged
 
   reconcile:
@@ -85,11 +105,11 @@ jobs:
     env:
       GH_TOKEN: ${{ github.token }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.repository.default_branch }}
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: "20"
       - name: Reconcile recently-merged review PRs
@@ -110,7 +130,7 @@ jobs:
             [ -n "$N" ] || continue
             REF="$(gh pr view "$N" --json headRefName --jq '.headRefName' 2>/dev/null)" || rc=1
             case "$REF" in
-              review/EP-*) npx -y -p yadflow@3 yad gate ci --branch "$REF" --pr "$N" --merged || rc=1 ;;
+              review/EP-*) npx -y -p "yadflow@${YAD_VERSION}" yad gate ci --branch "$REF" --pr "$N" --merged || rc=1 ;;
             esac
           done < /tmp/yad-merged-prs
           exit $rc

package/skills/yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml

@@ -35,6 +35,13 @@
 # SDLC_GATE_TOKEN. Without it the job fails visibly; recover by setting the token, then re-run the
 # pipeline or run `yad gate ci --branch <review-branch> --pr <iid> --merged` locally on the default
 # branch (advisory `yad gate sync` is read-only in bridge mode and cannot recover a stuck gate).
+#
+# Which yadflow this job runs: `npx -y -p "yadflow@${YAD_VERSION:-3}"`. The default `3` floats on the
+# major, so a published fix reaches this job on its next run with nobody in the loop — which is how you
+# want a correctness or gate-churn fix to arrive. To adopt releases deliberately instead, pin an exact
+# version by setting a CI/CD variable YAD_VERSION (e.g. `3.15.2`) in project Settings → CI/CD →
+# Variables — the same place SDLC_GATE_TOKEN lives, and deliberately NOT in this file, which `yad`
+# owns and rewrites on every sync. A pinned hub then owns its own upgrade decision.
 variables:
   GIT_DEPTH: "0" # full history: gate ci pushes the advance to the default branch
 
@@ -79,8 +86,12 @@ yad-gate-sync:
       rc=0
       if [ "$CI_PIPELINE_SOURCE" = "schedule" ]; then
         # SCHEDULED SWEEP — discover merged review MRs from the platform (Path B keeps no per-branch
-        # ledger), then advance each. `gate ci` is idempotent: an already-`done` step is never
-        # re-advanced, and re-syncing it writes nothing unless its approvals changed.
+        # ledger), then advance each. `gate ci` is idempotent DOWN TO THE BYTES: an already-`done` step
+        # is never re-advanced, and re-syncing it rewrites the ledger in a canonical order, so an
+        # unchanged approval record produces an unchanged file and nothing is committed. That last part
+        # is load-bearing — before the #163 fix the re-sync re-appended each step's approvals at the
+        # tail, so this loop rotated approvals.json and committed the reorder on every pass, forever
+        # (issue #163). If you are on an older yadflow, disable this schedule.
         # A stuck review MR (a squash merge whose commit dropped the branch name, or a failed merge
         # push) is always RECENT, so sweep a generous recent window and PAGINATE it fully (--paginate)
         # — this bounds cost without the old hard 50-row cap that could permanently strand older MRs.
@@ -94,7 +105,7 @@ yad-gate-sync:
         while read -r IID REF; do
           [ -n "$IID" ] || continue
           git checkout -q -B "$CI_DEFAULT_BRANCH" "origin/$CI_DEFAULT_BRANCH"
-          npx -y -p yadflow@3 yad gate ci --branch "$REF" --pr "$IID" --merged || rc=1
+          npx -y -p "yadflow@${YAD_VERSION:-3}" yad gate ci --branch "$REF" --pr "$IID" --merged || rc=1
         done < /tmp/yad-merged-mrs
       else
         # MERGE push to the default branch whose commit names a review branch: resolve the merged MR's
@@ -106,7 +117,7 @@ yad-gate-sync:
           IID="$(glab api "projects/:id/merge_requests?source_branch=${REVIEW_BRANCH}&state=merged" 2>/dev/null | jq -r '.[0].iid // empty' || true)"
           if [ -n "$IID" ]; then
             # Pass --pr + IID as two distinct args (avoid a fragile, shell-dependent ${IID:+...} split).
-            npx -y -p yadflow@3 yad gate ci --branch "$REVIEW_BRANCH" --pr "$IID" --merged || rc=1
+            npx -y -p "yadflow@${YAD_VERSION:-3}" yad gate ci --branch "$REVIEW_BRANCH" --pr "$IID" --merged || rc=1
           else
             # Without the IID, gate ci cannot re-read approvals — fail visibly (the scheduled sweep
             # retries) rather than running a green no-op that silently leaves the gate unadvanced.