yadflow 3.18.1 → 4.0.0-next.1

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

@@ -1,70 +1,163 @@
-# Login roster — schema, resolution, per-repo routing
-
-The roster lives in `.sdlc/hub.json` (`roster: [...]`) and is the only thing that turns a platform
-**login** into an SDLC **name + role** for the ledger. Schema and the no-tokens rule are documented once
-in `../../yad-connect-repos/references/hub-config.md`; this file covers how the bridge *uses* it.
-It is populated/edited any time with the `yad roster` CLI command (see that reference).
-
-## Entry
-
-```json
-{
-  "login": "abdelrahmannasr",
-  "name": "alice",
-  "email": "alice@example.com",
-  "roles": { "hub": ["owner", "reviewer"], "backend": ["domain-owner"] }
-}
-```
-
-- `login` — the GitHub/GitLab username whose review/approval is being mapped.
-- `name` — the SDLC name written to `approvals.json` / `comments.json` (the same names as `epic.md`
-  `owner` and `repos.json` `domain_owner`). Keep it stable.
-- `email` — the commit email; drives the **committer → login** reverse lookup used to auto-assign PRs.
-- `roles` — a **per-scope map** from a scope (`hub`, or a connected repo name) to the roles held there
-  (`owner` / `reviewer` / `domain-owner`). A person can hold several roles in one scope (owner **and**
-  reviewer **and** domain-owner at once), and several scopes; a repo gets several owners/reviewers/
-  domain-owners by being listed in several people's maps.
-
-**Back-compat (read on all three shapes):** the per-scope object above; a flat array
-`"roles": ["owner","reviewer"]` (treated as `hub` roles); and the legacy single `"role": "owner"`
-(a `hub` role). The legacy `repos.json` `domain_owner` field is still honored (see Resolution step 2).
-
-## Resolution
-
-1. **login → name + roles** from the roster. The `hub` roles map straight to records; each touched
-   domain `R` contributes the roles in `roles[R]` (a `domain-owner` role carries `domain: R`).
-2. **Legacy domain-owner fallback:** if the resolved `name` equals a repo's `domain_owner` in
-   `repos.json`, and that repo is a **touched domain** for the step under review, the bridge also emits a
-   `domain-owner` approval scoped to that repo (`domain: <repo>`). One person owning several repos yields
-   several `domain-owner` records with different `domain` values — exactly what the gate predicate allows.
-3. **Unmapped login → reviewer (flagged).** A login not in the roster maps to `name: <login>`,
-   `role: reviewer`, with `<!-- unverified login: <login> -->` in the review record. It counts as a
-   reviewer but is **never** auto-promoted to owner/domain-owner, so a stranger can never satisfy the
-   owner/domain-owner requirement. The marker prompts a human to add the login to the roster.
-
-## Auto-assignee / auto-reviewer on PR/MR open
-
-When a review PR/MR is opened (hub `yad gate open`, or a code-repo `yad open-pr`):
-
-- **Assignee = the committer/opener** — resolved from local git identity (`user.email`, then
-  `user.name`) through the roster (`email`/`name`/`login`). On GitHub an unresolved committer still
-  self-assigns via `@me`.
-- **Reviewers = `reviewer` + `domain-owner`** for the touched scope(s) (`hub` plus every touched
-  domain for a hub review; the repo itself for a code PR), **minus the committer** — you do not review
-  your own PR. The artifact **owner/author is recorded, not requested.**
-- Logins are validated against the hub during `yad setup` / `yad doctor` (`gh api users/<login>`,
-  `glab api users?username=<login>`); a miss is flagged `unverified` but never blocks (fail-open).
-
-## Per-repo routing (stories review, and any escalated step)
-
-The stories review needs a `domain-owner` per repo in the **union of every story's `repos`**. On the
-review PR the bridge makes this legible and enforceable:
-
-- Add a `domain:<repo>` **label** per touched repo.
-- **Request** each touched repo's `domain_owner` login as a reviewer (resolved via the roster).
-- On `sync`, an approval from login *L* maps to `domain-owner` for repo *R* **iff**
-  `repos.json[R].domain_owner == roster[L].name`. So a domain owner's approval is scoped to exactly the
-  repos they own, and a repo with no approving owner shows up as still-required in the gate report.
-
-This is the same touched-domains computation the gate uses (`../yad-review-gate/references/gating.md`):
-architecture+contract → `epic.repos`; stories → union of story `repos`.
+# Login attribution — who a record names
+
+This file used to describe the reviewer roster; E62 removed the roster, and it now describes how records
+are attributed without one.
+
+yadflow keeps **no stored list of people**. The platform already knows who reviewed, and repository
+access already decides who may approve. So every record names the **platform login** that acted.
+
+## Approvals and comments
+
+When `yad gate sync` (or CI, `yad gate ci`) reads a review PR/MR:
+
+- An approval becomes one `approvals.json` record per person:
+  ```json
+  { "artifact": "<artifact>", "step": "<step id>", "approver": "<platform login>", "status": "approved",
+    "date": "<YYYY-MM-DD>", "source": "bridge", "artifactHash": "<hash>", "approvedAt": "<time>",
+    "pr": <n>, "commit": "<sha>", "url": "<review url>", "reviewId": "<id>", "engagement": "verified|none" }
+  ```
+  `pr` is present when the PR/MR number is known. There is no `role`, no `domain` and no `unverified`
+  flag. `commit`, `url` and `reviewId` are the platform's evidence for the review (E64), written only
+  when the platform gives them — GitHub gives all three; GitLab gives none of them, because an MR
+  approval is not tied to a commit. They are a record of what happened; the gate still decides on the
+  login and the fingerprint. `approvedAt` is the time the platform gives: GitHub's submission time, or
+  GitLab's `approved_at`. A GitLab instance that does not send `approved_at`, and every GitLab record
+  written before E64, hold the date the sync first recorded the approval instead. A date is read as
+  "time unknown", never compared with a time.
+- A comment becomes a `comments.json` record:
+  `{ artifact, step, commenter: <platform login>, round, count, date }` — no `role`.
+- The dated side file `reviews/<artifact>--<date>--approved.md` lists
+  `- <approver> — approved <date> (<source>)`. An older record's role is printed only if that record
+  still has one.
+
+There is no lookup step: the login the platform reports is the name written. The gate counts distinct
+`approver` values, so the same person is one approver however many records name them.
+
+**Local ledger (no platform).** The `yad-review-gate` skill writes the same shapes by hand. `approver` /
+`commenter` is the reviewer's platform login, or the name they give when there is no platform. A team
+gate needs 1 distinct approver (solo mode waives it); nothing checks that it is not the artifact's author, so do not record the
+author's own approval.
+
+## Older records
+
+Records written while the roster existed may carry `role` and `domain`, and may name a person by their
+roster `name` instead of their login. The gate never counts a role; the records stay on disk.
+
+On the first sync after the upgrade, `yad gate sync` recognises the person such a bridge record names,
+so it continues that record instead of treating the approval as new:
+0. **An exact submission time comes first (GitHub).** When exactly one older record holds the second a
+   review was submitted, that review continues it, whatever name the roster now gives it. It continues the
+   records **of that review only** — the ones holding that second — never the whole name: two people an
+   older release wrote under one name each keep their own record, and neither reads as the other's newer
+   review. A name already continued by a time is not an "orphan" for a later approval to guess at (step 2).
+   A match by name is per review too: when some of the name's records hold the approval's own time, it
+   continues those. On a closed step, a record under that name that no review continued is kept as
+   history. **Known cost (chosen 2026-09-17):** the records cannot tell two people who once shared a name
+   from one person whose role records ended up at two different times (older releases moved all of a
+   person's records together, so that needs a role dropped on a closed step and a later re-approval, or a
+   hand edit). Keeping protects the first, likelier case; in the second, that closed step lists the person
+   twice, so `gate status` shows one approver more. Nothing advances on a closed step. The name table
+   can be wrong — renaming one of two people who shared a name hands the older records to whoever kept
+   it. Older GitLab records hold only a date, so there a rename can still put an older approval on the
+   wrong person: **do not rename a shared roster name while reviews with older approvals are open.**
+1. **With the roster still on disk** — the roster's `name` → `login` pairs make the match exact. This is
+   the ONLY thing the roster is read for; it decides nothing about the gate. A name equal to another
+   entry's login is still exact (the older record under a name was written from that entry). The one
+   exception is a name the roster gives to TWO logins: a record under it could be either person, so it is
+   treated like a record no name can place (step 2), and `yad doctor` warns `people:roster-ambiguous`. A
+   record an older release marked `unverified` already names a login and is never translated.
+2. **Without a roster** — a record is continued only when nothing else could be it: the same submission
+   time (GitHub), or — on an open step only — exactly one unmatched approval against exactly one
+   unmatched older approver of that PR (GitLab, whose older records hold only a date — this rule still
+   applies when the approval now carries `approved_at`). People are never matched
+   by list order, and the result is the same whatever order the platform lists reviews in.
+3. The continued record keeps the fingerprint and dates it carried, unless the platform shows a newer
+   review (a later submission time — a time on both sides, so a date-only record never reads as older —
+   or a different PR/MR). When one person's older records
+   disagree, the **stale** one is kept — stale meaning outside the fingerprints the gate accepts for the
+   artifact (`acceptedHashes`), not merely different from today's hash.
+   A continued record is rewritten under the login and drops `role`, `domain` and `unverified`: they
+   count for nothing, and a `role` left on a login-named record would make the next sync read it as an
+   older record and look its login up as a roster name — which can be another person's. The dated
+   `reviews/<artifact>--<date>--approved.md` keeps the roles as they were.
+4. **Still ambiguous:** on a closed step nothing is added (its record is history, and a second entry would
+   count one person twice); on an open step the approval is recorded against a stale fingerprint from
+   those older records, so it must be given again on a new review. If none of those older records is
+   stale, there is nothing stale to bind to, and the approval is recorded against the current content.
+
+Comment rounds use the same name → login pairs, so the first sync does not open a new round for
+unchanged threads. Without the roster (or for a name two logins share) that sync may open one new round.
+
+## Recording the login on older records (E64)
+
+The steps above need the roster. So, while it is still on disk, every sync write (`yad gate sync`,
+`yad gate ci`) records the login on each older record the roster can place for certain. After that, only
+the records it could not place (below) still need the roster.
+
+- **What changes on a record.** `approver` / `commenter` becomes the login, and `role`, `domain` and
+  `unverified` are removed, exactly as step 3 rewrites a continued record. An approval keeps the name it
+  had in `rosterName`. Everything else — fingerprint, dates, `pr` — stays as it was. The dated
+  `reviews/*--approved.md` keeps the roles.
+- **One record per person, but only for one review.** An older release wrote one record per role, so one
+  approval can be several records. They become one record — keeping the stale fingerprint when they
+  disagree — only when they prove they are one review: every one holds the same submission **time** and
+  the same `pr`. A date is not proof. Every GitLab record from before E64 holds the day it was synced, so
+  two people a renamed roster now gives one name look the same; and a hand-written record holds no time
+  at all. Such records are left as they are. On GitLab this means one person's role records usually stay
+  as they are, and the roster keeps matching them on the next sync of their review.
+- **Also left as they are:** a record marked `unverified` (it names a login already), a record under a
+  name two logins share, a name the roster does not hold, and a comment round in which two records would
+  then name the same login.
+- **The exact time still wins.** An approval stamped onto the wrong login (a renamed shared name) keeps
+  `rosterName`, so step 0 still matches it by its submission time and hands it to the right person.
+- **When it runs.** `yad gate sync` stamps every step of the epic it writes, closed steps included. On a
+  verified Product, `yad gate ci` does it on every merge run — the merge event and the scheduled reconcile
+  that re-runs it — for **every** epic, including one with no open review, and commits it with the rest.
+  It never writes before a merge; it skips an epic with uncommitted changes under `.sdlc` or `reviews`;
+  a run whose sync fails leaves no stamp behind; and a record it cannot read, or an epic whose stamp fails, is left as it
+  is and named, in any epic — the merged review's own included — without stopping that merge. `yad gate sync <epic>` writes the stamp even when the epic
+  has no review PR on file. A Product with no platform never needs it: nothing there matches logins.
+- **When the roster can go.** `yad doctor`'s `people:roster-unused` says so: how many older records still
+  wait for a gate write (and in which epics), or that none do. Records it cannot place (a shared name,
+  records that disagree about the review) are then matched by submission time or given again on a new
+  review.
+
+## Who wrote a record (`by`)
+
+Skip, defer, closing records, kill-switch flips and mode changes carry a `by`. It is:
+
+1. the login `gh api user` (GitHub, asked on the repo's own host) or `glab api user` (GitLab) reports, else
+2. git `user.name`, else `null`.
+
+`YAD_PLATFORM_LOGIN=0` turns the platform lookup off (offline work, tests). The lookup is best effort and
+never blocks the command. Checkpoint and tidy commit subjects show `@<login>` when the login is known,
+else the git name.
+
+## Opening a PR/MR
+
+`yad gate open` (review PRs) and `yad open-pr` (task PRs):
+
+- **Assignee** = the person opening it: `@me` on GitHub (`gh` resolves it), the login `glab api user`
+  reports on GitLab (no assignee when that lookup fails).
+- **Reviewers: none are requested.** The command prints
+  `no reviewers were requested — ask them on the PR itself`. On a code-repo PR, `yad open-pr` then
+  prints a reviewer suggestion from recent history and CODEOWNERS (E68) — a hint, never a request.
+- **Labels (`yad gate open` only):** a `domain:<repo>` label per touched domain is still applied — for
+  `stories-review` the union of every story's `repos`, for a step tagged `contract`, `auth` or
+  `payments` the epic's `repos`. The labels are a hint for whom to ask; they add no approvals.
+  `yad open-pr` adds no labels.
+
+## Legacy data `yad doctor` reports
+
+None of these decides anything any more. `yad doctor` warns so the team can delete them:
+
+| Warning | What is left on disk |
+|---|---|
+| `people:roster-unused` | a non-empty `roster` in `.sdlc/hub.json` — still read for its name → login pairs only (see "Older records"); the hint counts the older records still waiting for a gate write to record their login, and says when it is safe to delete |
+| `people:roster-ambiguous` | a roster name given to more than one login (only checked when the roster is non-empty) |
+| `people:domain-owners-unused` | a repo in `.sdlc/repos.json` that lists `domain_owner` / `domain_owners` |
+| `people:verified-authors-unused` | a `verified_authors` list in `.sdlc/hub.json`, or a `.sdlc/verified-authors` file in the Product or a connected repo |
+| `people:allowlist-gate-stale` | an older `checks/verified-commits.sh` that still enforces the author list (a local-ledger Product's CI files are not refreshed by `yad check --fix`) |
+
+`yad roster` is removed (typing it prints a notice and exits 1), and `yad setup` collects no reviewers,
+roles, repo owners or commit emails. The verified-commits gate checks platform-Verified signatures only.

package/skills/yad-hub-bridge/templates/checks/hub-route.sh

@@ -1,8 +1,12 @@
 #!/usr/bin/env bash
-# Hub review routing — the front-half analogue of yad-pr-template's risk-route.sh. Reads a hub review
-# PR/MR description's "Impact & Risk (front-half)" block and prints the required reviewers, reusing
-# yad-review-gate's rule: base = owner + 1 reviewer; if a risk tag (contract|auth|payments) is set OR
-# the artifact is the stories set, ALSO a domain-owner per touched repo. Advisory: it ROUTES the human
+# Product review routing — the Shape analogue of yad-pr-template's risk-route.sh. Reads a Product review
+# PR/MR description's "Impact & Risk (front-half)" block and prints how many approvers the gate asks for,
+# as the same sum the gate prints: base 1, plus a risk step from the tags — `contract` +2, `auth` or
+# `payments` +1, the largest and never the sum. Only the base holds the gate; the risk step is advisory.
+# The gate reports that count capped at the number of active people less one (E72); this
+# script cannot count people, so it prints the full sum. There are no roles and no named owners: yadflow
+# keeps no list of people (E62), so when a risk tag raises the count the touched repos are printed as a
+# hint for whom to ask (with no risk step it prints the base line alone). Advisory: it ROUTES the human
 # review; it does not approve or merge.
 set -euo pipefail
 
@@ -18,33 +22,32 @@ value_of() {
 
 risk_tags="$(printf '%s' "$(value_of 'Risk tags:')" | tr 'A-Z' 'a-z')"
 repos="$(value_of 'Domains.*touched:')"
-artifact="$(value_of 'Artifact:')"
 
 echo "Risk tags: ${risk_tags:-none}"
 echo "Repos touched: ${repos:-unspecified}"
 
-escalate=no
+step=0
+tier=""
 why=""
-case "$risk_tags" in
-  *contract*) escalate=yes; why="risk tag: contract" ;;
-esac
-case "$risk_tags" in *auth*) escalate=yes; why="${why:+$why, }risk tag: auth" ;; esac
-case "$risk_tags" in *payments*) escalate=yes; why="${why:+$why, }risk tag: payments" ;; esac
-# The stories review routes per-repo even with no risk tag.
-case "$artifact" in *stories*) escalate=yes; why="${why:+$why, }stories per-repo routing" ;; esac
+# Whole tags only, as the gate reads them (`gateRuleFor`): `oauth` or `contracts` is not a risk tag.
+tags=" $(printf '%s' "$risk_tags" | tr ',;' '  ' | tr -s '[:space:]' ' ') "
+case "$tags" in *" auth "*) step=1; tier=high; why="risk tag: auth" ;; esac
+case "$tags" in *" payments "*) step=1; tier=high; why="${why:+$why, }risk tag: payments" ;; esac
+case "$tags" in *" contract "*) step=2; tier=contract; why="${why:+$why, }risk tag: contract" ;; esac
 
