yadflow 4.0.0-next.3 → 4.0.0

package/skills/yad-pr-template/templates/checks/pr-template.sh

@@ -5,7 +5,7 @@
 # that bypassed the template.
 #   --profile code (default) — the code-repo task template (yad-pr-template templates/<platform>/):
 #     requires `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled `Risk level:` (low|medium|high).
-#   --profile hub — the Shape artifact-review template (templates/hub/<platform>/):
+#   --profile product (old name: hub) — the Shape artifact-review template (templates/product/<platform>/):
 #     requires `## Artifact under review`, `## Impact & Risk (front-half)` (or `(Shape)`), `## Checklist`, and a `Risk tags:` line.
 #     BUT only for review/EP-* head branches. Every other Product PR is a tooling/code change to the Product
 #     itself and uses the code task template instead; pass the head ref via --head so the gate knows
@@ -35,20 +35,22 @@ while [ $# -gt 0 ]; do
     *) ARGS+=("$1"); shift ;;
   esac
 done
-case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [pr-template]: unknown --profile '$PROFILE' (code|hub|product)."; exit 1 ;; esac
-# `product` is the new name for the `hub` profile and BOTH are accepted.
+case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [pr-template]: unknown --profile '$PROFILE' (code|product, or hub, the old name for product)."; exit 1 ;; esac
+# `product` is the Product's profile. `hub` is its old name, and BOTH are accepted.
 #
-# Not because the two sides update separately — they do not: this script and the workflow that passes
-# the flag are both in PRODUCT_WIRING (cli/manifest.mjs) and land together on one `yad update`. It is
-# the plain add-before-remove ladder instead: accept the new spelling now, switch the workflow
-# templates to emit it in a later release, drop the old one after that. Every shipped template still
-# passes `--profile hub` today, so this arm is dead weight until that switch — which is the point.
+# This script and the workflow that passes the flag are both in PRODUCT_WIRING (cli/manifest.mjs) and
+# normally land together on one `yad update` — but not always: a copy the team edited is kept. So the
+# order is add-before-remove: the new spelling was accepted first, the workflow templates switched to
+# emit it in E123 (`yad-product-checks.yml`), and the old one is dropped after that. `hub` stays
+# accepted meanwhile, for a workflow of the team's own or one they edited. The other direction — an
+# edited copy of THIS script from before 4.0, which rejects `product`, beside the new workflow — fails
+# every Product PR; `yad update` and `yad doctor` (`profile:`) say so.
 #
-# Normalised to `hub` immediately, so nothing below has to know there are two spellings. That is
-# load-bearing in pr-title.sh and pr-template.sh: leave `$PROFILE` as `product` and the `= hub`
+# Normalised to `product` immediately, so nothing below has to know there are two spellings. That is
+# load-bearing in pr-title.sh and pr-template.sh: leave `$PROFILE` as `hub` and the `= product`
 # branch is skipped, taking the whole review-branch arm with it — including the guard that stops a
 # plain code title carrying an artifact change past its review.
-[ "$PROFILE" = product ] && PROFILE=hub
+[ "$PROFILE" = hub ] && PROFILE=product
 
 
 # True when the PR changes a Shape artifact (anything under epics/** — or foundation/**, the Product level, E75). Reads the --changed list
@@ -115,14 +117,14 @@ check_code_body() {
 }
 
 # The Shape artifact-review template.
-check_hub_body() {
+check_product_body() {
   require_heading '## Artifact under review' '## Artifact under review'
   # Add before you remove (change-safety rule 3). `front-half` is the ORIGINAL spelling and it is
   # still what `yad gate open` emits and what the shipped Product template carries; `Shape` is the
   # replacement, accepted here first so that this script is lenient BEFORE anything starts writing
   # the new wording. That ordering is the whole point: this file is refreshed by `yad update`
   # (PRODUCT_WIRING, cli/manifest.mjs), but the PR template beside it is NOT — it is installed only by
-  # the `yad-pr-template repo:hub action: wire` skill, which nothing runs automatically. So a Product
+  # the `yad-pr-template repo:product action: wire` skill, which nothing runs automatically. So a Product
   # WILL sit with a refreshed checker next to an old template, and the checker has to accept both.
   # The emitter flips to `(Shape)` in the next major; only after that may `front-half` be dropped.
   require_heading '## Impact & Risk \((front-half|Shape)\)' '## Impact & Risk (front-half)'
@@ -134,9 +136,9 @@ check_hub_body() {
 }
 
 KIND="$PROFILE"
-if [ "$PROFILE" = hub ]; then
+if [ "$PROFILE" = product ]; then
   case "$HEADREF" in
-    review/EP-*|"") check_hub_body ;;            # artifact-review PR (or unknown head — stay strict)
+    review/EP-*|"") check_product_body ;;            # artifact-review PR (or unknown head — stay strict)
     *)
       # tooling/code change to the Product itself — UNLESS it changes Shape artifacts (epics/**),
       # which must go through a review/EP-* PR. Without this guard a non-review head could carry an
