yadflow 2.14.0 → 2.16.0

package/cli/platform.mjs

@@ -141,10 +141,21 @@ export function resolveLogin(login, roster = [], repos = [], touchedDomains = []
 
 // Normalized PR reviews -> approval records (only APPROVED states count). `submittedAt` rides along
 // so the gate can tell a fresh re-approval from a stale one (revoke-on-change).
-export function mapApprovers(reviews = [], { roster, repos, touchedDomains }) {
+export function mapApprovers(reviews = [], { roster, repos, touchedDomains, headOid } = {}) {
   const out = [];
   for (const r of reviews) {
     if (r.state !== 'APPROVED') continue;
+    // Revoke-on-change, enforced in code where the platform binds an approval to a commit. The reader
+    // sets `commit` to the review's SHA (GitHub), to `null` when that read DEGRADED, or leaves it
+    // ABSENT when the platform exposes no per-approval SHA (GitLab):
+    //   - `null` (degraded read)  → FAIL CLOSED → drop, independently of headOid: we cannot prove the
+    //                               approval is for the merged content, so a transient failure holds
+    //                               the gate rather than advancing on unverifiable approvals;
+    //   - a known SHA ≠ head      → the approval is stale (artifact moved) → drop;
+    //   - absent (GitLab)         → keep: revoke-on-change is the platform's "remove approvals on new
+    //                               commits" setting.
+    if (r.commit === null) continue;
+    if (headOid && r.commit !== undefined && r.commit !== headOid) continue;
     for (const rec of resolveLogin(r.login, roster, repos, touchedDomains)) {
       out.push({ ...rec, submittedAt: r.submittedAt || null });
     }
@@ -157,17 +168,35 @@ function readPrGitHub(n, { cwd } = {}) {
   const view = run('gh', ['pr', 'view', String(n), '--json', 'state,mergedAt,headRefOid'], { cwd });
   if (!view.ok) return { ok: false, reason: view.stderr || 'gh pr view failed' };
   const meta = JSON.parse(view.stdout);
-  // latestReviews collapses a reviewer's superseded reviews to their current one.
-  const rev = run('gh', ['pr', 'view', String(n), '--json', 'latestReviews'], { cwd });
-  const reviews = rev.ok
-    ? (JSON.parse(rev.stdout).latestReviews || []).map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt }))
-    : [];
+  let reviews = [];
+  let reviewsOk = false;
   // Review-thread resolution via GraphQL (REST does not expose isResolved). Paginate so a PR with
   // >100 threads is not mistakenly read as "all resolved".
   let threads = [];
   const nwo = run('gh', ['repo', 'view', '--json', 'owner,name'], { cwd });
   if (nwo.ok) {
     const { owner, name } = JSON.parse(nwo.stdout);
+    // latestReviews collapses a reviewer's superseded reviews to their current one; commit.oid binds
+    // each approval to the revision it was made on, so an approval on an older commit than the merged
+    // head is dropped as stale (revoke-on-change in code — see mapApprovers). `gh pr view --json
+    // latestReviews` does not expose the commit, so read it via GraphQL. Paginate so a PR with >100
+    // reviewers never silently omits one; any page failure aborts to the commitless fallback below,
+    // which fails closed rather than advancing on a partial read.
+    const rq = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){latestReviews(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{author{login} state submittedAt commit{oid}}}}}}`;
+    let rcursor = null;
+    reviewsOk = true;
+    for (let guard = 0; guard < 50; guard++) {
+      const args = ['api', 'graphql', '-f', `query=${rq}`, '-F', `o=${owner.login}`, '-F', `r=${name}`, '-F', `n=${n}`];
+      if (rcursor) args.push('-F', `c=${rcursor}`);
+      const rg = run('gh', args, { cwd });
+      if (!rg.ok) { reviewsOk = false; reviews = []; break; }
+      const conn = JSON.parse(rg.stdout)?.data?.repository?.pullRequest?.latestReviews;
+      for (const x of conn?.nodes || []) {
+        reviews.push({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, commit: x.commit?.oid || null });
+      }
+      if (!conn?.pageInfo?.hasNextPage) break;
+      rcursor = conn.pageInfo.endCursor;
+    }
     const q = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){reviewThreads(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{isResolved comments(first:1){nodes{author{login} body}}}}}}}`;
     let cursor = null;
     for (let guard = 0; guard < 50; guard++) {
@@ -188,6 +217,15 @@ function readPrGitHub(n, { cwd } = {}) {
       cursor = page.pageInfo.endCursor;
     }
   }