-if [ "$escalate" = "yes" ]; then
-  echo "ROUTE: ESCALATED (${why}) -> owner + 1 reviewer PLUS one domain-owner approval per touched repo"
-  echo "       (same escalation as yad-review-gate; map each repo to its domain_owner in repos.json)."
+if [ "$step" -gt 0 ]; then
+  echo "ROUTE: $((1 + step)) approvers = base 1 + ${tier} risk ${step} (${why})"
+  echo "       Only the base holds the gate: 1 approval (the platform decides whether the author may give it)."
+  echo "       The risk step is advisory; \`yad gate status\` prints it capped by the active people. Ask reviewers who know the touched repos:"
   case "$repos" in
     ""|*"<"*|*"…"*|*"|"*)
-      echo "  (Repos line not filled in — list each touched repo to route the domain owners.)" ;;
+      echo "  (Repos line not filled in — list each touched repo so the right reviewers can be asked.)" ;;
     *)
       printf '%s\n' "$repos" | tr ',' '\n' | while IFS= read -r r; do
         r="$(printf '%s' "$r" | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//')"
-        [ -n "$r" ] && echo "  - domain-owner: $r"
+        if [ -n "$r" ]; then echo "  - $r"; fi   # not `&&`: an empty last item (`a, b,`) would exit 1
       done ;;
   esac
 else