@@ -145,7 +147,7 @@ if [ "$PROFILE" = hub ]; then
         echo "FAIL [pr-template]: head '${HEADREF}' changes Shape artifacts (epics/** or foundation/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
         rc=1
       else
-        check_code_body; KIND="hub-tooling"
+        check_code_body; KIND="product-tooling"
       fi
       ;;
   esac

package/skills/yad-pr-template/templates/checks/pr-title.sh

@@ -4,7 +4,7 @@
 #   --profile code (default) — a Conventional-Commits subject "<type>: <description>", no trailing
 #     period (config.yaml build.pr_title_style: same_as_commit_subject; one task = one PR, the title is
 #     the squash-merge subject). Keep <type> in sync with cli/manifest.mjs COMMIT_TYPES.
-#   --profile hub — a Shape artifact-review title "review: <artifact> (EP-<slug>)", the shape
+#   --profile product (old name: hub) — a Shape artifact-review title "review: <artifact> (EP-<slug>)", the shape
 #     `yad gate open` creates (cli/gate.mjs) — BUT only for review/EP-* head branches. Every other
 #     Product PR is a tooling/code change to the Product itself and follows the code convention; pass the
 #     head ref via --head so the gate can tell the two apart (a tooling PR has no EP artifact to
@@ -34,20 +34,22 @@ while [ $# -gt 0 ]; do
     *) ARGS+=("$1"); shift ;;
   esac
 done
-case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [pr-title]: unknown --profile '$PROFILE' (code|hub|product)."; exit 1 ;; esac
-# `product` is the new name for the `hub` profile and BOTH are accepted.
+case "$PROFILE" in code|hub|product) ;; *) echo "FAIL [pr-title]: unknown --profile '$PROFILE' (code|product, or hub, the old name for product)."; exit 1 ;; esac
+# `product` is the Product's profile. `hub` is its old name, and BOTH are accepted.
 #
-# Not because the two sides update separately — they do not: this script and the workflow that passes
-# the flag are both in PRODUCT_WIRING (cli/manifest.mjs) and land together on one `yad update`. It is
-# the plain add-before-remove ladder instead: accept the new spelling now, switch the workflow
-# templates to emit it in a later release, drop the old one after that. Every shipped template still
-# passes `--profile hub` today, so this arm is dead weight until that switch — which is the point.
+# This script and the workflow that passes the flag are both in PRODUCT_WIRING (cli/manifest.mjs) and
+# normally land together on one `yad update` — but not always: a copy the team edited is kept. So the
+# order is add-before-remove: the new spelling was accepted first, the workflow templates switched to
+# emit it in E123 (`yad-product-checks.yml`), and the old one is dropped after that. `hub` stays
+# accepted meanwhile, for a workflow of the team's own or one they edited. The other direction — an
+# edited copy of THIS script from before 4.0, which rejects `product`, beside the new workflow — fails
+# every Product PR; `yad update` and `yad doctor` (`profile:`) say so.
 #
-# Normalised to `hub` immediately, so nothing below has to know there are two spellings. That is
-# load-bearing in pr-title.sh and pr-template.sh: leave `$PROFILE` as `product` and the `= hub`
+# Normalised to `product` immediately, so nothing below has to know there are two spellings. That is
+# load-bearing in pr-title.sh and pr-template.sh: leave `$PROFILE` as `hub` and the `= product`
 # branch is skipped, taking the whole review-branch arm with it — including the guard that stops a
 # plain code title carrying an artifact change past its review.
