yadflow 3.19.0-next.2 → 4.0.0-next.3

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

@@ -1,11 +1,11 @@
 ---
 name: yad-hub-bridge
-description: 'The templated PR/MR bridge for the Shape review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories / test-cases), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire merge-time sync on the hub: a CI workflow that runs `yad gate ci` when a human merges a review PR/MR — CI is the sole ledger writer and writes only at merge, on the default branch (during review the platform PR/MR is the source of truth; CI never touches the review branch). Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the local gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
+description: 'The templated PR/MR bridge for the Shape review gate. When the Product has a platform (.sdlc/hub.json), it opens a review PR/MR on the Product for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories / test-cases), applies the touched-domain labels (it requests no reviewers), and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire merge-time sync on the Product: a CI workflow that runs `yad gate ci` when a human merges a review PR/MR — CI is the sole ledger writer and writes only at merge, on the default branch (during review the platform PR/MR is the source of truth; CI never touches the review branch). Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the local gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
 ---
 
 # SDLC — Hub Review Bridge (the templated PR/MR bridge)
 
-**Goal:** Run the Shape review/comment/approval cycle through a **real PR/MR on the product hub**,
+**Goal:** Run the Shape review/comment/approval cycle through a **real PR/MR on the Product**,
 without changing the gate's predicate or making the file ledger optional. The verified ledger is an **alternate
 input path** into `yad-review-gate`: it opens a review PR for an artifact, reviewers approve/comment on
 the platform with **their own** `gh`/`glab` auth, and the gate's `sync` action (which calls this skill's
@@ -17,12 +17,13 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 
 ## Conventions
 
-- `{project-root}` is the **product hub**. Hub platform + reviewer roster live in `.sdlc/hub.json`
-  (`config.yaml` `hub.config`; schema in `../yad-connect-repos/references/hub-config.md`).
-- Per-step review-PR record: `epics/EP-<slug>/.sdlc/hub-prs.json` (`config.yaml` `hub.pr_ledger`) — a
+- `{project-root}` is the **Product**. The Product platform lives in `.sdlc/hub.json` — it holds no
+  list of people (`config.yaml` `product.config` (older projects: `hub.config`); schema in `../yad-connect-repos/references/hub-config.md`).
+- Per-step review-PR record: `epics/EP-<slug>/.sdlc/product-prs.json`, written together with its
+  older name `hub-prs.json` (`config.yaml` `product.pr_ledger` (older projects: `hub.pr_ledger`)) — a
   sibling ledger to `approvals.json`, so `state.json`'s locked step shape is untouched.
-- The review-PR body is the hub template from `yad-pr-template` (`templates/hub/<platform>/…`).
-- Branch per artifact: `review/EP-<slug>/<artifact-base>` (`config.yaml` `hub.artifact_branch`).
+- The review-PR body is the Product template from `yad-pr-template` (`templates/hub/<platform>/…`).
+- Branch per artifact: `review/EP-<slug>/<artifact-base>` (`config.yaml` `product.artifact_branch` (older projects: `hub.artifact_branch`)).
 - **Local-user auth only; store no tokens.** Use the user's own `gh`/`glab`. If neither is installed/
   authenticated, STOP this path and tell the gate to fall back to local — never embed a credential.
 
@@ -35,31 +36,40 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 
 ## Preconditions (the verified ledger runs only when all hold)
 
-`.sdlc/hub.json` exists with a non-null `platform`, `ledger: "verified"` (or, before `yad migrate`, `bridge_enabled: true`), `config.yaml` `hub.bridge:
-true`, and `gh` (GitHub) / `glab` (GitLab) installed **and authenticated**. If any fails, report that the
+`.sdlc/hub.json` exists with a non-null `platform`, `ledger: "verified"` (or, before `yad migrate`, `bridge_enabled: true`), `config.yaml` `product.bridge: true`
+(older projects: `hub.bridge: true`), and `gh` (GitHub) / `glab` (GitLab) installed **and authenticated**. If any fails, report that the
 gate proceeds **local** (no error) and stop.
 
 ## On Activation
 
 ### Step 1 — Resolve platform + routing