-  echo "ROUTE: base rule -> owner + 1 reviewer (no domain-owner escalation)."
+  echo "ROUTE: 1 approver = base 1 (no risk step)."
 fi

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

@@ -1,5 +1,5 @@
 # yad-managed: yad-hub-bridge
-# Merge-time gate sync for the PRODUCT HUB (Path B). CI is the SOLE writer of the ledger, and it
+# Merge-time gate sync for the PRODUCT (Path B). CI is the SOLE writer of the ledger, and it
 # writes ONLY at merge, ONLY to the default branch.
 #
 # During review there is NO CI write: the platform PR is the source of truth (native approvals +
@@ -24,7 +24,7 @@
 #   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). 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
+#   Product 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).
 #
@@ -48,13 +48,13 @@ permissions:
 
 env:
   # 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 →
+  # **variable** named YAD_VERSION to e.g. `4.0.0`, 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
+  # nobody deciding to upgrade — the amplification path in issue #163, where 3.13.1 took one Product from 20
   # to 96 churn commits an hour.
   YAD_VERSION: ${{ vars.YAD_VERSION || '' }}
 
@@ -87,9 +87,9 @@ jobs:
           # >>> 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
+          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this Product
           #   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
+          #   4. $YAD_MAJOR              — 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
@@ -98,20 +98,30 @@ jobs:
           # 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`.
