yadflow 3.15.1 → 3.15.3

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [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)
+
+
+### Bug Fixes
+
+* **checks:** exempt a new epic's ledger seed from ledger-guard ([ba923c2](https://github.com/abdelrahmannasr/yadflow/commit/ba923c2a3823e8bf17b2fc59b41f0160a3a11a19)), closes [#162](https://github.com/abdelrahmannasr/yadflow/issues/162)
+
 ## [3.15.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.0...v3.15.1) (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.1",
+  "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-analysis/SKILL.md

@@ -138,6 +138,10 @@ Notes:
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory.
+- Commit the seed on the `analysis/EP-<slug>` branch, and cut `review/EP-<slug>/analysis` from it so the
+  epic's **first** review PR/MR carries the ledger to the default branch. In bridge mode `ledger-guard`
+  exempts a new epic's ledger (creation, not mutation, #162); every later change to it is CI's. See
+  `../yad-epic/references/state-schema.md`, "Authoring branches".
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `analysis.md`, and that the next action is **review** via

package/skills/yad-change/SKILL.md

@@ -134,6 +134,12 @@ Seed `.sdlc/approvals.json` with one **provenance** record per inherited gate (N
 `{ "artifact": "<art>", "step": "<…-review>", "status": "inherited", "from": "<epic>", "boundHash": "<hash>", "date": "<today>" }`.
 Seed `.sdlc/comments.json` = `[]` and create `reviews/`.
 
+Commit the seed on the `change/EP-<slug>` branch. It reaches the hub's default branch through this
+change-epic's **first** review PR/MR — cut the `review/EP-<slug>/<artifact>` branch from `change/…` so
+it carries the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation,
+#162), so no direct push to a protected default branch is needed; every later change to that ledger is
+CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
+
 When `architecture` is **inherited**, materialize the **pointer-lock** `.sdlc/contract-lock.json`:
 `{ "artifact": "contract.md", "hash": "<parent surface hash, verbatim>", "lockedAt": "<today>", "inheritedFrom": "<epic>", "ref": "../../<epic>/.sdlc/contract-lock.json" }`.
 There is no `contract.md` in the change-epic, so the surface cannot drift, and `contract-check` passes

package/skills/yad-checks/SKILL.md

@@ -55,7 +55,11 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
     when humans legitimately own the ledger). On review PRs it FAILs any commit that touches the
     CI-owned gate ledger (`.sdlc/{state,approvals,comments,hub-prs}.json`, `reviews/*.md`) unless it
     is a **verified gate-bot commit** — bot-authored AND platform-Verified, since author text alone is