-Read `.sdlc/hub.json` for the platform and roster, `epics/<epic>/epic.md` for `repos` + `owner`, and the
-matching `review+approve` step's `risk_tags` from `.sdlc/state.json`. Compute the **required reviewers**
-with `route` (below) — the same rule `yad-review-gate` enforces: base (owner + 1 reviewer); escalated
-(`risk_tags` ∩ {contract,auth,payments}, or the stories step) adds a domain-owner per touched repo. Map
-each required domain-owner to a platform `login` via the roster (a roster `name` equal to a repo's
-`domain_owner` in `repos.json` is that repo's domain-owner).
+Read `.sdlc/hub.json` for the platform, `epics/<epic>/epic.md` for `repos` + `owner` (the artifact's
+author), and the matching `review+approve` step's `risk_tags` from `.sdlc/state.json`. Compute the
+**count** with `route` (below) — the same rule `yad-review-gate` enforces: `needed = base 1 + risk step`
+distinct approvers, where `contract` adds 2 and `auth`/`payments` add 1 (the highest tag, never the sum).
+Only the base (1 distinct approver, who should not be the author) holds the gate; the risk step is
+advisory. The gate caps the count at the active people less one and prints it (E72), but does
+not enforce it yet; when it cannot count the people — as in Product CI, which checks out only the hub —
+no cap is shown. Compute the **touched domains** too: the union of story `repos` for
+`stories-review`, the epic's `repos` for a step tagged `contract`, `auth` or `payments`, none otherwise.
+They become `domain:<repo>` labels and
+are a hint for whom to ask. There is no roster to turn them into people.
 
 ### 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
+1. From the Product 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 — by the step's
+   `yad fold` commit (E44); `yad open-pr` warns when the step's files have changes no fold has committed. Push as the
    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/…`),
+2. Open the PR/MR with `gh`/`glab` using the Product 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
-   per-repo routing is legible on the PR.
+3. **Request no reviewers.** Assign the person opening it — `@me` on GitHub (`gh` resolves it), the
+   login `glab api user` reports on GitLab (no assignee when that lookup fails) — and add a
+   `domain:<repo>` label per touched repo. `yad gate open` prints
+   `no reviewers were requested — ask them on the PR itself`; the author asks people on the PR. (A Shape review PR gets no
+   reviewer suggestion: E68's suggestion reads a code change, so only `yad open-pr` (and `yad ship`) on a code repo prints it.)
 4. **Do not write the ledger.** CI is the sole writer and writes only at merge. During review nothing
    is recorded in the ledger — the platform PR/MR holds the review state (native approvals + threads).
    At merge, CI records the `hub-prs.json` entry (in the shape below) and advances on the default
@@ -68,22 +78,27 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
    { "step": "<review step id>", "artifact": "<artifact>", "platform": "github|gitlab",
      "number": <n>, "url": "<pr/mr url>", "branch": "review/EP-<slug>/<artifact-base>", "lastSyncedAt": null }
    ```
-   A human commit touching the gate-state files (`.sdlc/{state,approvals,comments,hub-prs}.json` or
+   A human commit touching the gate-state files (`.sdlc/{state,approvals,comments,product-prs,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 verified mode it opens the
    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
+5. Report the PR/MR URL and the count the step needs. **Do not** record approvals or advance — reviewers
    act on the platform; CI (`yad gate ci`) reconciles it onto the default branch at merge.
 
-### Step 3 — `route` (print required reviewers)
-Compute and print the required reviewers as above. Use `templates/checks/hub-route.sh <body>` to parse a
-PR/MR body's Impact & Risk block when given one; otherwise derive from `epic.repos` + the step's
-`risk_tags`. Advisory only — it routes the human review, it does not approve.
-
-### Step 4 — `wire` (merge-time sync on the hub)
-Install the hub CI that turns the human **merge** into a `yad gate ci` run, with CI as the **sole
+### Step 3 — `route` (print the count)
+Compute and print the count as above. Use `templates/checks/hub-route.sh <body>` to parse a PR/MR
+body's Impact & Risk block when given one; it prints e.g. `ROUTE: 3 approvers = base 1 + contract risk 2
+(risk tag: contract)`, says only the base holds the gate (1 approval), that the risk step is advisory
+and `yad gate status` prints it capped by the active people, and lists the touched repos as a hint for whom
+to ask. With no `contract`/`auth`/`payments` tag it prints `ROUTE: 1 approver = base 1 (no risk step).`
+and no repo list. Otherwise derive from
+`epic.repos` + the step's `risk_tags`. Stories do not route per repo. Advisory only — it routes the
+human review, it does not approve.
+
+### Step 4 — `wire` (merge-time sync on the Product)
+Install the Product CI that turns the human **merge** into a `yad gate ci` run, with CI as the **sole
 writer** of the ledger. There is no pre-merge CI write — during review the platform PR/MR is the
 source of truth (native approvals + threads). On merge, CI re-reads approvals from the platform,
 advances the step, and flips the artifact `status:` on the **default branch** (the only place CI ever
@@ -103,12 +118,15 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
    enabled bridge in `.sdlc/hub.json` it installs
    - GitHub → `.github/workflows/yad-gate-sync.yml` (from `templates/github/yad-gate-sync.yml`)
    - 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
+   - plus the Product-side **verified-commits** gate (`checks/verified-commits.sh` + its workflow/fragment,
+     owned by `yad-checks`) so review PRs accept only platform-Verified (signed) commits — there is no
+     author allowlist
    - 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
+     floating major the fragment ships with (`YAD_MAJOR`, `4` in this release) — a committed pin is used
+     only when it is an exact release of that major, so `yad update` moves the fragment and the stamp
+     to a new major together. It stopped floating on the major because that let a release change a scheduled job's
+     behaviour unattended — how #163's churn reached Products 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`.
@@ -128,7 +146,7 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
      case set the variable to a real tag. The variable lives in project settings, so it survives
      every `yad` sync. Single value only — `tags: [$VAR]` is one tag equal to the whole variable,
      not a comma-split.
-3. Commit the workflow to the hub. GitHub needs nothing else — the ephemeral `github.token` reads the
+3. Commit the workflow to the Product. GitHub needs nothing else — the ephemeral `github.token` reads the
    PR and pushes the merge advance to the default branch, and the workflow's reconcile **schedule**
    runs automatically (no setup) as the safety net that recovers a merge whose run failed transiently.
    If the default branch is protected, see the workflow header for the bypass / PAT options; until then
@@ -143,7 +161,8 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
   is the source of truth** and the gate predicate (in `yad-review-gate`) is unchanged.
 - **the verified ledger never approves on a reviewer's behalf.** Reviewers approve/merge with their own auth. The
   step advances when a human **merges** the approved, fully-resolved review PR (the merge is that human
-  act) — `yad gate sync` records the approvals + resolution + merged state and advances; unresolved
+  act) — `yad gate ci` at merge (or `yad gate sync` with a local ledger) records the approvals +
+  resolution + merged state and advances; unresolved
   comments or a changed artifact hold it `in_review`. The mechanical sync is the `yad gate` CLI.
 - **CI never approves and never merges.** The wired workflow only runs `gate ci` — the same sync +
   unchanged predicate. It does **nothing pre-merge** (the platform PR/MR holds the review state); at
@@ -154,7 +173,7 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
   ephemeral `github.token` (nothing stored). GitLab requires a stored masked `SDLC_GATE_TOKEN`
   project access token because `CI_JOB_TOKEN` can neither read the approvals API nor push — say so
   when wiring, and scope it to `read_api` + `write_repository` only.
-- **Protect the hub default branch.** Require that `epics/**` artifacts change only through a review
+- **Protect the Product 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"). Safe to require: a new epic's `.sdlc/` seed rides its first review PR/MR, so
@@ -164,6 +183,6 @@ default branch. (local mode keeps `yad gate sync` as the local writer.)
 ## Reference
 - PR-body→ledger mapping, the read-only gh/glab recipes, idempotent re-sync, contract re-lock handling:
   `references/bridge.md`.
-- Roster schema, login→role resolution, unverified-login fallback, per-repo routing: `references/login-roster.md`.
+- How approvals, comments and records are attributed to a platform login (no roster): `references/login-roster.md`.
 - The gate this feeds (open hook + sync action + unchanged predicate): `../yad-review-gate/SKILL.md`, `../yad-review-gate/references/gating.md`.
-- The hub PR/MR body template + the code-repo routing analogue: `../yad-pr-template/`.
+- The Product PR/MR body template + the code-repo routing analogue: `../yad-pr-template/`.

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

@@ -8,8 +8,8 @@ predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The verifi
 
 | Platform review state | Ledger effect |
 |---|---|
-| GitHub review `APPROVED` / GitLab MR approval (`approved_by`) | an `approved` record in `approvals.json`, role resolved from the roster (owner/reviewer) or derived domain-owner, tagged `"source": "bridge"` |
-| GitHub `COMMENTED` / `CHANGES_REQUESTED`; GitLab discussions/notes | a line under `## <name> (<role>)` in `reviews/<artifact>--<date>--comments.md` + a `comments.json` record; **never** an approval. `CHANGES_REQUESTED` is also flagged as blocking in the comments file |
+| GitHub review `APPROVED` / GitLab MR approval (`approved_by`) | one `approved` record per person in `approvals.json`, `approver` = the platform login, no role, tagged `"source": "bridge"` |
+| GitHub `COMMENTED` / `CHANGES_REQUESTED`; GitLab discussions/notes | a line under `## <login> (unresolved)` or `## <login> (changes requested — **blocking**)` in `reviews/<artifact>--<date>--comments.md` + a `comments.json` record (`commenter` = the login); **never** an approval. `CHANGES_REQUESTED` is also flagged as blocking in the comments file |
 | GitHub review dismissed / GitLab approval revoked | the prior bridge `approved` record for that approver is removed on re-sync **while the step is open**; once the step is `done` the record is kept as the audit trail of why it passed (see idempotency) |
 
 `approvals.json` records from the verified ledger carry `"source": "bridge"`; **manual** approvals have no such
@@ -23,13 +23,13 @@ gh pr view <n> --json reviews,comments,reviewDecision,latestReviews
 gh api repos/{owner}/{repo}/pulls/{n}/comments        # inline review comments
 ```
 - `reviews[].state` ∈ {APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED}; `reviews[].author.login` is
-  the login to resolve. Use `latestReviews` so a superseded earlier review doesn't double-count.
+  the login written to the record. Use `latestReviews` so a superseded earlier review doesn't double-count.
 
 **GitLab** (`glab` / `glab api`):
 ```
 glab mr view <n>
 glab api projects/:id/merge_requests/:iid/approvals     # approved_by[].user.username
-glab api projects/:id/merge_requests/:iid/notes          # discussion notes (comments)
+glab api projects/:id/merge_requests/:iid/discussions    # discussions + their notes (comments, resolvable threads)
 ```
 
 All commands run as the **local user**; the verified ledger stores no tokens. If the CLI is missing/unauthenticated
@@ -41,70 +41,81 @@ or the remote is unreachable, the verified ledger stops and the gate falls back
 > reviewer state. (GitHub maps both.) If you need GitLab "Request changes" honored, read
 > `reviewers[].state` from the MR and map it to `CHANGES_REQUESTED`.
 
-## Open recipes (request the reviewers — used by `yad gate open` / `yad open-pr`)
+## Open recipes (no reviewers requested — used by `yad gate open` / `yad open-pr`)
 
-Opening the review PR/MR must **request the required reviewers**, or an escalated gate is opened with
-nobody asked. The CLI (`createPr` in `cli/platform.mjs`) does this; an agent opening a PR by hand uses:
+Opening the review PR/MR **requests no reviewers**. yadflow keeps no list of people to pick them from
+(E62), so the command prints `no reviewers were requested — ask them on the PR itself`, and the author
+asks people on the PR. (On a code-repo PR, `yad open-pr` also prints a reviewer suggestion from recent history and CODEOWNERS — E68, a hint, never a request.) `yad gate open` assigns the opener and adds the touched-domain labels (`domain:<repo>`); `yad open-pr`
+assigns the opener and adds no labels. An agent opening a PR by hand
+uses:
 
-**GitHub** — create, then add each reviewer (a bad/non-collaborator login WARNS instead of aborting the
-whole create):
+**GitHub:**
 ```bash
 gh pr create --title "review: <artifact> (<epic>)" --body <body> --base <default> --head <branch> \
-  --assignee @me --label domain:<repo>
-gh pr edit <n> --add-reviewer <login>      # once per required reviewer
+  --assignee <login|@me> --label domain:<repo>
 ```
 
-**GitLab** — a Free/Core MR carries a **single** reviewer field (multiple reviewers is Premium), so
-assign the first required reviewer and **@-mention the rest in a note** so they are still notified/routed:
+**GitLab:**
 ```bash
 glab mr create --title "review: <artifact> (<epic>)" --description <body> \
-  --target-branch <default> --source-branch <branch> --reviewer <first-login> --label domain:<repo> --yes
-glab mr note <iid> -m "Review requested (owner + reviewer rule): @<l2> @<l3> — please review and approve/comment on this MR (this drives the gate)."
+  --target-branch <default> --source-branch <branch> --assignee <login> --label domain:<repo> --yes
 ```
-The read side counts a mentioned reviewer normally: their eventual **approval** still appears in
-`…/approvals → approved_by[]`, and their **note** in `…/discussions` — so the single-reviewer-field cap
-loses only the native "Reviewers" UI chip, not the gate routing.
 
-Required reviewers = the hub's `reviewer`/`domain-owner` roster logins for the touched scopes, PLUS any
-repo whose ownership lives only in `repos.json` `domain_owner`/`domain_owners` (those are resolved to a
-login and requested too — otherwise an escalated step is structurally unsatisfiable through routing).
+The assignee is `@me` on GitHub (`gh` resolves it on the repo's host) and the login `glab api user`
+reports on GitLab (none when that lookup fails). The `domain:<repo>` labels are the touched domains —
+for `stories-review` the union of every story's `repos`, for a step tagged `contract`, `auth` or
+`payments` the epic's `repos`, and none otherwise. They are a hint for whom to ask and add no
+approvals.
 
-## Login → role resolution (order)
+## Who a record names
 
-1. Roster (`.sdlc/hub.json`) maps `login` → `name` + base `role` (owner/reviewer).
-2. If that `name` equals a repo's `domain_owner` in `repos.json` **and** that repo is a touched domain
-   for this step → also emit a `domain-owner` record with `domain: <repo>`.
-3. Login not in the roster → `name: <login>`, `role: reviewer`, flagged
-   `<!-- unverified login: <login> -->`. **Never** auto-promoted to owner/domain-owner.
+The platform login that reviewed is written as `approver` / `commenter`. There is no lookup and no
+role, and no login is flagged `unverified`: the platform's record of who approved is the evidence, and
+repository access decides who may approve. A review with no login is not counted.
 
-(Full detail + per-repo routing: `login-roster.md`.)
+(Full detail, including older roster-era records and the `by` field: `login-roster.md`.)
 
 ## Idempotent re-sync
 
-- Key bridge approvals on `(step, approver, role, domain)`. On re-sync, **upsert** — do not append a
-  duplicate.
+- Key bridge approvals on `(step, approver)` — one record per person. On re-sync, **upsert** — do not
+  append a duplicate. An older record that still carries `role`/`domain` (and may name the person by
+  their old roster name) is recognised as `login-roster.md` → "Older records" describes (the roster's
+  name → login pairs first; never by list order), and replaced by one login-named record that keeps its
+  `artifactHash` and dates — unless the platform shows a newer review (a later submission time, with a
+  time on both sides, or a different PR/MR), which, as for any approval, binds to the current content.
+  Every sync write (`yad gate sync`, `yad gate ci`) also records the login on the older records the
+  roster can place for certain, on every step of the epic; only the records it cannot place still need the
+  roster on a later sync (`login-roster.md` → "Recording the login on older
+  records").
+- A bridge approval records the platform's evidence when it is given: `approvedAt` (GitHub's submission
+  time, GitLab's `approved_at`), and on GitHub the review's `commit`, `url` and `reviewId`. They are
+  audit only — the gate decides on the login and the fingerprint. A stored `approvedAt` that is only a
+  date (every GitLab record from before this) is "time unknown": it keeps its fingerprint and takes the
+  platform's time once.
 - **On an OPEN step**, remove any bridge approval whose platform review was dismissed/revoked: the
   platform is the live source of truth while the review is in flight.
 - **On a step already `done`**, the record is only added to or refreshed in place — an approval the
   platform no longer reports is **kept**. Those approvals are the audit record of *why* the gate
-  passed; a roster edit, an approval reset, or a degraded-but-successful read would otherwise erase
+  passed; an approval reset, or a degraded-but-successful read would otherwise erase
   them and leave the step `done` with zero approvals.
-- Key synced comments on the platform comment id so the same comment is not appended twice. Comment
-  rounds are recorded for an **open** step only, so re-visiting a merged review does not append a new
-  round per pass.
+- Record synced comments as one `comments.json` record per `(step, commenter, round)` with a `count`
+  (there is no per-comment id). A new round is opened only when the commenters or their counts change;
+  an unchanged re-read rewrites the latest round in place, keeping its date. Comment rounds are recorded
+  for an **open** step only, so re-visiting a merged review does not append a new round per pass.
 - 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
+- **Write the ledgers in a canonical order.** `approvals.json`, `comments.json` and the PR ledger
+  (`product-prs.json` + `hub-prs.json`, written together) 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
+  semantic change. That is issue #163: ~1,800 bot commits/day on the Product 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
+- Running `sync` twice on the same day 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
@@ -117,22 +128,24 @@ deliberate act: `yad update` (which re-stamps `.sdlc/cli-version.json`), or a `g
 
 ## Contract re-lock invalidates prior platform approvals too
 
-For the **architecture+contract** review, the gate already drops approvals when the contract-surface hash
-no longer matches `.sdlc/contract-lock.json`. The verified ledger extends this to platform-sourced approvals:
-`sync` discards bridge `approved` records for the architecture step dated **before** the new lock, and
-posts a comment on the review PR noting "contract re-locked — re-approval required". The escalation
-(`risk_tags: ["contract"]` → a domain-owner per repo) is unchanged.
+For the **architecture+contract** review, an approval's `artifactHash` is the contract-surface hash.
+When the surface changes and is re-locked, a bridge approval recorded against the old hash no longer
+matches, so the gate stops counting it (it shows as stale in `yad gate status`) — exactly as for a
+manual approval. Nothing is deleted by date and no comment is posted on the PR; the reviewer approves
+again, and a genuinely newer review (a later submission time, or a new PR/MR) binds to the new hash. The count
+(`risk_tags: ["contract"]` → 3 approvers, capped at the active people less one and reported; base 1
+enforced, risk step advisory) is unchanged.
 
 ## CHANGES_REQUESTED & unresolved threads hold the gate
 
 `CHANGES_REQUESTED` and any **unresolved review thread** are recorded as comments and surfaced as
 **blocking**. Under the PR-driven gate they actively hold the step `in_review`: the predicate does not
-pass while any thread is unresolved, even if the approval counts are met. The owner addresses the
+pass while any thread is unresolved, even if the approval count is met. The owner addresses the
 comments, replies, the reviewer **resolves** their thread, then `sync` runs again.
 
 ## Merge advances; an artifact change revokes approvals
 
-- **Merge → advance.** When the reviewer rule is satisfied, every thread is resolved, **and the review
+- **Merge → advance.** When the base count is met (1 distinct approver; the capped risk step is reported, not enforced; solo mode waives it), every thread is resolved, **and the review
   PR/MR is merged**, `sync` marks the step `done` and unblocks the next step. The merge is the human
   approval act — there is no separate machine advance. (`yad gate sync` performs this deterministically.)
 - **Revoke on artifact change (checked at merge).** Path B reconciles at merge, so an approval given
@@ -151,27 +164,30 @@ comments, replies, the reviewer **resolves** their thread, then `sync` runs agai
     advancing on approvals whose freshness cannot be proven (re-run `yad gate sync` to recover).
     CHANGES_REQUESTED is still honored, so a degraded read can only ever *hold* the gate.
   The `artifactHash` stamp still binds architecture approvals to the locked contract surface (see
-  "Contract re-lock" above).
-- **Known limitation — protect the hub default branch.** The advance hashes the artifact from the
+  "Contract re-lock" above). For every other artifact it covers the file WITHOUT its frontmatter
+  `status:` line, so the merge run's own `draft` → `approved` flip (and Build's `in-build` / `shipped`)
+  never revokes the approvals it just recorded (shape 9). An approval recorded before shape 9 hashed the
+  whole file, and is still read.
+- **Known limitation — protect the Product default branch.** The advance hashes the artifact from the
   default branch as it stands when CI runs, while approvals are SHA-bound to the reviewed PR/MR head.
   Those can differ if the artifact changes on the **base** outside this review while the PR/MR is open
   (the merge then integrates a change the reviewers never saw) or if a later out-of-band commit edits
   the merged artifact before a delayed reconcile advances it. In both cases each approval's commit
   still equals the reviewed head, so the SHA check passes, yet the live content was not reviewed. Close