+  // Fallback if the GraphQL reviews read failed (no nwo / API hiccup): take the plain JSON view with
+  // commit=null. Approvals then FAIL CLOSED in mapApprovers (a degraded read cannot prove an approval
+  // is for the merged content), while CHANGES_REQUESTED is still honored — so a transient failure
+  // holds the gate, never advances it.
+  if (!reviewsOk) {
+    const rev = run('gh', ['pr', 'view', String(n), '--json', 'latestReviews'], { cwd });
+    if (rev.ok) reviews = (JSON.parse(rev.stdout).latestReviews || [])
+      .map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, commit: null }));
+  }
   return {
     ok: true,
     state: meta.state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 30 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-checks/SKILL.md

@@ -38,6 +38,13 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 - Canonical gate sources live in this skill's `templates/` (the source of truth that gets installed
   into each code repo):
   - `templates/checks/{spec-link,contract-check,build-test-lint,verified-commits}.sh`
+  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** (a no-op
+    when humans legitimately own the ledger). On review PRs it FAILs any commit that touches the
+    CI-owned gate ledger (`.sdlc/{state,approvals,comments,hub-prs}.json`, `reviews/*.md`) unless it
+    is a **verified gate-bot commit** — bot-authored AND platform-Verified, since author text alone is
+    spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. Runs in `yad-hub-checks`
+    alongside `verified-commits` (which waives the allowlist for the bot but still requires its
+    signature). See `yad-hub-bridge`.
   - `templates/github/yad-verified-commits.yml` + `templates/gitlab/yad-verified-commits.gitlab-ci.yml`
     → the standalone hub-side verified-commits CI (installed by `yad check --fix` with the hub wiring)
   - `templates/github/yad-checks.yml` → installs to `.github/workflows/yad-checks.yml` (marked `# yad-managed: yad-checks`)

package/skills/yad-checks/references/check-gates.md

@@ -121,8 +121,17 @@ from the event payload):
 - `--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).
-- `--profile hub` → a front-half artifact-review title `review: <artifact> (EP-<slug>)`, the shape
-  `yad gate open` creates.
+- `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
+  - `review/EP-*` head (or no `--head` — stays strict) → a front-half artifact-review title
+    `review: <artifact> (EP-<slug>)`, the shape `yad gate open` creates.
+  - any other head → a tooling/code change to the hub itself, so it follows the `code` convention (a
+    Conventional-Commits subject). This is what lets a PR that changes the hub's own workflows/checks
+    pass — it has no EP artifact to review.
+  - **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
+    changes front-half artifacts (any path under `epics/**`) **FAILS** — those changes must go through
+    a `review/EP-*` PR and the artifact-review workflow. CI passes the PR's changed paths via
+    `--changed <file>` (computed from the diff against the base ref); without that list (a direct
+    by-hand caller) the guard is inert and the branch split alone applies.
 
 ## 7. pr-template (`templates/checks/pr-template.sh`)
 