-    spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. Runs in `yad-hub-checks`
+    spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. So is a **new epic's seed**:
+    no CI path can create a ledger (`gate ci` only *advances* an existing chain, at merge, on the
+    default branch), so an epic whose `.sdlc/state.json` is absent from the base ref may be created by
+    a human on its first review PR/MR — **creation, not mutation** (#162). Once the ledger is on the
+    default branch the guard is absolute again. Runs in `yad-hub-checks`
     alongside `verified-commits` (which waives the allowlist for the bot but still requires its
     signature). See `yad-hub-bridge`.
   - `templates/github/yad-verified-commits.yml` + `templates/gitlab/yad-verified-commits.gitlab-ci.yml`

package/skills/yad-checks/templates/checks/ledger-guard.sh

@@ -11,6 +11,8 @@
 # NOT protected:
 #   epics/*/.sdlc/contract-lock.json — artifact-side: the architect locks the contract surface in
 #   `gate open`, so a human legitimately commits it alongside the architecture artifact.
+#   A brand-new epic's ledger — CREATION is not mutation (#162). No CI path can seed one, so the
+#   seed rides the first review PR/MR; see the carve-out below. Mutation stays bot-only.
 #
 # A "bot commit" must be BOTH authored by the gate bot (name/email contains yad-gate-sync) AND
 # platform-VERIFIED — author/committer text alone is user-controlled and spoofable, so the platform
@@ -114,19 +116,81 @@ trusted_bot() {
   signature_verified "$1"
 }
 
+# ---- seeding carve-out: creation is not mutation (#162) ---------------------------------------
+# A brand-new epic's ledger has no CI author. `gate ci` only ADVANCES an existing chain — it bails on
+# a missing state.json ("the review branch is cut from the default branch, so it should carry it") and
+# writes only at merge, on the default branch — and the engine itself reads a missing state.json as
+# "not seeded yet". `gate open` writes nothing in bridge mode, and `checkpoint` stages back-half
+# ledgers only. So the seed the authoring skills write (yad-epic / yad-change / yad-analysis /
+# yad-discovery / yad-stub) can reach the trunk ONLY through the first review PR/MR — the one place
+# this gate runs. Guarding it there makes the documented flow unshippable on a protected trunk, so an
+# epic whose ledger is absent from the BASE ref is exempt: that ledger is human-authored by
+# construction and the reviewer sees the whole of it in the diff. The moment its state.json is on the
+# base ref the guard is absolute again.
+#
+# Anchored on state.json — the ledger root, the same "is this epic seeded?" question the engine asks —
+# NOT on the individual file: adding hub-prs.json to an epic that IS on the base ref still FAILs.
+# Anchored on the BASE ref, not the parent commit, so delete-then-re-add cannot reset the exemption
+# (the deletion is itself a guarded change).
+#
+# The slug match is CASE-FOLDED on purpose. Git paths are byte-exact, but macOS/Windows checkouts are
+# not: seeding `epics/ep-x/.sdlc/state.json` beside an on-base `epics/EP-X/` would probe as a brand-new
+# epic, pass, and then land ON TOP of the real ledger in every case-insensitive clone — a mutation
+# laundered as a creation. So the base's seeded slugs are read once (one ls-tree, not one probe per
+# path) and compared folded.
+#
+# Slugs are held in ARRAYS read from NUL-delimited git output, never in a space- or newline-delimited
+# string: git permits a newline inside a path, and a `EP-<newline>x` slug split across two records
+# would drop the real epic out of the on-base list and let a mutation through as a "creation". Both
+# arrays carry one empty sentinel element so `"${a[@]}"` is safe under `set -u` on bash 3.2 (macOS),
+# which has no associative arrays; a slug is never empty, so the sentinel can never match.
+base_slugs=("")                     # every epic with a ledger on BASE, lowercased
+base_slugs_loaded=0
+noted_slugs=("")                    # slugs already announced, so the note prints once each
+fold() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+in_list() {                         # $1 = needle, $2… = haystack
+  _needle="$1"; shift
+  for _item in "$@"; do [ "$_item" = "$_needle" ] && return 0; done
+  return 1
+}
+is_seeding() {                      # $1 = epic slug; 0 when that epic has no ledger on BASE
+  if [ "$base_slugs_loaded" = 0 ]; then
+    while IFS= read -r -d '' _p; do
+      case "$_p" in
+        epics/*/.sdlc/state.json)
+          _s="${_p#epics/}"; _s="${_s%%/*}"
+          base_slugs[${#base_slugs[@]}]="$(fold "$_s")"
+          ;;
+      esac
+    done < <(git -c core.quotePath=false ls-tree -r --name-only -z "${BASE}" -- epics 2>/dev/null || true)
+    base_slugs_loaded=1
+  fi
+  _f="$(fold "$1")"
+  in_list "$_f" "${base_slugs[@]}"  && return 1
+  in_list "$_f" "${noted_slugs[@]}" && return 0
+  noted_slugs[${#noted_slugs[@]}]="$_f"
+  echo "note [ledger-guard]: epics/$1 has no ledger on ${BASE} — new epic, its seed is exempt (creation, not mutation)."
+  return 0
+}
+
 violations=0
 for sha in $commits; do
   touches_ledger=0
-  while IFS= read -r f; do
+  # quotePath=false + -z on both git reads: a path git chose to escape ("epics/EP-caf\303\251/…") and a
+  # path holding a newline both match no arm below, so the gate would fail OPEN on exactly the paths it
+  # is meant to guard. NUL is the only byte a git path cannot contain.
+  while IFS= read -r -d '' f; do
     [ -n "$f" ] || continue
     case "$f" in
       epics/*/.sdlc/contract-lock.json) ;; # artifact-side — allowed
       epics/*/.sdlc/state.json|epics/*/.sdlc/approvals.json|epics/*/.sdlc/comments.json|epics/*/.sdlc/hub-prs.json|epics/*/reviews/*.md)
+        _slug="${f#epics/}"; _slug="${_slug%%/*}"
+        is_seeding "$_slug" && continue      # a new epic's seed — not a mutation of a CI-owned ledger
         touches_ledger=1
         echo "  ${sha} (author $(git show -s --format='%an' "$sha")) → $f"
         ;;
     esac
-  done < <(git diff-tree --no-commit-id --name-only -r "$sha")
+  done < <(git -c core.quotePath=false diff-tree --no-commit-id --name-only -r -z "$sha")
   if [ "$touches_ledger" = 1 ] && ! trusted_bot "$sha"; then
     violations=$((violations + 1))
   fi
@@ -134,7 +198,18 @@ done
 
 if [ "$violations" -gt 0 ]; then
   echo "FAIL [ledger-guard]: ${violations} commit(s) change CI-owned gate files without a verified gate-bot signature. The ledger is CI-owned — let CI sync the gate; do not commit .sdlc/*.json or reviews/*.md yourself."
+  # An epic's seed is exempt only while its ledger is off the base ref. Once the first review PR merges
+  # (squashed or rebased, so the SHAs differ), those same seed commits still sitting on a sibling
+  # authoring branch read as mutations — the author did nothing wrong and the remedy is a rebase, so
+  # name it rather than leaving them with "do not commit the ledger yourself".
+  echo "hint [ledger-guard]: if these are seed commits from an already-merged review PR, rebase this branch onto the updated ${BASE} — the seed carve-out applies only until the ledger is on the base ref."
   exit 1
 fi
-echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit."
+# Say WHICH rule passed the range: claiming "every change is a bot commit" would be false on a range
+# whose only ledger change was a human seed the carve-out let through.
+if [ "${#noted_slugs[@]}" -gt 1 ]; then   # >1: the sentinel element is always there
+  echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit or a new epic's seed."
+else
+  echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit."
+fi
 exit 0

package/skills/yad-checks/templates/github/yad-hub-checks.yml

@@ -55,7 +55,9 @@ jobs:
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
           bash checks/pr-template.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$body"
 
-  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
+  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,hub-prs}.json
+  # or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
+  # brand-new epic's seed, which no CI path can write, so it rides this first review PR (#162).
   ledger-guard:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'

package/skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml

@@ -44,7 +44,9 @@ yad-hub-pr-template:
     - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
     - bash checks/pr-template.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
 
-# The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
+# The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,hub-prs}.json
+# or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
+# brand-new epic's seed, which no CI path can write, so it rides this first review MR (#162).
 yad-hub-ledger-guard:
   extends: .yad_hub_mr_only
   needs: []

package/skills/yad-discovery/SKILL.md

@@ -112,6 +112,10 @@ Notes:
   never escalates to domain owners (no contract surface is touched yet).
 - Also create an empty approvals ledger `.sdlc/approvals.json` and comments ledger
   `.sdlc/comments.json`, each containing `[]`, and the `reviews/` directory.
+- Commit the seed on the `discovery/EP-discovery` branch, and cut `review/EP-discovery/discovery` from
+  it so the **first** review PR/MR carries the ledger to the default branch. In bridge mode
+  `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162); every later change to it
+  is CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the path to the discovery set, and that the next action is **review** via `yad-review-gate`

package/skills/yad-epic/SKILL.md

@@ -152,6 +152,10 @@ Notes:
 - `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
   when `stories-review` passes — at which point the epic is already `ready-for-build`, so the build half
   runs alongside the tester. They never gate `ready-for-build` (see `references/state-schema.md`).
+- Commit the seed on this step's authoring branch. It reaches the hub's default branch through the
+  epic's **first** review PR/MR — cut `review/EP-<slug>/epic` from the authoring branch so it carries
+  the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162);
+  every later change to it is CI's. See `references/state-schema.md`, "Authoring branches".
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the

package/skills/yad-epic/references/state-schema.md

@@ -94,6 +94,16 @@ The shared procedure (run once the `EP-<slug>` is known):
    hub's default branch (`git checkout -b <step>/EP-<slug>`).
 3. Author and commit the step's artifact(s) on that branch. The bridge's `review/…` branch is created
    separately at review time and is untouched by this step.
+
+**How the seed reaches the default branch.** The `.sdlc/` ledger is seeded once, by hand, on the
+**entry** step's authoring branch (`analysis/…`, `epic/…`, `change/…`, `discovery/…`) — no CLI or CI
+path creates one (`yad gate ci` only *advances* an existing chain, at merge, on the default branch).
+So for the **first** gate of an epic, cut `review/EP-<slug>/<artifact-base>` from that authoring
+branch: the review PR/MR then carries the seed alongside the artifact, and the ledger lands on the
+default branch when it merges. In bridge mode `ledger-guard` exempts exactly this case — **creation,
+not mutation** (#162) — so no direct push to a protected default branch is needed. For every **later**
+gate the ledger is already on the default branch: cut the review branch from there, commit the
+artifact only, and leave `.sdlc/{state,approvals,comments,hub-prs}.json` and `reviews/*.md` to CI.
 | `type` | `author` \| `review+approve` | Authoring step or a team review gate. |
 | `artifact` | filename or folder | The file/folder this step produces or gates. |
 | `assistance` | `none` \| `review` \| `heavy` | Dial 1 — how much AI helps (build plan §2). |

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

@@ -52,7 +52,10 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
 ### Step 2 — `open` (create the review PR/MR)
 1. From the hub default branch, create `review/EP-<slug>/<artifact-base>` and ensure the artifact file
    (and, for architecture, `contract.md` + `.sdlc/contract-lock.json`) is committed on it. Push as the
-   local user.
+   local user. **First gate of a new epic:** cut the review branch from the **authoring** branch
+   (`epic/…`, `change/…`, `analysis/…`, `discovery/…`) instead, so it carries the `.sdlc/` **seed** —
+   that PR/MR is the only way a new epic's ledger reaches the default branch, and `ledger-guard`
+   exempts it (see step 4).
 2. Open the PR/MR with `gh`/`glab` using the hub body template (`yad-pr-template` `templates/hub/…`),
    filled with the epic, artifact, gate step, owner, `epic.repos`, and the step's risk tags.
 3. **Request the required reviewers** (their logins) and add a `domain:<repo>` label per touched repo so
@@ -68,7 +71,9 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
    A human commit touching the gate-state files (`.sdlc/{state,approvals,comments,hub-prs}.json` or
    `reviews/*.md`; `.sdlc/contract-lock.json` is artifact-side and allowed) on a review PR is rejected
    by the `ledger-guard` check. (The `yad gate open` CLI behaves the same: in bridge mode it opens the
-   PR only and writes no ledger.)
+   PR only and writes no ledger.) The **one** exception is a brand-new epic's **seed** — no CI path can
+   create a ledger, so an epic whose `.sdlc/state.json` is absent from the base ref may be created by a
+   human on this first PR/MR (#162). Every later change to it is CI's alone.
 5. Report the PR/MR URL and the required reviewers. **Do not** record approvals or advance — reviewers
    act on the platform; CI (`yad gate ci`) reconciles it onto the default branch at merge.
 
@@ -98,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;
@@ -143,7 +152,8 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
 - **Protect the hub default branch.** Require that `epics/**` artifacts change only through a review
   PR/MR (branch protection). This keeps revoke-on-change sound: it removes the only window where a
   delayed reconcile could advance on an out-of-band post-merge artifact change (see `references/bridge.md`,
-  "Known limitation").
+  "Known limitation"). Safe to require: a new epic's `.sdlc/` seed rides its first review PR/MR, so
+  nobody needs a direct push to the default branch to start an epic (#162).
 - **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs file-only with no error.
 
 ## Reference

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
@@ -155,7 +169,9 @@ During review CI writes nothing: the platform PR/MR is the source of truth (nati
 threads). The CLI is self-sufficient at merge: it derives the epic + artifact from the
 `review/EP-<slug>/<artifact-base>` head branch, takes the PR/MR number from the event (GitHub) or
 resolves it from the platform (GitLab), upserts the `hub-prs.json` entry itself, and **re-reads
-approvals fresh from the platform** — so no ledger needs to be pre-seeded on the branch.
+approvals fresh from the platform** — so no ledger needs to be pre-seeded on the branch. (It only
+*advances* a chain, though: it cannot **create** one. A brand-new epic's seed therefore travels the
+other way — up through its first review PR/MR; see "the seed of a new epic" below.)
 
 | Platform event | Phase | CI action |
 |---|---|---|
@@ -163,6 +179,22 @@ approvals fresh from the platform** — so no ledger needs to be pre-seeded on t
 | 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
@@ -174,13 +206,26 @@ commit — the advance plus the `draft → approved` status flip — lands on th
 check (yad-checks) FAILs any commit on a review PR that touches `.sdlc/{state,approvals,comments,hub-prs}
 .json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). Under Path B **no
 CI commit lands in a review PR at all**, so the only ledger change the guard can see there is a human
-edit — which it rejects. (The `verified-commits` gate still vets every commit's signature + author;
+edit — which it rejects, with one carve-out for a new epic's seed (below). (The `verified-commits`
+gate still vets every commit's signature + author;
 its gate-bot exemption is now vestigial in-PR because CI no longer commits there.) `yad gate open`
 opens the PR only; local `yad gate sync` is advisory in bridge mode (writes nothing). After a merge,
 everyone `git checkout <default> && git pull`. (Without the bridge, humans own the ledger locally and
 these guards are no-ops.)
 
-**The one sanctioned human ledger write: `yad gate repair`.** It heals a `YAD-STATE-005` chain (an
+**The one sanctioned human ledger write *in a review PR*: the seed of a new epic.** `gate ci` only
+**advances** an existing chain — it bails on a missing `state.json`, and the engine reads that absence
+as "not seeded yet" — so no CI path can ever create a ledger. The seed the authoring skills write
+(`yad-epic`, `yad-change`, `yad-analysis`, `yad-discovery`, `yad-stub`) can reach the default branch
+only through the epic's **first** review PR/MR, which is exactly where `ledger-guard` runs. So the gate
+exempts **creation**: an epic whose `.sdlc/state.json` is absent from the PR's base ref may have its
+ledger written by a human there (#162). It stays a narrow carve-out — the probe is against the base
+ref, not the parent commit, so deleting an on-trunk `state.json` to "re-seed" it is itself a rejected
+mutation, and the moment the ledger is on the default branch every further change is CI's alone. Cut
+that first review branch from the authoring branch (`epic/…`, `change/…`) so it carries the seed; no
+direct push to a protected default branch is needed.
+
+**The one sanctioned human ledger write *on the default branch*: `yad gate repair`.** It heals a `YAD-STATE-005` chain (an
 authoring step stranded behind a review gate that already advanced) by writing `state.json` alone. This
 is not a `ledger-guard` gap: the repair commits to the **default branch**, where `ledger-guard` — which
 only inspects review PRs — never runs, and where the `yad-update-guard` (platform-Verified signature +

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.

package/skills/yad-review-gate/SKILL.md

@@ -176,7 +176,9 @@ PR only — against the `review/<epic>/<artifact>` branch, which must already ex
 records this skill describes. The skill's
 job is the human half: presenting the artifact, helping the owner address comments, and narrating the
 gate. Local `yad gate sync` is advisory in bridge mode (reads the platform, prints status, writes
-nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it).
+nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it). The single
+exception is an epic's **seed** — no CI path can create a ledger, so a brand-new epic's `.sdlc/` rides
+its **first** review PR/MR, cut from the authoring branch (creation, not mutation, #162).
 
 Under that CLI the gate **advances on merge**: a review PR/MR whose reviewer rule is satisfied, whose
 comment threads are **all resolved**, and which has been **merged** auto-marks the step `done` and

package/skills/yad-stub/SKILL.md

@@ -115,6 +115,11 @@ into normal authoring with zero re-seeding.
 Also create the empty ledgers `{.sdlc/approvals.json}` and `{.sdlc/comments.json}` (each `[]`) and the
 `reviews/` directory. **Do NOT** write a `contract-lock.json` — a stub has no locked surface yet.
 
+Commit the seed on this step's authoring branch; it reaches the hub's default branch through the
+epic's **first** review PR/MR (or, for a stub, the PR that carries the stub itself). In bridge mode
+`ledger-guard` exempts a new epic's ledger — creation, not mutation (#162) — while every later change
+to it stays CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
+
 ### Step 6 — Stop; hand off (NO auto-advance)
 Report the new `EP-<slug>`, that it is a **stub (backfill pending)**, and the two next moves:
 - **File bugs now:** `yad-change` (`--parent EP-<slug>`, `kind: defect|change`) — the defect threads off