-  it operationally: **require branch protection on the hub default branch so `epics/**` artifacts can
+  it operationally: **require branch protection on the Product default branch so `epics/**` artifacts can
   only change through their own review PR/MR** (one open review per artifact) — then the base copy of an
   artifact cannot move while its review is open, so the merged/live content always equals the reviewed
   content. (The complete in-code fix would hash the artifact at the reviewed PR-head revision before
   advancing; deferred in favor of the branch-protection mitigation.)
 
-## Event-driven sync (hub CI) — Path B
+## Event-driven sync (Product CI) — Path B
 
-The `wire` action (SKILL.md Step 4) installs CI on the hub so a **merge** drives `yad gate ci` —
+The `wire` action (SKILL.md Step 4) installs CI on the Product so a **merge** drives `yad gate ci` —
 **CI is the SOLE writer of the ledger, and it writes only at merge, only to the default branch.**
 During review CI writes nothing: the platform PR/MR is the source of truth (native approvals +
 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
+resolves it from the platform (GitLab), upserts the PR-ledger entry itself (under both names), and **re-reads
 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.)
@@ -183,28 +199,38 @@ other way — up through its first review PR/MR; see "the seed of a new epic" be
 | 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`:
+and fall back to the major the fragment ships with — `YAD_MAJOR` in its `yad-pin` block (`4` in this release):
 
 | # | Source | Set it in |
 |---|---|---|
 | 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 | — |
+| 2 | `.sdlc/hub.json` → `gate_sync_version` — this Product's committed pin | edit `hub.json`, commit it |
+| 3 | `.sdlc/cli-version.json` → `version` — the yadflow that last wired the Product | `yad update` re-stamps it |
+| 4 | `$YAD_MAJOR` — floating major, only when nothing above resolves. While only prereleases of that major exist (`4.0.0-next.N`) npm cannot resolve a bare major, so the job says so on stderr first; a Product wired by that release always has a stamp that 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`
+Sources 2 and 3 are **validated** before use: an exact release token of the fragment's own major, prereleases
+included (`4.16.0-rc.1` is a legitimate pin; `latest`, a bare `4` and a `3.x` 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.
 
+**A new major moves both files at once.** `yad update` rewrites the fragment from the release's template
+and re-stamps `.sdlc/cli-version.json` in the same run, so a Product that updates to 4.x gets a fragment
+with `YAD_MAJOR=4` and a `4.x` stamp together. A `gate_sync_version` pin in `hub.json` from the old major
+is then SKIPPED (the job logs `ignoring pin … not an exact 4.x release`) — update it or remove it. A
+fragment the team EDITED is kept by `yad update` while the stamp still moves, so an edited fragment on
+the old major would skip the new stamp; `yad update` names that case, and `--overwrite-local` replaces
+the fragment (saving the edit beside it). The
+fragment's major is held to the major a release publishes by `scripts/pin-major-check.sh`, a step of the
+release check.
+
 **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
+wired Product 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
+both ways — a Product 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
@@ -220,15 +246,15 @@ commit — the advance plus the `draft → approved` status flip — lands on th
 `[skip ci]`.
 
 **The ledger is CI-owned (verified 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}
+check (yad-checks) FAILs any commit on a review PR that touches `.sdlc/{state,approvals,comments,product-prs,hub-prs}
 .json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). "verified mode" there
 means the same thing it means everywhere else — a `platform` **and** the verified ledger flag, `isVerifiedLedger`'s
-predicate. The gate used to enable itself on the flag alone, which let a platform-less hub reject the
+predicate. The gate used to enable itself on the flag alone, which let a platform-less Product 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;
-its gate-bot exemption is now vestigial in-PR because CI no longer commits there.) `yad gate open`
+gate still vets every commit's platform-Verified signature — there is no author allowlist, and so no
+gate-bot exemption either.) `yad gate open`
 opens the PR only; local `yad gate sync` is advisory in verified mode (writes nothing). After a merge,
 everyone `git checkout <default> && git pull`. (with a local ledger, humans own the ledger locally and
 these guards are no-ops.)
@@ -248,8 +274,8 @@ 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 +
-roster-allowlisted author) vets it instead, exactly as it does for `yad checkpoint` and `yad update`.
+only inspects review PRs — never runs, and where the `yad-update-guard` (platform-Verified signature)
+vets it instead, exactly as it does for `yad checkpoint` and `yad update`.
 The command refuses to commit off the default branch unless `--allow-branch` is passed.
 
 **Loop prevention & races.** The only ledger commit lands on the **default branch** at merge, which
@@ -270,7 +296,8 @@ push retries with a rebase.
   Actions, else a fine-grained PAT as `SDLC_GATE_TOKEN` on the mergesync checkout.
 
 **Manual sync & recovery.** In verified mode `yad gate sync` is **advisory** (read-only) — it prints the
-predicate but writes nothing, so it is **not** a recovery path when CI fails. If a merge-time run fails
+predicate (and any `! may not be met:` / `! if the risk step were enforced:` warning, E73) but writes
+nothing, so it is **not** a recovery path when CI fails. If a merge-time run fails
 (can't push, API hiccup), recovery is the scheduled **reconcile** job (automatic; it re-advances merged
 reviews not yet `done`). To force it immediately, a maintainer runs the same command CI runs, locally on
 the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged` (this writes + pushes,
@@ -302,7 +329,7 @@ sweep's recent-MR window overlaps whatever the merge-push pipeline is handling
 one at a time (`concurrency: yad-gate-mergesync` on GitHub, `resource_group: yad-gate-mergesync` on
 GitLab). Without it both runs produce the same advance, one pushes, and the other rebases onto it and
 lands a duplicate `chore(gate): advance …` commit under a different SHA — unreviewed churn, since
-those commits carry `[skip ci]` and go straight to the default branch. An already-wired GitLab hub
+those commits carry `[skip ci]` and go straight to the default branch. An already-wired GitLab Product
 picks the `resource_group` up on the next `yad update` / `yad check --fix`.
 
 **`yad gate open` does not create or push the review branch.** It opens a PR/MR *against*
@@ -313,7 +340,7 @@ rather than failing inside `gh`/`glab`; an origin that cannot be reached at all
 
 ### Manual end-to-end verification (GitHub)
 
-1. On a scratch hub: `yad setup` (platform github, roster with a second account) → `yad check --fix`
+1. On a scratch Product: `yad setup` (platform github; a second account with write access to review) → `yad check --fix`
    installs `.github/workflows/yad-gate-sync.yml`; commit + push it.
 2. Author an epic → `yad gate open EP-x epic.md` → the review PR opens. CI writes nothing yet — review
    state lives on the platform.