-[ "$PROFILE" = product ] && PROFILE=hub
+[ "$PROFILE" = hub ] && PROFILE=product
 
 
 # True when the PR changes a Shape artifact (anything under epics/** — or foundation/**, the Product level, E75). Reads the --changed list
@@ -84,12 +86,12 @@ check_code_title() {
   exit 0
 }
 
-if [ "$PROFILE" = hub ]; then
+if [ "$PROFILE" = product ]; then
   # review/EP-* head branch (or unknown head ref) => Shape artifact-review PR: 'review: <artifact> (EP-<slug>)'.
   case "$HEADREF" in
     review/EP-*|"")
       if printf '%s' "$TITLE" | grep -qE '^review: .+ \(EP-[a-z0-9-]+\)$'; then
-        echo "PASS [pr-title]: '${TITLE}' (profile: hub, artifact-review)"
+        echo "PASS [pr-title]: '${TITLE}' (profile: product, artifact-review)"
         exit 0
       fi
       echo "FAIL [pr-title]: '${TITLE}' is not a Product review title 'review: <artifact> (EP-<slug>)'."

package/skills/yad-pr-template/templates/{hub → product}/github/pull_request_template.md

@@ -1,4 +1,4 @@
-<!-- SDLC HUB PR template — Shape artifact review (epic / architecture+contract / ui-design / stories). -->
+<!-- SDLC Product PR template — Shape artifact review (epic / architecture+contract / ui-design / stories). -->
 <!-- This PR is a REVIEW VEHICLE on the Product, not a code merge. The file gate (yad-review-gate)
      advances the step when this PR is MERGED with the approvals met and every thread resolved. Reviewers
      approve/comment here; `yad gate sync` (or CI at merge, with a verified ledger) pulls that into the file ledger. -->
@@ -22,7 +22,7 @@
   `auth`/`payments`, 1 otherwise (the largest step, never the sum). No approval should be the author’s own.
 - Enforced: **1 approval** (the base). The risk step is **advisory**. `yad gate status <epic>`
   prints the count capped at the active people less one (one seat is left for the author), and
-  `yad-hub-bridge`'s `hub-route.sh` run on this description prints the full count.
+  `yad-product-bridge`'s `product-route.sh` run on this description prints the full count.
 - No reviewers are requested automatically — ask them on this PR. The `domain:<repo>` labels show the touched repos.
 
 ## How to review (this drives the gate)

package/skills/yad-pr-template/templates/{hub → product}/gitlab/merge_request_templates/Default.md

@@ -1,4 +1,4 @@
-<!-- SDLC HUB MR template — Shape artifact review (epic / architecture+contract / ui-design / stories). -->
+<!-- SDLC Product MR template — Shape artifact review (epic / architecture+contract / ui-design / stories). -->
 <!-- This MR is a REVIEW VEHICLE on the Product, not a code merge. The file gate (yad-review-gate)
      advances the step when this MR is MERGED with the approvals met and every thread resolved. Reviewers
      approve/comment here; `yad gate sync` (or CI at merge, with a verified ledger) pulls that into the file ledger. -->
@@ -31,7 +31,7 @@
   `auth`/`payments`, 1 otherwise (the largest step, never the sum). No approval should be the author’s own.
 - Enforced: **1 approval** (the base). The risk step is **advisory**. `yad gate status <epic>`
   prints the count capped at the active people less one (one seat is left for the author), and
-  `yad-hub-bridge`'s `hub-route.sh` run on this description prints the full count.
+  `yad-product-bridge`'s `product-route.sh` run on this description prints the full count.
 - No reviewers are requested automatically — ask them on this MR. The `domain:<repo>` labels show the touched repos.
 
 ## How to review (this drives the gate)

package/skills/{yad-hub-bridge → yad-product-bridge}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: yad-hub-bridge
-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.'
+name: yad-product-bridge
+description: 'The templated PR/MR bridge for the Shape review gate. When the Product has a platform (.sdlc/product.json), it opens a review PR/MR on the Product for an authored artifact (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)
+# SDLC — Product Review Bridge (the templated PR/MR bridge)
 
 **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
@@ -17,12 +17,12 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 
 ## Conventions
 