+          # The major this fragment ships with. ONE literal, read by the check, the message and the fallback
+          # below, so they cannot drift apart; scripts/pin-major-check.sh holds it to the major a release
+          # publishes. `yad update` rewrites this file and re-stamps .sdlc/cli-version.json together, so a
+          # Product moves both to the new major at once — and a pin from an older major is skipped.
+          YAD_MAJOR=4
           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_pin_valid() { printf '%s' "${1:-}" | grep -Eq "^${YAD_MAJOR}\.[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
+              echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact ${YAD_MAJOR}.x release." >&2
             done
           fi
-          YAD_PKG="${YAD_PKG:-3}"
+          if [ -z "$YAD_PKG" ]; then
+            YAD_PKG="$YAD_MAJOR"
+            # A bare major is an npm RANGE, and a range never matches a prerelease: while only ${YAD_MAJOR}.0.0-next.N
+            # exists, npm fails with ETARGET. Say what to do before that happens.
+            echo "yad-gate-sync: no exact pin resolved — floating on yadflow@${YAD_MAJOR}. If npm cannot find it, run: yad update — and commit .sdlc/cli-version.json — or set YAD_VERSION." >&2
+          fi
           echo "yad-gate-sync: running yadflow@${YAD_PKG}"
           # <<< yad-pin
           echo "YAD_PKG=${YAD_PKG}" >> "$GITHUB_ENV"
@@ -155,9 +165,9 @@ jobs:
           # >>> 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
+          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this Product
           #   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
+          #   4. $YAD_MAJOR              — 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
@@ -166,20 +176,30 @@ jobs:
           # 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`.
+          # The major this fragment ships with. ONE literal, read by the check, the message and the fallback
+          # below, so they cannot drift apart; scripts/pin-major-check.sh holds it to the major a release
+          # publishes. `yad update` rewrites this file and re-stamps .sdlc/cli-version.json together, so a
+          # Product moves both to the new major at once — and a pin from an older major is skipped.
+          YAD_MAJOR=4
           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_pin_valid() { printf '%s' "${1:-}" | grep -Eq "^${YAD_MAJOR}\.[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
+              echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact ${YAD_MAJOR}.x release." >&2
             done
           fi
-          YAD_PKG="${YAD_PKG:-3}"
+          if [ -z "$YAD_PKG" ]; then
+            YAD_PKG="$YAD_MAJOR"
+            # A bare major is an npm RANGE, and a range never matches a prerelease: while only ${YAD_MAJOR}.0.0-next.N
+            # exists, npm fails with ETARGET. Say what to do before that happens.
+            echo "yad-gate-sync: no exact pin resolved — floating on yadflow@${YAD_MAJOR}. If npm cannot find it, run: yad update — and commit .sdlc/cli-version.json — or set YAD_VERSION." >&2
+          fi
           echo "yad-gate-sync: running yadflow@${YAD_PKG}"
           # <<< yad-pin
           echo "YAD_PKG=${YAD_PKG}" >> "$GITHUB_ENV"

package/skills/yad-hub-bridge/templates/gitlab/gitlab-ci.include-root.yml

@@ -1,5 +1,5 @@
-# SDLC gate sync — minimal root pipeline for the PRODUCT HUB.
-# Written by the yad-hub-bridge `wire` action ONLY when the hub has no existing root
+# SDLC gate sync — minimal root pipeline for the PRODUCT.
+# Written by the yad-hub-bridge `wire` action ONLY when the Product has no existing root
 # `.gitlab-ci.yml`. The job itself lives in the included fragment so the same single source is
 # reused whether or not a root pipeline already exists. If a root later grows real jobs, they
 # coexist with the included yad-* job (which carries `needs: []` and no `stage:`).

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

@@ -1,6 +1,6 @@
 # yad-managed-include: yad-hub-bridge
-# Merge-time gate sync for the PRODUCT HUB, as an INCLUDABLE fragment (Path B). Pulled into the
-# hub's root .gitlab-ci.yml via:
+# Merge-time gate sync for the PRODUCT, as an INCLUDABLE fragment (Path B). Pulled into the
+# Product's root .gitlab-ci.yml via:
 #   include:
 #     - local: '.gitlab/ci/yad-gate-sync.yml'
 # so wiring never edits the foreign root pipeline beyond that one include line. The job carries
@@ -34,16 +34,16 @@
 # default branch — the merge advance pushes there) and store it as a masked CI/CD variable
 # 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).
+# branch (advisory `yad gate sync` is read-only in verified mode and cannot recover a stuck gate).
 #
 # 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
+# took one Product from 20 to 96 churn commits an hour). The trade-off is deliberate and cuts both ways: a
+# Product 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 →
+# To override it, set a CI/CD variable YAD_VERSION (e.g. `4.0.0`) 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:
@@ -90,9 +90,9 @@ yad-gate-sync:
       # >>> 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
+      #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this Product
       #   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
+      #   4. $YAD_MAJOR              — 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
@@ -101,20 +101,30 @@ yad-gate-sync:
       # 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`).
+      # The major this fragment ships with. ONE literal, read by the check, the message and the fallback
+      # below, so they cannot drift apart; scripts/pin-major-check.sh holds it to the major a release
+      # publishes. `yad update` rewrites this file and re-stamps .sdlc/cli-version.json together, so a
+      # Product moves both to the new major at once — and a pin from an older major is skipped.
+      YAD_MAJOR=4
       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_pin_valid() { printf '%s' "${1:-}" | grep -Eq "^${YAD_MAJOR}\.[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
+          echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact ${YAD_MAJOR}.x release." >&2
         done
       fi
-      YAD_PKG="${YAD_PKG:-3}"
+      if [ -z "$YAD_PKG" ]; then
+        YAD_PKG="$YAD_MAJOR"
+        # A bare major is an npm RANGE, and a range never matches a prerelease: while only ${YAD_MAJOR}.0.0-next.N
+        # exists, npm fails with ETARGET. Say what to do before that happens.
+        echo "yad-gate-sync: no exact pin resolved — floating on yadflow@${YAD_MAJOR}. If npm cannot find it, run: yad update — and commit .sdlc/cli-version.json — or set YAD_VERSION." >&2
+      fi
       echo "yad-gate-sync: running yadflow@${YAD_PKG}"
       # <<< yad-pin
     - |
@@ -126,7 +136,7 @@ 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). This job runs an exact pin resolved from the repo, so a hub still sitting on a
+        # (issue #163). This job runs an exact pin resolved from the repo, so a Product 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)