yadflow 3.15.3 → 3.15.5

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [3.15.5](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.4...v3.15.5) (2026-08-12)
+
+
+### Bug Fixes
+
+* **bridge:** resolve the wired gate-sync pin from the repo, not a floating major ([8489bf5](https://github.com/abdelrahmannasr/yadflow/commit/8489bf5298f529868dc65085068882b59e89bbb5)), closes [#163](https://github.com/abdelrahmannasr/yadflow/issues/163) [#163](https://github.com/abdelrahmannasr/yadflow/issues/163)
+* **checks:** require a platform for the ledger-guard bridge gate ([297d13a](https://github.com/abdelrahmannasr/yadflow/commit/297d13a0ebf26bec995ce64e0aacfa022b228e18)), closes [#185](https://github.com/abdelrahmannasr/yadflow/issues/185) [#186](https://github.com/abdelrahmannasr/yadflow/issues/186)
+* **checks:** scope the ledger-guard bridge read to root-level keys ([4fb83a9](https://github.com/abdelrahmannasr/yadflow/commit/4fb83a968d4537e89a9367d72418aede9cf305f0)), closes [#186](https://github.com/abdelrahmannasr/yadflow/issues/186) [#186](https://github.com/abdelrahmannasr/yadflow/issues/186)
+
+## [3.15.4](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.3...v3.15.4) (2026-08-12)
+
 ## [3.15.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.2...v3.15.3) (2026-08-11)
 
 

package/cli/doctor.mjs

@@ -62,7 +62,11 @@ export function projectChecks(checks, root) {
   // version stamp
   const ver = readJSON(verPath, null);
   if (!ver) check(checks, 'cli-version', 'project', 'warn', `${PROJECT_FILES.version} missing or unreadable`, 'run `yad check --fix`');
-  else if (ver.version !== VERSION) check(checks, 'cli-version', 'project', 'warn', `project stamped v${ver.version}, CLI is v${VERSION}`, 'run `yad update` to reconcile');
+  // The stamp is not only cosmetic: in bridge mode the wired gate-sync job resolves the yadflow it
+  // RUNS from it — unless hub.json pins `gate_sync_version`, a YAD_VERSION variable overrides, or the
+  // stamp is not an exact release of the current major (then the job skips it and floats). So a stale
+  // stamp can mean CI is running an old gate; say so, or the warning reads as bookkeeping.
+  else if (ver.version !== VERSION) check(checks, 'cli-version', 'project', 'warn', `project stamped v${ver.version}, CLI is v${VERSION} — this also drives the wired gate-sync pin`, 'run `yad update` to reconcile');
   else check(checks, 'cli-version', 'project', 'ok', `version stamp matches (v${VERSION})`);
 
   // hub.json: parse + shape

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.15.3",
+  "version": "3.15.5",
   "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-architecture/SKILL.md

@@ -178,9 +178,22 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 > of hash-binding.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
-In `state.json`: set `architecture.status: "done"`, set `architecture-review.status: "in_review"`, and
-set `currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
-real reviewers approve, through the gate.
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit the artifact set — **`architecture.md`, `contract.md`, and
+`.sdlc/contract-lock.json`** (artifact-side, not ledger) — then hand off to `yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`architecture.status: "done"`, set `architecture-review.status: "in_review"`, and set
+`currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
+real reviewers approve, through the gate. On this branch `yad gate open` makes the same edit, so it
+is a no-op once the gate has run.
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the paths to `architecture.md`, `contract.md`, and `contract-lock.json`; the contract hash;

package/skills/yad-backfill/SKILL.md

@@ -99,6 +99,12 @@ thread off it, `promote` is what makes that anchor real — run it once the feat
   "wake" the state chain — set `currentStep: "epic"`, `epic` step `status: "in_progress"` — then run
   `yad-epic` → `yad-architecture` → … the normal way. This re-locks a contract that subsequent thread
   changes will inherit.
+- **Bridge mode — promote is not wired.** The `state.json` edits above mutate an epic whose ledger is
+  already on the base ref, so the `#162` seed exemption does not apply and `ledger-guard` rejects the
+  commit; unlike the authoring steps there is no `yad backfill` CLI and no `gate ci` path that performs
+  the promotion instead. On a bridge hub, STOP and report this — the promotion needs the gate bot (or a
+  maintainer landing it out of band). Only the `epic.md` half is safe to commit. Tracked as a gap; do
+  **not** push the ledger edit around the guard.
 - Never auto-advances; a human confirms the promotion.
 
 ### Step 7 — Stop (no auto-advance)

package/skills/yad-checks/SKILL.md

@@ -51,8 +51,11 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 - Canonical gate sources live in this skill's `templates/` (the source of truth that gets installed
   into each code repo):
   - `templates/checks/{spec-link,contract-check,build-test-lint,verified-commits}.sh`
-  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** (a no-op
-    when humans legitimately own the ledger). On review PRs it FAILs any commit that touches the
+  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** — hub.json
+    carries BOTH a `platform` and `bridge_enabled` (or the legacy `bridge`) true, the same predicate
+    `isBridge` (`cli/gate.mjs`) applies, so the gate and the CLI can never disagree about who owns the
+    ledger (#186). A no-op otherwise, when humans legitimately own it. 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. So is a **new epic's seed**:

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

@@ -20,16 +20,55 @@
 # distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
 # human edit and rejected.
 #
-# Scope: enforced ONLY when the bridge is enabled (a platform + gate-sync CI). Without the bridge
-# (file-only / non-bridge) humans legitimately write the ledger locally, so the gate is a no-op.
+# Scope: enforced ONLY when the bridge is enabled — hub.json carries BOTH a `platform` and
+# `bridge_enabled` (or the legacy `bridge`) true, the same predicate `isBridge` (cli/gate.mjs) and
+# `hubActions` (cli/plan.mjs) apply. Without the bridge (file-only / non-bridge, or a platform-less
+# hub) humans legitimately write the ledger locally, so the gate is a no-op.
 #
 # Degradation: a base ref that cannot be resolved FAILs closed; no platform (cannot read the Verified
 # badge) WARNs and waives the signature half — the same stance verified-commits takes.
 set -euo pipefail
 
 # ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
+# The predicate is BOTH a platform and the bridge flag, exactly as `isBridge` (cli/gate.mjs) and
+# `hubActions` (cli/plan.mjs) define it. Requiring the flag alone put this gate out of step with every
+# other bridge detector (issue #186): a hub carrying `bridge_enabled: true` with no `platform` would
+# have its human ledger commits rejected here while the CLI, reading the same file, called it
+# file-only and kept the LOCAL write path — no CI writer and no permitted human writer, so no gate
+# could advance. Reachable through a stale install (platform set, script wired, platform later
+# nulled), not through `yad setup`, which derives both from one value.
+#
+# `tr -d '\n'` first, like every other hub.json read in these gates: a key and its value may legally
+# sit on separate lines, and a per-line match would MISS the flag and silently no-op a security gate
+# (the fail-open direction of issue #161).
+#
+# Matched at the ROOT LEVEL only. The shared `default_branch` read below is depth-blind, and that is
+# survivable there — a false match yields a bogus branch name and the gate fails loudly. Here it is
+# not: a nested `"bridge": true` (say under `review`) would silently ENABLE this gate on a hub whose
+# `isBridge` is false, recreating the exact no-writer deadlock #186 is about, from the other side. So
+# the nesting is stripped rather than ignored: peel the outermost braces, then delete innermost
+# objects/arrays until none remain, leaving only root-level pairs to match against. Not a JSON parser
+# — a value containing a literal brace would confuse it — but hub.json is machine-written and the
+# failure it prevents is the one that matters.
+#
+# Flattened ONCE into a variable and matched with here-strings, never `tr … | grep -q`: under the
+# `pipefail` set above, `grep -q` exits at the first match and can SIGPIPE `tr`, which would make a
+# MATCHING pipeline report failure. Reading from a here-string has no upstream process to kill.
 HUB="${SDLC_HUB_CONFIG:-.sdlc/hub.json}"
-if [ ! -f "$HUB" ] || ! grep -Eq '"(bridge_enabled|bridge)"[[:space:]]*:[[:space:]]*true' "$HUB"; then
+HUB_FLAT="$(tr -d '\n' < "$HUB" 2>/dev/null || true)"
+HUB_ROOT="${HUB_FLAT#*\{}"
+HUB_ROOT="${HUB_ROOT%\}*}"
+while :; do
+  _stripped="$(sed -E 's/\{[^{}]*\}//g; s/\[[^][]*\]//g' <<< "$HUB_ROOT")"
+  [ "$_stripped" = "$HUB_ROOT" ] && break
+  HUB_ROOT="$_stripped"
+done
+# One line in, so `sed` emits at most one line out — no `head` needed (which would re-introduce the
+# SIGPIPE-under-pipefail problem this avoids).
+hub_str() { sed -nE "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p" <<< "$HUB_ROOT"; }
+hub_true() { grep -Eq "\"$1\"[[:space:]]*:[[:space:]]*true" <<< "$HUB_ROOT"; }
+
+if [ ! -f "$HUB" ] || [ -z "$(hub_str platform)" ] || { ! hub_true bridge_enabled && ! hub_true bridge; }; then
   echo "PASS [ledger-guard]: bridge not enabled — the ledger is locally owned, nothing to guard."
   exit 0
 fi

package/skills/yad-connect-repos/SKILL.md

@@ -148,7 +148,11 @@ write only `{project-root}/.sdlc/hub.json` (`config.yaml` `hub.config`) — neve
 - **`detect-hub`** — detect the hub's own platform and upsert `.sdlc/hub.json`. Run
   `git remote get-url origin` **on the hub** and read the host with the SAME logic Step 1 uses for code
   repos: `github.com` → `github`, GitLab host → `gitlab`, no remote → `platform: null`. Record
-  `git_url`, `default_branch`, `detectedAt`, and `bridge_enabled: true` (preserve an existing roster).
+  `git_url`, `default_branch`, `detectedAt`, and `bridge_enabled` — **`true` only when a platform was
+  detected, `false` alongside `platform: null`** (preserve an existing roster). The two travel
+  together: bridge mode is a platform AND the flag (`isBridge`, `cli/gate.mjs`), and `yad setup`
+  derives both from one value, so writing the flag onto a platform-less hub creates a state no CLI
+  path can produce and the gates read differently (#186).
   Auth is the local user's own `gh`/`glab`/git; **store no tokens**. Idempotent — safe to re-run.
 - **`roster`** — set one roster entry mapping a platform `login` → SDLC `name` + `email` + a per-scope
   `roles` map (`roles: { hub: ["owner","reviewer"], <repo>: ["domain-owner", …] }`). Upsert by `login`;

package/skills/yad-connect-repos/references/hub-config.md

@@ -18,7 +18,8 @@ login to an SDLC name + role. It is a single object for the hub itself — the s
   "platform": "github",                                       // github | gitlab (from the hub's own remote host); null when local-only
   "git_url": "https://github.com/abdelrahmannasr/yadflow.git", // REQUIRED when platform is non-null (scopes auth + opens PRs); yad doctor warns YAD-CFG-005 if absent
   "default_branch": "main",
-  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews
+  "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews; travels WITH platform — bridge mode is both (isBridge), so never true beside platform: null (#186)
+  "gate_sync_version": "3.15.3",                              // OPTIONAL exact pin for the wired gate-sync job; an exact 3.x.y, prereleases included (3.16.0-rc.1) — anything else is skipped. Omitted => the .sdlc/cli-version.json stamp if that qualifies, else floating 3
   "review": { "requireEngagement": false },                   // Review Companion: false (soft) counts bare approves but nudges; true counts only verified-engagement approvals
   "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
   "roster": [

package/skills/yad-epic/SKILL.md

@@ -169,14 +169,31 @@ Notes:
 
 ### Step 5b — Advance the authoring step — analysis-ran only
 *(Only when analysis ran — `state.json` already exists from `yad-analysis`.)*
-In `state.json`: set `epic.status: "done"`, set `epic-review.status: "in_review"`, and set
-`currentStep: "epic-review"`. Write `state.json`. Do **not** re-seed and do **not** touch
-`approvals.json` — only real reviewers approve, through the gate.
-
-> Since 3.11 the CLI closes the authoring step itself whenever its review gate opens or advances
-> (`yad gate open` / `sync`), so this edit is a no-op when the gate has already run. Keep making it —
-> it keeps `state.json` truthful before the gate opens — but it is no longer load-bearing: an epic
-> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`).
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit **`epic.md` only** — nothing else under `.sdlc/` — then hand off
+to `yad-review-gate`.
+
+> **This is not the Step 5 seed exemption.** `ledger-guard` exempts a *brand-new* epic's ledger
+> (creation, not mutation, #162). On this path `state.json` already exists from `yad-analysis` and
+> reached the base ref through the analysis review — so the guard is absolute here.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`epic.status: "done"`, set `epic-review.status: "in_review"`, and set `currentStep: "epic-review"`.
+Write `state.json`. Do **not** re-seed and do **not** touch `approvals.json` — only real reviewers
+approve, through the gate.
+
+> **File-only branch only.** Since 3.11 the CLI closes the authoring step itself whenever its review
+> gate opens or advances (`yad gate open` / `sync`), so this edit is a no-op when the gate has already
+> run. It keeps `state.json` truthful before the gate opens, but it is no longer load-bearing: an epic
+> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`). In bridge mode
+> `gate open` writes nothing and local `gate sync` is advisory — `gate ci` closes the step at merge.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `epic.md`, and that the next action is **review** via

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

@@ -103,9 +103,12 @@ 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
+   - the wired job runs an **exact** version, resolved at run time from the repo: the `YAD_VERSION`
+     variable, else `hub.json` `gate_sync_version`, else the `.sdlc/cli-version.json` stamp, else the
+     floating `3`. It stopped floating on the major because that let a release change a scheduled job's
+     behaviour unattended — how #163's churn reached hubs that never opted in. So upgrading is now a
+     deliberate act (`yad update`); if the resolved pin predates 3.15.3, upgrade or disable the
+     schedule. Never edit a version into the wired file — `yad check --fix` rewrites it byte-for-byte
      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

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

@@ -111,6 +111,9 @@ login and requested too — otherwise an escalated step is structurally unsatisf
 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.
+Since the wired job now runs an exact pin rather than floating on the major, that upgrade is a
+deliberate act: `yad update` (which re-stamps `.sdlc/cli-version.json`), or a `gate_sync_version` in
+`hub.json` — see the version table below.
 
 ## Contract re-lock invalidates prior platform approvals too
 
@@ -182,18 +185,32 @@ other way — up through its first review PR/MR; see "the seed of a new epic" be
 **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 |
+| # | Source | Set it in |
 |---|---|---|
-| 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.
+| 1 | `YAD_VERSION` — used **verbatim**, the operator's override | GitHub: Settings → Secrets and variables → Actions → **Variables**. GitLab: Settings → CI/CD → **Variables** (beside `SDLC_GATE_TOKEN`) |
+| 2 | `.sdlc/hub.json` → `gate_sync_version` — this hub's committed pin | edit `hub.json`, commit it |
+| 3 | `.sdlc/cli-version.json` → `version` — the yadflow that last wired the hub | `yad update` re-stamps it |
+| 4 | `3` — floating major, only when nothing above resolves | — |
+
+Sources 2 and 3 are **validated** before use: an exact `3.x.y` release token, prereleases included
+(`3.16.0-rc.1` is a legitimate pin; `latest` and a bare `3` are not). A `.sdlc/cli-version.json`
+written by a long-untouched project can still say something like `1.0.2`, a version with no `yad gate ci`
+in it at all, and the value is interpolated into `npx -p "yadflow@$V"` on a runner holding a push token —
+so anything that is not an exact release of this major is skipped, loudly, in favour of the next source.
+`YAD_VERSION` is exempt: it is a human's deliberate act, and it is the only way to cross a major.
+
+**Why this is no longer a floating major.** It used to be, on the argument that a published fix should
+reach a scheduled job with nobody in the loop — this page's own issue #163 as the example. The same
+mechanism is how #163's churn *arrived*: the CI fragment ran `yadflow@3`, so 3.13.1 rolled onto every
+wired hub automatically and took the reporting one from 20 to 96 churn commits an hour, with nobody
+deciding to upgrade. Issue #163's fourth suggested fix was to stop that. The trade-off is real and cuts
+both ways — a hub is no longer carried onto a fix for free, so **if the resolved pin is older than
+3.15.3, run `yad update` or disable the schedule** (`yad doctor` flags a stale stamp).
+
+The pin is **never stamped into 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 report `outdated` on every check and
+be reverted on the next sync. That is exactly why the job resolves it from committed files at run time
+instead — the fragment itself stays byte-identical to what ships.
 
 **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.
@@ -204,7 +221,10 @@ commit — the advance plus the `draft → approved` status flip — lands on th
 
 **The ledger is CI-owned (bridge mode only).** Humans never commit gate-state files: the `ledger-guard`
 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
+.json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). "Bridge mode" there
+means the same thing it means everywhere else — a `platform` **and** the bridge flag, `isBridge`'s
+predicate. The gate used to enable itself on the flag alone, which let a platform-less hub reject the
+human's ledger write while the CLI still expected one (#186). 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, with one carve-out for a new epic's seed (below). (The `verified-commits`
 gate still vets every commit's signature + author;

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

@@ -23,7 +23,9 @@
 #   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.
+#   #163). These jobs run an EXACT version resolved from the repo (see the resolver in each job), so a
+#   hub sitting on a pre-#163 yadflow keeps that behaviour until someone upgrades it — if the resolved
+#   pin is older than 3.15.3, run `yad update` or 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.
@@ -45,13 +47,16 @@ permissions:
   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' }}
+  # The manual override for which yadflow these jobs run: set a repository (or organization) Actions
+  # **variable** named YAD_VERSION to e.g. `3.15.2`, under Settings → Secrets and variables → Actions →
+  # Variables. It lives there and not in this file, which `yad` owns and rewrites byte-for-byte from
+  # its template on every sync — a version edited in here would be silently reverted.
+  #
+  # Left EMPTY the jobs resolve an exact pin from the repo itself instead of floating on the major (see
+  # the resolver step in each job). Floating meant a release could change what a scheduled job does with
+  # nobody deciding to upgrade — the amplification path in issue #163, where 3.13.1 took one hub from 20
+  # to 96 churn commits an hour.
+  YAD_VERSION: ${{ vars.YAD_VERSION || '' }}
 
 jobs:
   mergesync:
@@ -77,6 +82,39 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: "20"
+      - name: Resolve the yadflow pin
+        run: |
+          # >>> yad-pin
+          # Which yadflow this job runs, most explicit source first:
+          #   1. $YAD_VERSION            — the platform variable, a human's deliberate override, verbatim
+          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this hub
+          #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
+          #   4. 3                       — floating major, only when nothing above resolves
+          # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
+          # they are VALIDATED: an exact release token of the major this fragment was written for. That
+          # also keeps the value safe to interpolate into `npx -p "yadflow@$V"` — a repo-controlled
+          # string reaching a shell on a runner holding `contents: write` is the same class of hole the
+          # HEAD_REF fix closed. Anything unparseable is skipped loudly rather than failing the run.
+          # Pipes, not bash here-strings, so the block stays byte-identical to the GitLab fragment's
+          # (which must run under `sh` when an image has no bash). `sed` drains its input, so nothing
+          # SIGPIPEs `tr`.
+          yad_pin_read() { # <file> <key>
+            [ -f "$1" ] || return 0
+            tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
+          }
+          yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq '^3\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; }
+          YAD_PKG="${YAD_VERSION:-}"
+          if [ -z "$YAD_PKG" ]; then
+            for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+              [ -n "$_cand" ] || continue
+              if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
+              echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact 3.x release." >&2
+            done
+          fi
+          YAD_PKG="${YAD_PKG:-3}"
+          echo "yad-gate-sync: running yadflow@${YAD_PKG}"
+          # <<< yad-pin
+          echo "YAD_PKG=${YAD_PKG}" >> "$GITHUB_ENV"
       - 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
@@ -88,7 +126,7 @@ jobs:
         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@${YAD_VERSION}" yad gate ci \
+          npx -y -p "yadflow@${YAD_PKG}" yad gate ci \
             --branch "$HEAD_REF" \
             --pr "$PR_NUMBER" \
             --merged
@@ -112,6 +150,39 @@ jobs:
       - uses: actions/setup-node@v7
         with:
           node-version: "20"
+      - name: Resolve the yadflow pin
+        run: |
+          # >>> yad-pin
+          # Which yadflow this job runs, most explicit source first:
+          #   1. $YAD_VERSION            — the platform variable, a human's deliberate override, verbatim
+          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this hub
+          #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
+          #   4. 3                       — floating major, only when nothing above resolves
+          # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
+          # they are VALIDATED: an exact release token of the major this fragment was written for. That
+          # also keeps the value safe to interpolate into `npx -p "yadflow@$V"` — a repo-controlled
+          # string reaching a shell on a runner holding `contents: write` is the same class of hole the
+          # HEAD_REF fix closed. Anything unparseable is skipped loudly rather than failing the run.
+          # Pipes, not bash here-strings, so the block stays byte-identical to the GitLab fragment's
+          # (which must run under `sh` when an image has no bash). `sed` drains its input, so nothing
+          # SIGPIPEs `tr`.
+          yad_pin_read() { # <file> <key>
+            [ -f "$1" ] || return 0
+            tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
+          }
+          yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq '^3\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; }
+          YAD_PKG="${YAD_VERSION:-}"
+          if [ -z "$YAD_PKG" ]; then
+            for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+              [ -n "$_cand" ] || continue
+              if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
+              echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact 3.x release." >&2
+            done
+          fi
+          YAD_PKG="${YAD_PKG:-3}"
+          echo "yad-gate-sync: running yadflow@${YAD_PKG}"
+          # <<< yad-pin
+          echo "YAD_PKG=${YAD_PKG}" >> "$GITHUB_ENV"
       - name: Reconcile recently-merged review PRs
         run: |
           git config user.name  "yad-gate-sync[bot]"
@@ -130,7 +201,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@${YAD_VERSION}" yad gate ci --branch "$REF" --pr "$N" --merged || rc=1 ;;
+              review/EP-*) npx -y -p "yadflow@${YAD_PKG}" 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

@@ -36,12 +36,16 @@
 # 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.
+# Which yadflow this job runs: an EXACT version resolved from the repo at run time — see the `yad-pin`
+# block in the script below for the precedence. It no longer floats on the major, because floating let a
+# release change what a scheduled job does with nobody deciding to upgrade (issue #163, where 3.13.1
+# took one hub from 20 to 96 churn commits an hour). The trade-off is deliberate and cuts both ways: a
+# hub is no longer carried onto a fix automatically, so if the resolved pin is older than 3.15.3, run
+# `yad update` or disable this schedule.
+#
+# To override it, set 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 byte-for-byte from its template on every sync.
 variables:
   GIT_DEPTH: "0" # full history: gate ci pushes the advance to the default branch
 
@@ -82,6 +86,37 @@ yad-gate-sync:
     - export GITLAB_TOKEN="$SDLC_GATE_TOKEN" GITLAB_HOST="$CI_SERVER_URL"
     - git fetch origin "$CI_DEFAULT_BRANCH"
     - git checkout -B "$CI_DEFAULT_BRANCH" "origin/$CI_DEFAULT_BRANCH"
+    - |
+      # >>> yad-pin
+      # Which yadflow this job runs, most explicit source first:
+      #   1. $YAD_VERSION            — the CI/CD variable, a human's deliberate override, verbatim
+      #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this hub
+      #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
+      #   4. 3                       — floating major, only when nothing above resolves
+      # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
+      # they are VALIDATED: an exact release token of the major this fragment was written for. That
+      # also keeps the value safe to interpolate into `npx -p "yadflow@$V"` — a repo-controlled
+      # string reaching a shell on a runner holding a push token. Anything unparseable is skipped
+      # loudly rather than failing the run. Resolved once here; GitLab runs every `script` line in
+      # the same shell, so YAD_PKG carries into the block below.
+      # Pipes, not bash here-strings: a GitLab runner falls back to `sh` when the image has no bash,
+      # and `<<<` is a bashism. `sed` drains its input (no early exit, so nothing SIGPIPEs `tr`).
+      yad_pin_read() { # <file> <key>
+        [ -f "$1" ] || return 0
+        tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
+      }
+      yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq '^3\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$'; }
+      YAD_PKG="${YAD_VERSION:-}"
+      if [ -z "$YAD_PKG" ]; then
+        for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+          [ -n "$_cand" ] || continue
+          if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
+          echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact 3.x release." >&2
+        done
+      fi
+      YAD_PKG="${YAD_PKG:-3}"
+      echo "yad-gate-sync: running yadflow@${YAD_PKG}"
+      # <<< yad-pin
     - |
       rc=0
       if [ "$CI_PIPELINE_SOURCE" = "schedule" ]; then
@@ -91,7 +126,8 @@ yad-gate-sync:
         # 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.
+        # (issue #163). This job runs an exact pin resolved from the repo, so a hub still sitting on a
+        # pre-3.15.3 yadflow keeps that behaviour — upgrade it or 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.
@@ -105,7 +141,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@${YAD_VERSION:-3}" yad gate ci --branch "$REF" --pr "$IID" --merged || rc=1
+          npx -y -p "yadflow@${YAD_PKG}" 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
@@ -117,7 +153,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@${YAD_VERSION:-3}" yad gate ci --branch "$REVIEW_BRANCH" --pr "$IID" --merged || rc=1
+            npx -y -p "yadflow@${YAD_PKG}" 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

@@ -54,16 +54,28 @@ touched `repos` — never a forked or copied gate.
 
 ### Step 2 — Dispatch on `action`
 
+> **Check the mode first — in bridge mode you write nothing to the ledger.** Read `.sdlc/hub.json`:
+> **bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`. Under the bridge
+> the ledger is CI-owned — `ledger-guard` rejects any non-bot commit touching
+> `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`, local `yad gate
+> sync` is advisory, and `yad gate ci --merged` writes the whole transition when the review PR merges.
+> So every "set / append / write" instruction below is the **file-only, or a platform with no
+> gate-sync CI** path. In bridge mode do the human-facing half — present the artifact, route the
+> required reviewers, help the owner address comments — and let the platform PR/MR carry the review
+> state; the approvals, comments, review records and the advance all land through CI at merge.
+
 **`open`** — Present the artifact for review. Summarise what changed, list the required reviewers per
 the rule above, and tell reviewers how to comment/approve. Set the step `status` to `in_review` and
 `currentStep` to this step in `state.json` if not already. Do not advance.
 
-If `.sdlc/hub.json` has a non-null `platform`, `bridge_enabled: true`, `config.yaml` `hub.bridge: true`,
-and `gh`/`glab` is authenticated, **also open a review PR/MR on the hub** by invoking
-`yad-hub-bridge action: open` (epic + artifact). Record the PR in `epics/<epic>/.sdlc/hub-prs.json`
-(`{step, artifact, platform, number, url, branch, lastSyncedAt}`) and report the URL + required
-reviewers. Otherwise (no platform / disabled / no CLI) proceed **file-only** exactly as before — no
-error. Opening the PR records no approvals and never advances.
+If `.sdlc/hub.json` has a non-null `platform` and `bridge_enabled: true` (or legacy `bridge: true` —
+`.sdlc/hub.json` is the only source the CLI reads, see `isBridge` in `cli/gate.mjs`), and `gh`/`glab`
+is authenticated, **also open a review PR/MR on the hub** by invoking `yad-hub-bridge action: open`
+(epic + artifact), and report the URL + required reviewers. **CI records the PR** in
+`epics/<epic>/.sdlc/hub-prs.json` (`{step, artifact, platform, number, url, branch, lastSyncedAt}`) —
+write that file yourself only on the file-only path. Otherwise (no platform / disabled / no CLI)
+proceed **file-only** exactly as before — no error. Opening the PR records no approvals and never
+advances.
 
 **`comment`** — Capture reviewer feedback. Append/create a review file
 `reviews/<artifact-base>--<YYYY-MM-DD>--comments.md` with a heading per reviewer:

package/skills/yad-stories/SKILL.md

@@ -101,12 +101,26 @@ As a <role>, I want <capability>, so that <outcome>.
 `repos` is the field the later build phase reads to know where to scaffold specs — set it precisely.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
-In `state.json`: set `stories.status: "done"`, set `stories-review.status: "in_review"`, and set
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit **the story files under `stories/` only** — nothing else
+under `.sdlc/` — then hand off to `yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`stories.status: "done"`, set `stories-review.status: "in_review"`, and set
 `currentStep: "stories-review"`. Write `state.json`. Do **not** touch `approvals.json`.
 
-> Since 3.11 the CLI also closes the authoring step when its review gate opens or advances, so this
-> edit is a no-op once `yad gate open` has run. A `stories` step left `in_progress` behind a passed
-> `stories-review` used to block the parallel `test-cases` track (`YAD-STATE-005`).
+> **File-only branch only.** Since 3.11 the CLI also closes the authoring step when its review gate
+> opens or advances, so this edit is a no-op once `yad gate open` has run. A `stories` step left
+> `in_progress` behind a passed `stories-review` used to block the parallel `test-cases` track
+> (`YAD-STATE-005`). In bridge mode `gate open` writes nothing and local `gate sync` is advisory —
+> `gate ci` closes the step at merge.
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the story IDs created, the repos each touches, and that the next action is **review** via

package/skills/yad-test-cases/SKILL.md

@@ -162,9 +162,24 @@ Keep the `## Automation (<tool>)` section of `test-cases.md` in step with this f
 degraded (`testing: none`), do **not** write `test-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
-In `state.json`: set `test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave
-`currentStep` at `ready-for-build`** — this is the parallel track; moving `currentStep` would pull it
-back from the build half. Write `state.json`. Do **not** touch `approvals.json`.
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit the artifact set — **`test-cases.md` and, when a testing
+tool was used, `.sdlc/test-links.json`** (artifact-side, not ledger; generated tests live in their
+own code repo, not here) — then hand off to `yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave `currentStep` at
+`ready-for-build`** — this is the parallel track; moving `currentStep` would pull it back from the
+build half. Write `state.json`. Do **not** touch `approvals.json`. On this branch `yad gate open`
+makes the same edit — `markInReview` leaves `currentStep` alone once it is `ready-for-build`
+(`cli/epic-state.mjs`) — so it is a no-op once the gate has run.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the path to `test-cases.md`, the connected testing tool and what it produced (e.g. "Playwright —

package/skills/yad-ui/SKILL.md

@@ -171,8 +171,22 @@ Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file.
 (`design: none`), do **not** write `design-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
-In `state.json`: set `ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
-`currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`.
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit the artifact set — **`ui-design.md`, `DESIGN.md`, and, when a
+design tool was used, `.sdlc/design-links.json`** (artifact-side, not ledger) — then hand off to
+`yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
+`currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`. On this
+branch `yad gate open` makes the same edit, so it is a no-op once the gate has run.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, the connected design