@@ -131,8 +140,14 @@ catches a free-form description that bypassed it:
 
 - `--profile code` (default) → requires `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled
   `Risk level:` (`low|medium|high`).
-- `--profile hub` → requires `## Artifact under review`, `## Impact & Risk (front-half)`, `## Checklist`,
-  and a `Risk tags:` line.
+- `--profile hub` → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
+  - `review/EP-*` head (or no `--head`) → requires the artifact-review template: `## Artifact under
+    review`, `## Impact & Risk (front-half)`, `## Checklist`, and a `Risk tags:` line.
+  - any other head → a hub tooling PR, so it requires the `code` task template (`## Summary`,
+    `## Impact & Risk`, `## Checklist`, filled `Risk level:`).
+  - **Anti-bypass guard** (same as pr-title): a non-review head that changes front-half artifacts
+    (`epics/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
+    must go through a `review/EP-*` PR.
 
 ## CI wiring (both platforms)
 
@@ -202,9 +217,12 @@ its one include line) whenever `.sdlc/hub.json` has a platform with the bridge e
 front-half review PRs are held to the same rule as code-repo PRs: signed, known authors only.
 
 The hub **also** runs the three pattern gates (`commit-message`, `pr-title`, `pr-template`) with
-`--profile hub`, so the front-half review PRs follow the hub conventions — Conventional-Commits commit
-subjects, a `review: <artifact> (EP-<slug>)` title, and a body that uses the hub artifact-review
-template. `yad check --fix` installs the same `checks/*.sh` scripts plus a standalone hub workflow
+`--profile hub`. The pattern gates split by the PR/MR **head branch** (passed via `--head`): a
+`review/EP-*` head is a front-half review PR — Conventional-Commits commit subjects, a
+`review: <artifact> (EP-<slug>)` title, and the hub artifact-review template body; **any other head is
+a tooling/code change to the hub itself** and follows the `code` convention (a Conventional-Commits
+title + the code task template), so a PR that changes the hub's own workflows/checks can pass.
+`yad check --fix` installs the same `checks/*.sh` scripts plus a standalone hub workflow
 (`templates/github/yad-hub-checks.yml` → `.github/workflows/yad-hub-checks.yml`, or the GitLab fragment
 `templates/gitlab/yad-hub-checks.gitlab-ci.yml` → `.gitlab/ci/yad-hub-checks.yml` + its one include
 line). Code repos run the same three with `--profile code` inside the main `yad-checks` workflow.

package/skills/yad-checks/templates/checks/ledger-guard.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# ledger-guard gate.
+# In BRIDGE mode the gate ledger is CI-owned: only the yad gate-sync bot may change the
+# machine-written gate-state files. A commit on a review PR by anyone else that modifies them is
+# rejected — the human keeps the artifact, CI keeps the ledger. This makes "CI is the sole writer of
+# the ledger" a mechanical guarantee instead of a convention.
+#
+# Protected (gate-state, machine-written):
+#   epics/*/.sdlc/state.json, approvals.json, comments.json, hub-prs.json
+#   epics/*/reviews/*.md
+# NOT protected:
+#   epics/*/.sdlc/contract-lock.json — artifact-side: the architect locks the contract surface in
+#   `gate open`, so a human legitimately commits it alongside the architecture artifact.
+#
+# A "bot commit" must be BOTH authored by the gate bot (name/email contains yad-gate-sync) AND
+# platform-VERIFIED — author/committer text alone is user-controlled and spoofable, so the platform
+# Verified signature (a key the contributor cannot forge under the bot identity) is what actually
+# distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
+# human edit and rejected.
+#
+# Scope: enforced ONLY when the bridge is enabled (a platform + gate-sync CI). Without the bridge
+# (file-only / non-bridge) humans legitimately write the ledger locally, so the gate is a no-op.
+#
+# Degradation: a base ref that cannot be resolved FAILs closed; no platform (cannot read the Verified
+# badge) WARNs and waives the signature half — the same stance verified-commits takes.
+set -euo pipefail
+
+# ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
+HUB="${SDLC_HUB_CONFIG:-.sdlc/hub.json}"
+if [ ! -f "$HUB" ] || ! grep -Eq '"(bridge_enabled|bridge)"[[:space:]]*:[[:space:]]*true' "$HUB"; then
+  echo "PASS [ledger-guard]: bridge not enabled — the ledger is locally owned, nothing to guard."
+  exit 0
+fi
+
+BASE="${1:-${SDLC_BASE:-origin/main}}"
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [ledger-guard]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+RANGE="${BASE}..HEAD"
+
+commits="$(git rev-list "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [ledger-guard]: no commits in ${RANGE}"
+  exit 0
+fi
+
+# ---- platform for the signature check (mirrors verified-commits) ------------------------------
+remote="$(git remote get-url origin 2>/dev/null || true)"
+platform=""
+case "$remote" in
+  *github*) platform=github ;;
+  *gitlab*) platform=gitlab ;;
+esac
+platform="${SDLC_PLATFORM:-$platform}"
+case "$platform" in
+  github|gitlab) ;;
+  ""|none) platform=""; echo "WARN [ledger-guard]: no GitHub/GitLab remote — bot signature NOT verified (the Verified badge is a platform concept)." ;;
+  *) echo "FAIL [ledger-guard]: unknown platform '${platform}' (SDLC_PLATFORM must be github|gitlab|none)."; exit 1 ;;
+esac
+
+# 0 when the platform marks the commit's signature verified.
+signature_verified() {
+  local sha v body
+  sha="$1"
+  case "$platform" in
+    github)
+      v="$(gh api "repos/{owner}/{repo}/commits/${sha}" --jq '.commit.verification.verified' 2>/dev/null || echo api-error)"
+      [ "$v" = "true" ]
+      ;;
+    gitlab)
+      if [ -n "${CI_API_V4_URL:-}" ] && [ -n "${CI_PROJECT_ID:-}" ]; then
+        body="$(curl -fsS --header "PRIVATE-TOKEN: ${GITLAB_TOKEN:-${SDLC_API_TOKEN:-}}" \
+          "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/repository/commits/${sha}/signature" 2>/dev/null || true)"
+      else
+        body="$(glab api "projects/:id/repository/commits/${sha}/signature" 2>/dev/null || true)"
+      fi
+      printf '%s' "$body" | grep -qE '"verification_status"[[:space:]]*:[[:space:]]*"verified"'
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+# A trusted bot commit = bot-attributed AND (platform-Verified, or no platform to check against).
+trusted_bot() {
+  case "$(git show -s --format='%an|%ae' "$1")" in
+    *yad-gate-sync*) ;;
+    *) return 1 ;;
+  esac
+  [ -z "$platform" ] && return 0          # degraded: cannot read the Verified badge — waive (warned above)
+  signature_verified "$1"
+}
+
+violations=0
+for sha in $commits; do
+  touches_ledger=0
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in
+      epics/*/.sdlc/contract-lock.json) ;; # artifact-side — allowed
+      epics/*/.sdlc/state.json|epics/*/.sdlc/approvals.json|epics/*/.sdlc/comments.json|epics/*/.sdlc/hub-prs.json|epics/*/reviews/*.md)
+        touches_ledger=1
+        echo "  ${sha} (author $(git show -s --format='%an' "$sha")) → $f"
+        ;;
+    esac
+  done < <(git diff-tree --no-commit-id --name-only -r "$sha")
+  if [ "$touches_ledger" = 1 ] && ! trusted_bot "$sha"; then
+    violations=$((violations + 1))
+  fi
+done
+
+if [ "$violations" -gt 0 ]; then
+  echo "FAIL [ledger-guard]: ${violations} commit(s) change CI-owned gate files without a verified gate-bot signature. The ledger is CI-owned — let CI sync the gate; do not commit .sdlc/*.json or reviews/*.md yourself."
+  exit 1
+fi
+echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit."
+exit 0

package/skills/yad-checks/templates/checks/verified-commits.sh

@@ -93,8 +93,14 @@ while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
   author="$(git log -1 --format=%ae "$sha" | tr '[:upper:]' '[:lower:]')"
+  # The gate-sync bot is a machine identity, not a roster human — waive the allowlist for it. Its
+  # commits are still held to the SIGNATURE check below, so a contributor cannot spoof the bot author
+  # to dodge the allowlist (a forged-author commit is not platform-Verified). Mirrors how the
+  # platform-committer merge commits are allowlist-exempt but signature-covered.
+  is_bot=0
+  case "${author}|$(git log -1 --format=%an "$sha" | tr '[:upper:]' '[:lower:]')" in *yad-gate-sync*) is_bot=1 ;; esac
 
-  if [ "$authors_on" = 1 ]; then
+  if [ "$authors_on" = 1 ] && [ "$is_bot" = 0 ]; then
     # tolerate CRLF / stray surrounding whitespace in a hand-edited allowlist
     if grep -vE '^[[:space:]]*(#|$)' "$ALLOWLIST" | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
         | tr '[:upper:]' '[:lower:]' | grep -qxF "$author"; then
@@ -103,6 +109,8 @@ while IFS= read -r sha; do
       echo "FAIL [verified-commits]: ${short} author <${author}> is not in ${ALLOWLIST} — unverified user."
       rc=1
     fi
+  elif [ "$is_bot" = 1 ]; then
+    echo "PASS [verified-commits]: ${short} gate-sync bot — allowlist waived (signature still required)"
   fi
 
   if [ -n "$platform" ]; then

package/skills/yad-checks/templates/github/yad-hub-checks.yml

@@ -1,8 +1,11 @@
 # yad-managed: yad-checks
-# Pattern gates for the PRODUCT HUB: every PR (including the front-half review/EP-* PRs) must follow
-# the hub conventions — Conventional-Commits commit subjects, a `review: <artifact> (EP-<slug>)` PR
-# title, and a PR body that uses the hub artifact-review template. They run with `--profile hub`.
-# Standalone workflow so it never collides with the code-repo yad-checks workflow.
+# Pattern gates for the PRODUCT HUB. They run with `--profile hub` and split by head branch:
+#   review/EP-* PRs are front-half artifact-review vehicles — a `review: <artifact> (EP-<slug>)` title
+#     and the hub artifact-review template body.
+#   every other PR is a tooling/code change to the hub itself — a Conventional-Commits title and the
+#     code task template body (same convention the code repos use).
+# The head ref is passed via --head so the gate can tell the two apart. Commit subjects are always
+# Conventional-Commits. Standalone workflow so it never collides with the code-repo yad-checks workflow.
 name: yad-hub-checks
 on:
   pull_request:
@@ -17,20 +20,39 @@ jobs:
       - run: bash checks/commit-message.sh --profile hub "origin/${{ github.base_ref }}"
 
   # Pass the title via env (never interpolate untrusted ${{ }} into a run line — injection-safe).
+  # fetch-depth: 0 + the base ref give us the PR's changed paths, so the gate can reject an artifact
+  # change (epics/**) riding a non-review head past the front-half review with a plain code title.
   pr-title:
     runs-on: ubuntu-latest
     env:
       PR_TITLE: ${{ github.event.pull_request.title }}
+      PR_HEAD: ${{ github.event.pull_request.head.ref }}
+      BASE_REF: ${{ github.base_ref }}
     steps:
       - uses: actions/checkout@v4
-      - run: bash checks/pr-title.sh --profile hub "$PR_TITLE"
+        with: { fetch-depth: 0 }
+      - run: |
+          changed="$(mktemp)"; git diff --name-only "origin/${BASE_REF}...HEAD" > "$changed"
+          bash checks/pr-title.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$PR_TITLE"
 
   pr-template:
     runs-on: ubuntu-latest
     env:
       PR_BODY: ${{ github.event.pull_request.body }}
+      PR_HEAD: ${{ github.event.pull_request.head.ref }}
+      BASE_REF: ${{ github.base_ref }}
     steps:
       - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
       - run: |
+          changed="$(mktemp)"; git diff --name-only "origin/${BASE_REF}...HEAD" > "$changed"
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
-          bash checks/pr-template.sh --profile hub "$body"
+          bash checks/pr-template.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$body"
+
+  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
+  ledger-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/ledger-guard.sh "origin/${{ github.base_ref }}"

package/skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml

@@ -3,9 +3,11 @@
 # .gitlab-ci.yml via:
 #   include:
 #     - local: '.gitlab/ci/yad-hub-checks.yml'
-# Every MR (including the front-half review/EP-* MRs) must follow the hub conventions — a
-# Conventional-Commits commit subject, a `review: <artifact> (EP-<slug>)` MR title, and an MR body
-# that uses the hub artifact-review template. They run with `--profile hub`.
+# MRs run with `--profile hub` and split by source branch: review/EP-* MRs are front-half artifact-
+# review vehicles (a `review: <artifact> (EP-<slug>)` title + the hub artifact-review template body);
+# every other MR is a tooling/code change to the hub itself and follows the code convention (a
+# Conventional-Commits title + the code task template body). The source branch is passed via --head so
+# the gate can tell the two apart. Commit subjects are always Conventional-Commits.
 # Job names are yad-hub-prefixed so they coexist with any code-repo fragment in one pipeline; jobs use
 # `needs: []` and no `stage:` so a foreign `stages:` list can neither break nor reorder them.
 default:
@@ -25,15 +27,26 @@ yad-hub-commit-message:
   script:
     - bash checks/commit-message.sh --profile hub "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
 
+# GIT_DEPTH: 0 (above) gives the changed paths, so the gate can reject an artifact change (epics/**)
+# riding a non-review source branch past the front-half review with a plain code title/template.
 yad-hub-pr-title:
   extends: .yad_hub_mr_only
   needs: []
   script:
-    - bash checks/pr-title.sh --profile hub "$CI_MERGE_REQUEST_TITLE"
+    - changed="$(mktemp)"; git diff --name-only "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > "$changed"
+    - bash checks/pr-title.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$CI_MERGE_REQUEST_TITLE"
 
 yad-hub-pr-template:
   extends: .yad_hub_mr_only
   needs: []
   script:
+    - changed="$(mktemp)"; git diff --name-only "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > "$changed"
     - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
-    - bash checks/pr-template.sh --profile hub "$body"
+    - bash checks/pr-template.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
+
+# The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
+yad-hub-ledger-guard:
+  extends: .yad_hub_mr_only
+  needs: []
+  script:
+    - bash checks/ledger-guard.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"

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

@@ -1,6 +1,6 @@
 ---
 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 event-driven sync on the hub: a CI workflow that runs `yad gate ci` whenever a reviewer approves / requests changes / a human merges, committing the ledger to the default 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 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.'
 ---
 
 # SDLC — Hub Review Bridge (the templated PR/MR bridge)
@@ -57,24 +57,40 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
    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.
-4. Upsert a record into `epics/<epic>/.sdlc/hub-prs.json`:
+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
+   branch:
    ```json
    { "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
+   `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
+   PR only and writes no ledger.)
 5. Report the PR/MR URL and the required reviewers. **Do not** record approvals or advance — reviewers
-   act on the platform; `yad-review-gate action: sync` pulls it back.
+   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` (event-driven sync on the hub)
-Install the hub CI that turns platform actions — a review **approval**, a **change request**, a review
-dismissal, or the human **merge** — into an automatic `yad gate ci` run that syncs the ledger and
-commits it to the hub's default branch. No more waiting on a manual `yad gate sync`; the manual command
-remains valid and is the fallback whenever CI cannot push.
+### 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
+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
+commits). Also install the `ledger-guard` check (yad-checks) so humans cannot commit gate-state files.
+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
+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**
+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.)
 
 1. Run `yad check --fix` (the wiring is manifest-driven, like `yad-checks`): with a platform +
    enabled bridge in `.sdlc/hub.json` it installs
@@ -87,8 +103,9 @@ remains valid and is the fallback whenever CI cannot push.
      `templates/gitlab/gitlab-ci.include-root.yml` as the root when none exists;
    - create the 15-minute pipeline **schedule** (variable `SDLC_GATE_SYNC=true`) and the masked
      `SDLC_GATE_TOKEN` project-access-token variable (`read_api` + `write_repository`). GitLab fires no
-     pipeline on an approval alone, so the schedule is the path that picks approvals up (≤ ~15 min
-     latency); MR events and the merge are near-immediate.
+     pipeline on an approval alone, and a squash merge can drop the branch name, so the schedule is the
+     catch-up path that advances merged reviews it discovers via the API (≤ ~15 min latency); a merge
+     push whose commit names the review branch advances near-immediately.
    - **If your runners are tag-locked** (`run_untagged: false`, common on self-hosted): set a
      `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) so the docker-image `yad-gate-sync` job
      is routed to a runner — otherwise it sits `pending` forever. The fragment emits
@@ -98,8 +115,12 @@ remains valid and is the fallback whenever CI cannot push.
      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
-   PR and pushes the ledger. If the default branch is protected, see the workflow header for the
-   bypass / PAT options; until then the run fails visibly and manual `yad gate sync` still works.
+   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
+   the run fails visibly — recover by granting the push path, then re-run the workflow or run
+   `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the default branch (advisory
+   `yad gate sync` cannot recover a bridge gate).
 
 ## Hard rules
 
@@ -111,12 +132,18 @@ remains valid and is the fallback whenever CI cannot push.
   act) — `yad gate sync` 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 — and commits the **ledger files only** to the default branch; the artifact lands
-  on the default branch exclusively via the human merge. Front gates stay permanently human.
+  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
+  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
+  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").
 - **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs file-only with no error.
 
 ## Reference