yadflow 3.18.1 → 4.0.0-next.1

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

@@ -1,12 +1,12 @@
 ---
 name: yad-hub-bridge
-description: 'The templated PR/MR bridge for the front-half 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 file-only 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 front-half review/comment/approval cycle through a **real PR/MR on the product hub**,
-without changing the gate's predicate or making the file ledger optional. The bridge is an **alternate
+**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
 read recipes) maps that platform state into `approvals.json` / `comments.json` / `reviews/*.md`, then
@@ -17,14 +17,15 @@ 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 file-only — never embed a credential.
+  authenticated, STOP this path and tell the gate to fall back to local — never embed a credential.
 
 ## Inputs
 
@@ -33,33 +34,41 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 - `action`   — `open` | `route` | `wire` (default `route`). (`sync`'s ledger writes live in
   `yad-review-gate`; this skill provides the read recipes `sync` calls — see `references/bridge.md`.)
 
-## Preconditions (the bridge runs only when all hold)
+## Preconditions (the verified ledger runs only when all hold)
 
-`.sdlc/hub.json` exists with a non-null `platform`, `bridge_enabled: true`, `config.yaml` `hub.bridge:
-true`, and `gh` (GitHub) / `glab` (GitLab) installed **and authenticated**. If any fails, report that the
-gate proceeds **file-only** (no error) and stop.
+`.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
+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. 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 +77,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 bridge mode it opens the
+   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
@@ -94,21 +108,24 @@ Revoke-on-change is enforced at merge: on **GitHub** in code (an approval whose
 head is dropped — no setting needed); on **GitLab** it has no per-approval commit SHA, so enabling the
 platform's **"remove all approvals when commits are added to the source branch"** is **required** for
 the guarantee. Either way it is safe because CI never pushes the review branch — only the owner's own
-artifact pushes dismiss approvals. In bridge mode `yad gate sync` is advisory (read-only) and is **not**
+artifact pushes dismiss approvals. In verified mode `yad gate sync` is advisory (read-only) and is **not**
 a recovery path; if a merge-time run fails, the scheduled reconcile job re-advances it automatically, or
 a maintainer can force it with `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the
-default branch. (File-only mode keeps `yad gate sync` as the local writer.)
+default branch. (local mode keeps `yad gate sync` as the local writer.)
 
 1. Run `yad check --fix` (the wiring is manifest-driven, like `yad-checks`): with a platform +
    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 +145,7 @@ default branch. (File-only 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
@@ -139,31 +156,32 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
 ## Hard rules
 
 - **Local-user auth only; store no tokens.** Reviewers use their own `gh`/`glab`.
-- **The bridge is an input path, never the authority.** It opens PRs and reads state; the **file ledger
+- **the verified ledger is an input path, never the authority.** It opens PRs and reads state; the **file ledger
   is the source of truth** and the gate predicate (in `yad-review-gate`) is unchanged.
-- **The bridge never approves on a reviewer's behalf.** Reviewers approve/merge with their own auth. The
+- **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
   merge it re-reads approvals from the platform, advances the step, and flips the artifact status on
-  the **default branch** (the only place CI ever commits). CI is the sole ledger writer; front gates
+  the **default branch** (the only place CI ever commits). CI is the sole ledger writer; Shape gates
   stay permanently human.
 - **The CI tokens are the one documented bend of "no stored tokens".** GitHub uses the platform's own
   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
   nobody needs a direct push to the default branch to start an epic (#162).
-- **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs file-only with no error.
+- **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs local with no error.
 
 ## 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/`.