yadflow 3.18.1 → 4.0.0-next.1

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

@@ -1,18 +1,18 @@
-# The bridge — PR/MR ↔ ledger mapping, read recipes, idempotency
+# the verified ledger — PR/MR ↔ ledger mapping, read recipes, idempotency
 
-The bridge maps platform review state onto the **same file records** the manual gate writes, so the gate
-predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The bridge only changes the
+the verified ledger maps platform review state onto the **same file records** the manual gate writes, so the gate
+predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The verified ledger only changes the
 *input path*; it never changes what passing the gate means.
 
 ## State mapping (platform → ledger)
 
 | 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 bridge carry `"source": "bridge"`; **manual** approvals have no such
+`approvals.json` records from the verified ledger carry `"source": "bridge"`; **manual** approvals have no such
 tag and are **never** touched by `sync` — the two coexist.
 
 ## Read recipes (read-only, local-user auth — no tokens)
@@ -23,17 +23,17 @@ 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 bridge stores no tokens. If the CLI is missing/unauthenticated
-or the remote is unreachable, the bridge stops and the gate falls back to file-only (no error).
+All commands run as the **local user**; the verified ledger stores no tokens. If the CLI is missing/unauthenticated
+or the remote is unreachable, the verified ledger stops and the gate falls back to local (no error).
 
 > **GitLab read parity (GAP-6).** `readPrGitLab` reads approvals (`approved_by[]`) and discussions but
 > does **not** map a "Request changes" reviewer state to `CHANGES_REQUESTED` — on GitLab the blocking
@@ -41,70 +41,81 @@ or the remote is unreachable, the bridge stops and the gate falls back to file-o
 > 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 bridge 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
@@ -219,18 +245,18 @@ each `artifactHash` against the merged content, so revoke-on-change still holds.
 commit — the advance plus the `draft → approved` status flip — lands on the **default branch** with
 `[skip ci]`.
 
-**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). "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
+**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,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 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`
-opens the PR only; local `yad gate sync` is advisory in bridge mode (writes nothing). After a merge,
-everyone `git checkout <default> && git pull`. (Without the bridge, humans own the ledger locally and
+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.)
 
 **The one sanctioned human ledger write *in a review PR*: the seed of a new epic.** `gate ci` only
@@ -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
@@ -269,12 +295,13 @@ push retries with a rebase.
 - Protected default branch (GitHub): the merge advance needs to push it — prefer a ruleset bypass for
   Actions, else a fine-grained PAT as `SDLC_GATE_TOKEN` on the mergesync checkout.
 
-**Manual sync & recovery.** In bridge 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
+**Manual sync & recovery.** In verified mode `yad gate sync` is **advisory** (read-only) — it prints the
+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,
-unlike advisory `yad gate sync`). File-only mode (no platform) keeps `yad gate sync` as the local writer.
+unlike advisory `yad gate sync`). Local mode (no platform) keeps `yad gate sync` as the local writer.
 The file ledger is still the source of truth.
 
 Because CI records the `hub-prs.json` pointer only at merge, a review the ledger has never seen still
@@ -283,17 +310,17 @@ recorded pointer, `yad gate sync <epic> <artifact>` resolves the PR/MR from the
 (`review/<epic>/<artifact>`) itself, and `--pr <n>` names it outright:
 
 ```bash
-yad gate sync EP-x architecture.md --pr 42   # advisory in bridge mode; the writer without the bridge
+yad gate sync EP-x architecture.md --pr 42   # advisory in verified mode; the writer with a local ledger
 ```
 
 An explicit `--pr` also **overrides** a recorded pointer, since a re-opened review is a new PR the
 ledger has not seen. Before its reviewers are bound to the artifact's hash, the number is confirmed to
 be the PR for that artifact's review branch — a mismatch is refused, and a platform that cannot answer
-warns and proceeds. The bridge rule is unchanged: the resolved pointer is adopted into the ledger only
+warns and proceeds. The verified ledger rule is unchanged: the resolved pointer is adopted into the ledger only
 on the writer path, so a human never leaves a gate-state file in their working tree for `ledger-guard`
 to reject.
 
-**In bridge mode `gate sync` stays advisory even with `--pr`** — it prints the predicate and writes
+**In verified mode `gate sync` stays advisory even with `--pr`** — it prints the predicate and writes
 nothing, because CI owns the ledger. The recovery that actually writes is the command CI itself runs,
 on the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged`.
 
@@ -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.