-- `{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`).
+- `{project-root}` is the **Product**. The Product platform lives in `.sdlc/product.json` (written together with its older name `.sdlc/hub.json`, same bytes, until v5; read from `hub.json` only when `product.json` is absent) — it holds no
+  list of people (`config.yaml` `product.config` (older projects: `hub.config`); schema in `../yad-connect-repos/references/product-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 Product template from `yad-pr-template` (`templates/hub/<platform>/…`).
+- The review-PR body is the Product template from `yad-pr-template` (`templates/product/<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.
@@ -36,20 +36,20 @@ 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` `product.bridge: true`
+`.sdlc/product.json` (or, on an older Product, `.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, `epics/<epic>/epic.md` for `repos` + `owner` (the artifact's
+Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name) 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 —
+not enforce it yet; when it cannot count the people — as in Product CI, which checks out only the Product —
 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
@@ -63,7 +63,7 @@ are a hint for whom to ask. There is no roster to turn them into people.
    (`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 Product body template (`yad-pr-template` `templates/hub/…`),
+2. Open the PR/MR with `gh`/`glab` using the Product body template (`yad-pr-template` `templates/product/…`),
    filled with the epic, artifact, gate step, owner, `epic.repos`, and the step's risk tags.
 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
@@ -72,7 +72,7 @@ are a hint for whom to ask. There is no roster to turn them into people.
    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
+   At merge, CI records the PR-ledger entry in the shape below (in `product-prs.json` and `hub-prs.json`) and advances on the default
    branch:
    ```json
    { "step": "<review step id>", "artifact": "<artifact>", "platform": "github|gitlab",
@@ -88,7 +88,7 @@ are a hint for whom to ask. There is no roster to turn them into people.
    act on the platform; CI (`yad gate ci`) reconciles it onto the default branch at merge.
 
 ### 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
+Compute and print the count as above. Use `templates/checks/product-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
@@ -103,7 +103,7 @@ writer** of the ledger. There is no pre-merge CI write — during review the pla
 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
 commits). Also install the `ledger-guard` check (yad-checks) so humans cannot commit gate-state files,
-and its local counterpart `hooks/ledger-guard.sh` — the harness hook that refuses an **agent** the
+and its local counterpart `hooks/ledger-guard.mjs` — the harness hook that refuses an **agent** the
 same write at the moment it tries it, instead of letting it surface as a CI failure later (#171).
 Revoke-on-change is enforced at merge: on **GitHub** in code (an approval whose commit ≠ the merged
 head is dropped — no setting needed); on **GitLab** it has no per-approval commit SHA, so enabling the
@@ -115,14 +115,14 @@ a maintainer can force it with `yad gate ci --branch <review-branch> --pr <n> --
 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
+   enabled bridge in `.sdlc/product.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 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
+     variable, else `product.json` `gate_sync_version` (`hub.json` when it is absent), else the `.sdlc/cli-version.json` stamp, else the
      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

package/skills/{yad-hub-bridge → yad-product-bridge}/references/bridge.md

@@ -102,7 +102,7 @@ repository access decides who may approve. A review with no login is not counted
   (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
+- Update the step's PR-ledger `lastSyncedAt` (`product-prs.json` + `hub-prs.json`, same bytes) 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 the PR ledger
@@ -124,7 +124,7 @@ permanently. On an older yadflow the workaround is to disable the pipeline sched
 advance gates via the push path; only the catch-up for squash merges and bare approvals is lost.
 Since the wired job now runs an exact pin rather than floating on the major, that upgrade is a
 deliberate act: `yad update` (which re-stamps `.sdlc/cli-version.json`), or a `gate_sync_version` in
-`hub.json` — see the version table below.
+`.sdlc/product.json` — see the version table below.
 
 ## Contract re-lock invalidates prior platform approvals too
 
@@ -204,7 +204,7 @@ and fall back to the major the fragment ships with — `YAD_MAJOR` in its `yad-p
 | # | 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 Product's committed pin | edit `hub.json`, commit it |
+| 2 | `.sdlc/product.json` → `gate_sync_version` (`.sdlc/hub.json` when `product.json` is absent) — this Product's committed pin | edit `product.json`, run `yad migrate --apply --keep product` (it copies it over `hub.json`; two that differ are refused, YAD-STATE-008), commit both. A Product that has only `hub.json`: edit that, and never create a `product.json` beside it by hand |
 | 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 | — |
 
@@ -217,8 +217,9 @@ so anything that is not an exact release of this major is skipped, loudly, in fa
 
 **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
+with `YAD_MAJOR=4` and a `4.x` stamp together. A `gate_sync_version` pin in `product.json` from the old major
+is then SKIPPED (the job logs `ignoring pin … not an exact 4.x release`) — update it or remove it (edit
+`product.json`, then `yad migrate --apply --keep product`; on a Product that has only `hub.json`, edit that). 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
@@ -287,13 +288,17 @@ which is exactly the intended revoke-on-change. Merge advances serialize on the
 push retries with a rebase.
 
 **Tokens.**
-- GitHub: the ephemeral `github.token` with `contents: write` + `pull-requests: read` — nothing stored.
-  Only the merge job pushes, and only the default branch.
+- GitHub: the ephemeral `github.token` — nothing stored. The workflow default is `contents: read`; the
+  two jobs that push (merge and reconcile) each ask for `contents: write` + `pull-requests: read`, and
+  push only the default branch.
 - GitLab: a masked `SDLC_GATE_TOKEN` project access token (`read_api` + `write_repository`) — the one
   documented bend of the no-stored-tokens rule; `CI_JOB_TOKEN` can neither read the approvals API nor
   push. Used only for the merge-time default-branch push + the API reads.
-- 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.
+- Protected default branch (GitHub): the merge advance needs to push it, and the built-in Actions token
+  cannot bypass branch protection or a ruleset (a ruleset's bypass list takes actors such as roles,
+  teams and GitHub Apps, never GitHub Actions). Pass a token whose owner may bypass to both jobs' `actions/checkout` — a GitHub
+  App on the bypass list, or a fine-grained PAT as `SDLC_GATE_TOKEN`. See yadflow's
+  `docs/branch-protection.md`.
 
 **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
@@ -304,7 +309,7 @@ the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged` (th
 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
+Because CI records the PR-ledger pointer (`product-prs.json` + `hub-prs.json`) only at merge, a review the ledger has never seen still
 has to be nameable — otherwise `sync` refuses a PR that is sitting merged on the platform. With no
 recorded pointer, `yad gate sync <epic> <artifact>` resolves the PR/MR from the review branch
 (`review/<epic>/<artifact>`) itself, and `--pr <n>` names it outright:

package/skills/{yad-hub-bridge → yad-product-bridge}/references/login-roster.md

@@ -153,10 +153,10 @@ None of these decides anything any more. `yad doctor` warns so the team can dele
 
 | Warning | What is left on disk |
 |---|---|
-| `people:roster-unused` | a non-empty `roster` in `.sdlc/hub.json` — still read for its name → login pairs only (see "Older records"); the hint counts the older records still waiting for a gate write to record their login, and says when it is safe to delete |
+| `people:roster-unused` | a non-empty `roster` in `.sdlc/product.json` — still read for its name → login pairs only (see "Older records"); the hint counts the older records still waiting for a gate write to record their login, and says when it is safe to delete |
 | `people:roster-ambiguous` | a roster name given to more than one login (only checked when the roster is non-empty) |
 | `people:domain-owners-unused` | a repo in `.sdlc/repos.json` that lists `domain_owner` / `domain_owners` |
-| `people:verified-authors-unused` | a `verified_authors` list in `.sdlc/hub.json`, or a `.sdlc/verified-authors` file in the Product or a connected repo |
+| `people:verified-authors-unused` | a `verified_authors` list in `.sdlc/product.json`, or a `.sdlc/verified-authors` file in the Product or a connected repo |
 | `people:allowlist-gate-stale` | an older `checks/verified-commits.sh` that still enforces the author list (a local-ledger Product's CI files are not refreshed by `yad check --fix`) |
 
 `yad roster` is removed (typing it prints a notice and exits 1), and `yad setup` collects no reviewers,

package/skills/{yad-hub-bridge/templates/checks/hub-route.sh → yad-product-bridge/templates/checks/product-route.sh}

@@ -10,8 +10,8 @@
 # review; it does not approve or merge.
 set -euo pipefail
 
-BODY="${1:?usage: hub-route.sh <hub-pr-description-file>}"
-[ -f "$BODY" ] || { echo "hub-route: file not found: $BODY" >&2; exit 2; }
+BODY="${1:?usage: product-route.sh <product-pr-description-file>}"
+[ -f "$BODY" ] || { echo "product-route: file not found: $BODY" >&2; exit 2; }
 
 # Value side of the FIRST line matching a label regex, comments + markdown markers stripped. Tolerant:
 # a missing label yields empty (never aborts) — an advisory helper must still print for a half-filled body.

package/skills/{yad-hub-bridge → yad-product-bridge}/templates/github/yad-gate-sync.yml

@@ -1,4 +1,4 @@
-# yad-managed: yad-hub-bridge
+# yad-managed: yad-product-bridge
 # Merge-time gate sync for the PRODUCT (Path B). CI is the SOLE writer of the ledger, and it
 # writes ONLY at merge, ONLY to the default branch.
 #
@@ -30,11 +30,13 @@
 #
 # CI never approves and never merges — the merge click is the human approval act.
 #
-# Protected default branch? Only these jobs push there. If the default branch is protected against
-# Actions:
-#   a) add a ruleset bypass so GitHub Actions may push to it, or
-#   b) store a fine-grained PAT as the SDLC_GATE_TOKEN secret and pass it to actions/checkout below
-#      via `with: { token: ${{ secrets.SDLC_GATE_TOKEN }} }` — see references/bridge.md.
+# Protected default branch? Only these jobs push there, and the built-in Actions token cannot get past
+# branch protection or a ruleset: a ruleset's bypass list takes actors such as roles, teams and GitHub
+# Apps, never GitHub Actions. So give the push a token whose owner may bypass, and pass it to actions/checkout
+# below via `with: { token: ${{ secrets.SDLC_GATE_TOKEN }} }`:
+#   a) a GitHub App on the bypass list (its installation token), or
+#   b) a fine-grained PAT of someone on the bypass list, stored as the SDLC_GATE_TOKEN secret.
+# See docs/branch-protection.md in the yadflow repo, and references/bridge.md.
 name: yad-gate-sync
 on:
   pull_request:
@@ -42,9 +44,10 @@ on:
   schedule:
     - cron: "*/15 * * * *"
 
+# Read-only by default. Each job below asks for the write access it needs, so a job added later
+# does not inherit a token that can push.
 permissions:
-  contents: write # push the merge-advance ledger commit to the default branch
-  pull-requests: read # gh pr view + reviewThreads GraphQL
+  contents: read
 
 env:
   # The manual override for which yadflow these jobs run: set a repository (or organization) Actions
@@ -71,15 +74,18 @@ jobs:
     concurrency:
       group: yad-gate-mergesync
       cancel-in-progress: false
+    permissions:
+      contents: write # push the merge-advance ledger commit to the default branch
+      pull-requests: read # gh pr view + reviewThreads GraphQL
     env:
       GH_TOKEN: ${{ github.token }}
     steps:
       # Check out the default branch — the merge already landed the artifact here.
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.base.ref }}
           fetch-depth: 0
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "20"
       - name: Resolve the yadflow pin
@@ -87,7 +93,7 @@ jobs:
           # >>> yad-pin
           # Which yadflow this job runs, most explicit source first:
           #   1. $YAD_VERSION            — the platform variable, a human's deliberate override, verbatim
-          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this Product
+          #   2. .sdlc/product.json      — "gate_sync_version" (.sdlc/hub.json when it is absent), the committed pin for this Product
           #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
           #   4. $YAD_MAJOR              — floating major, only when nothing above resolves
           # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
@@ -108,9 +114,11 @@ jobs:
             tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
           }
           yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq "^${YAD_MAJOR}\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?\$"; }
+          # The Product settings under their new name first (E122); the old one until v5 deletes it.
+          YAD_PIN_FILE=.sdlc/product.json; [ -f "$YAD_PIN_FILE" ] || YAD_PIN_FILE=.sdlc/hub.json
           YAD_PKG="${YAD_VERSION:-}"
           if [ -z "$YAD_PKG" ]; then
-            for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+            for _cand in "$(yad_pin_read "$YAD_PIN_FILE" gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
               [ -n "$_cand" ] || continue
               if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
               echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact ${YAD_MAJOR}.x release." >&2
@@ -150,14 +158,17 @@ jobs:
     concurrency:
       group: yad-gate-mergesync
       cancel-in-progress: false
+    permissions:
+      contents: write # push the merge-advance ledger commit to the default branch
+      pull-requests: read # gh pr view + reviewThreads GraphQL
     env:
       GH_TOKEN: ${{ github.token }}
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.repository.default_branch }}
           fetch-depth: 0
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "20"
       - name: Resolve the yadflow pin
@@ -165,7 +176,7 @@ jobs:
           # >>> yad-pin
           # Which yadflow this job runs, most explicit source first:
           #   1. $YAD_VERSION            — the platform variable, a human's deliberate override, verbatim
-          #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this Product
+          #   2. .sdlc/product.json      — "gate_sync_version" (.sdlc/hub.json when it is absent), the committed pin for this Product
           #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
           #   4. $YAD_MAJOR              — floating major, only when nothing above resolves
           # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
@@ -186,9 +197,11 @@ jobs:
             tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
           }
           yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq "^${YAD_MAJOR}\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?\$"; }
+          # The Product settings under their new name first (E122); the old one until v5 deletes it.
+          YAD_PIN_FILE=.sdlc/product.json; [ -f "$YAD_PIN_FILE" ] || YAD_PIN_FILE=.sdlc/hub.json
           YAD_PKG="${YAD_VERSION:-}"
           if [ -z "$YAD_PKG" ]; then
-            for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+            for _cand in "$(yad_pin_read "$YAD_PIN_FILE" gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
               [ -n "$_cand" ] || continue
               if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
               echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact ${YAD_MAJOR}.x release." >&2

package/skills/{yad-hub-bridge → yad-product-bridge}/templates/gitlab/gitlab-ci.include-root.yml

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

package/skills/{yad-hub-bridge → yad-product-bridge}/templates/gitlab/yad-gate-sync.gitlab-ci.yml

@@ -1,4 +1,4 @@
-# yad-managed-include: yad-hub-bridge
+# yad-managed-include: yad-product-bridge
 # Merge-time gate sync for the PRODUCT, as an INCLUDABLE fragment (Path B). Pulled into the
 # Product's root .gitlab-ci.yml via:
 #   include:
@@ -90,7 +90,7 @@ yad-gate-sync:
       # >>> yad-pin
       # Which yadflow this job runs, most explicit source first:
       #   1. $YAD_VERSION            — the CI/CD variable, a human's deliberate override, verbatim
-      #   2. .sdlc/hub.json          — "gate_sync_version", the committed pin for this Product
+      #   2. .sdlc/product.json      — "gate_sync_version" (.sdlc/hub.json when it is absent), the committed pin for this Product
       #   3. .sdlc/cli-version.json  — the version that last wired it (`yad update` re-stamps this)
       #   4. $YAD_MAJOR              — floating major, only when nothing above resolves
       # Sources 2 and 3 are machine-written files a stale or hand-edited checkout can get wrong, so
@@ -111,9 +111,11 @@ yad-gate-sync:
         tr -d '\n' < "$1" 2>/dev/null | sed -nE "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\1/p"
       }
       yad_pin_valid() { printf '%s' "${1:-}" | grep -Eq "^${YAD_MAJOR}\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?\$"; }
+      # The Product settings under their new name first (E122); the old one until v5 deletes it.
+      YAD_PIN_FILE=.sdlc/product.json; [ -f "$YAD_PIN_FILE" ] || YAD_PIN_FILE=.sdlc/hub.json
       YAD_PKG="${YAD_VERSION:-}"
       if [ -z "$YAD_PKG" ]; then
-        for _cand in "$(yad_pin_read .sdlc/hub.json gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
+        for _cand in "$(yad_pin_read "$YAD_PIN_FILE" gate_sync_version)" "$(yad_pin_read .sdlc/cli-version.json version)"; do
           [ -n "$_cand" ] || continue
           if yad_pin_valid "$_cand"; then YAD_PKG="$_cand"; break; fi
           echo "yad-gate-sync: ignoring pin '${_cand}' — not an exact ${YAD_MAJOR}.x release." >&2

package/skills/yad-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-report
-description: 'Self issue reporter for the yad CLI. When a yadflow flow breaks, file a well-formed bug in the upstream yadflow repo (abdelrahmannasr/yadflow) with auto-scrubbed diagnostics attached, so recurring issues surface to the maintainers. Drives the `yad report` command: it captures ONLY a privacy-safe allowlist (yadflow/node/os version, tool present+authenticated booleans, Product platform enum, the YadError code/hint, a path-scrubbed error message, and the failing command + flag NAMES) — never absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch names, or flag values. It searches open issues first to avoid duplicates, shows the exact payload, and asks before posting anything to the public repo. Files directly via an authenticated gh (the upstream repo is on GitHub), or falls back to a prefilled issues/new URL. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 or SDLC_NONINTERACTIVE disables it). Use when the user says "yad report", "report this bug", "file an issue", or "something broke in the flow".'
+description: 'Self issue reporter for the yad CLI. When a yadflow flow breaks, file a well-formed bug in the upstream yadflow repo (abdelrahmannasr/yadflow) with auto-scrubbed diagnostics attached. Drives the `yad report` command: it captures ONLY a privacy-safe allowlist (yadflow/node/os version, tool present+authenticated booleans, Product platform enum, the YadError code/hint, a path-scrubbed error message, and the failing command + flag NAMES) — never absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch names, or flag values. It searches open issues first to avoid duplicates, shows the exact payload, and asks before posting anything to the public repo. Files directly via an authenticated gh, or falls back to a prefilled issues/new URL. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 or SDLC_NONINTERACTIVE disables it). Use when the user says "yad report", "report this bug", "file an issue", or "something broke in the flow".'
 ---
 
 # yad — Self Issue Reporter

package/skills/yad-review-companion/SKILL.md

@@ -32,7 +32,7 @@ The CLI never calls an LLM — **you** (this skill) generate the text and post i
    questions and flagged concerns become the review record. If you **cannot** answer from the material,
    say so — that gap is itself a finding (post it as a genuine, blocking comment).
 4. **🏆 Social (E)** — a verified-engagement mark on a real companion review, a friendly public
-   @-mention nudge on a bare approve, and light read-only gamification surfaced by `yad status`.
+   @-mention nudge on a bare approve, and light read-only gamification surfaced by the `yad-status` skill.
 
 ## Markers (the contract with the gate — all live in PLATFORM data, never a ledger file)
 
@@ -54,7 +54,7 @@ Inputs: `epic` + `artifact` (Shape) **or** `repo` + `pr` (Build); and the `actio
    `requireEngagement`, and `step.gateRule` — the step's full approver count (`base`, `riskStep`,
    `needed`, `risk`) — with `step.cap`, an object `{ active, limit, to, capped }` (E72): `to` is the count
    capped by the active people, `capped` is true when the cap lowered it, and the field is `null` when
-   the people could not be counted, which is worth naming in the trailer on a high-risk step and never a blocker. Build: `yad review chat --repo <r>` (see `yad-engineer-review`) provides the
+   the people could not be counted, which is worth naming in the trailer on a high-risk step and never a blocker. Build: `yad review context --repo <r> --pr <n>` (see `yad-engineer-review`) provides the
    diff + code-map grounding. Read the named files yourself — never invent content.
 2. **Trailer.** Generate ≤6 lines (what / risk / read-time), grounded only in the bundle. Post it:
    `yad gate trailer <epic> <artifact> --body "<text>" [--pr <n>]` (idempotent; re-run after edits).
@@ -81,7 +81,7 @@ Inputs: `epic` + `artifact` (Shape) **or** `repo` + `pr` (Build); and the `actio
 - **Companion comments never block; genuine concerns always do.** Flag the former with `yad:noblock`;
   leave the latter unflagged.
 - **The engagement signal is gameable and you say so.** It makes review quality visible; it is not
-  proof. The strict-mode switch is `hub.review.requireEngagement` (off by default).
+  proof. The strict-mode switch is `review.requireEngagement` (Product settings) (off by default).
 - **The companion never approves on a human's behalf and never merges.** It assists; the human acts.
 
 ## local mode (no platform)