yadflow 2.14.0 → 2.15.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.15.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/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

@@ -34,3 +34,11 @@ jobs:
       - run: |
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
           bash checks/pr-template.sh --profile hub "$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

@@ -37,3 +37,10 @@ yad-hub-pr-template:
   script:
     - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
     - bash checks/pr-template.sh --profile hub "$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

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

@@ -73,64 +73,106 @@ comments, replies, the reviewer **resolves** their thread, then `sync` runs agai
 - **Merge → advance.** When the reviewer rule is satisfied, every thread is resolved, **and the review
   PR/MR is merged**, `sync` marks the step `done` and unblocks the next step. The merge is the human
   approval act — there is no separate machine advance. (`yad gate sync` performs this deterministically.)
-- **Revoke on artifact change.** Each bridge approval is stamped with the content hash it was given
-  against (the file bytes; the locked contract surface for architecture). On re-sync, an approval whose
-  stamped hash ≠ the current hash is **dropped** — the reviewer must re-approve the changed artifact. A
-  genuinely newer review (later `submittedAt`) re-stamps against the new hash. This is "revoke only when
-  the artifact changed", not "revoke on any PR commit".
-
-## Event-driven sync (hub CI)
-
-The `wire` action (SKILL.md Step 4) installs a CI workflow on the hub so the platform events drive
-`yad gate ci` instead of waiting on a manual `yad gate sync`. The CLI entry is self-sufficient: it
-derives the epic + artifact from the `review/EP-<slug>/<artifact-base>` head branch and takes the PR/MR
-number from the event payload — it even upserts the `hub-prs.json` entry when the author never committed
-it, so the first CI commit converges the views. `yad gate ci` with no `--branch` sweeps every open
-review PR (the scheduled path).
-
-| Platform event | CI action |
-|---|---|
-| review submitted (approve / changes requested) or dismissed | `gate ci --branch <head> --pr <n>` → sync the ledger; the predicate may hold or pass |
-| PR/MR `synchronize` (new commits on the review branch) | same — promptly re-stamps/revokes approvals on artifact change |
-| PR/MR closed **and merged** (the human act) | same — predicate sees `merged: true` and advances the step |
-| GitLab schedule (`*/15 * * * *`, `SDLC_GATE_SYNC=true`) | `gate ci` sweep — the **only** GitLab path that sees a bare approval (≤ ~15 min latency) |
-
-**The overlay.** Pre-merge, the artifact under review exists only on the review branch, while the
-ledger lives on the default branch. `gate ci` checks out the default branch, fetches the head ref and
-overlays just the artifact paths (for architecture: `architecture.md` + `contract.md` +
-`.sdlc/contract-lock.json`; for stories: `stories/`) so `artifactHash` binds each approval to **what the
-reviewers actually approved** — then drops the overlay before committing. Only
-`epics/<epic>/.sdlc/*.json` + `reviews/*.md` are committed (message `chore(gate): … [skip ci]`); the
-artifact reaches the default branch exclusively via the human merge.
-
-**Loop prevention & races.** The GitHub triggers (`pull_request_review`, `pull_request`) cannot fire on
-a push to the default branch, `[skip ci]` guards every other workflow on both platforms, and a
-repo-wide concurrency group serializes runs; the ledger push retries with a rebase (ledger-only commits
-across epics touch disjoint files).
+- **Revoke on artifact change (checked at merge).** Path B reconciles at merge, so an approval given
+  to an earlier revision must not count for the merged content. How that is enforced differs by
+  platform:
+  - **GitHub — in code.** Each approval carries the **commit SHA it was made on**; `mapApprovers`
+    drops any approval whose commit ≠ the merged head (`headOid`). The reviewer approved an older
+    revision → their review is stale → dropped. No platform setting required.
+  - **GitLab — platform setting.** GitLab approvals expose no per-approval commit SHA (the reader omits
+    it), so the in-code SHA check does not apply and the approval is kept. Revoke-on-change there is the
+    platform's **"remove all approvals when commits are added to the source branch"** setting — **enable
+    it** (required for the guarantee on GitLab; safe under Path B because CI never pushes the source
+    branch, so only the owner's own artifact pushes drop approvals).
+  - **Degraded GitHub read — fail closed.** If the GitHub commit read fails (the reader returns a
+    `null` commit), the approval is **dropped**: a transient failure holds the gate rather than
+    advancing on approvals whose freshness cannot be proven (re-run `yad gate sync` to recover).
+    CHANGES_REQUESTED is still honored, so a degraded read can only ever *hold* the gate.
+  The `artifactHash` stamp still binds architecture approvals to the locked contract surface (see
+  "Contract re-lock" above).
+- **Known limitation — protect the hub default branch.** The advance hashes the artifact from the
+  default branch as it stands when CI runs, while approvals are SHA-bound to the reviewed PR/MR head.
+  Those can differ if the artifact changes on the **base** outside this review while the PR/MR is open
+  (the merge then integrates a change the reviewers never saw) or if a later out-of-band commit edits
+  the merged artifact before a delayed reconcile advances it. In both cases each approval's commit
+  still equals the reviewed head, so the SHA check passes, yet the live content was not reviewed. Close
+  it operationally: **require branch protection on the hub default branch so `epics/**` artifacts can
+  only change through their own review PR/MR** (one open review per artifact) — then the base copy of an
+  artifact cannot move while its review is open, so the merged/live content always equals the reviewed
+  content. (The complete in-code fix would hash the artifact at the reviewed PR-head revision before
+  advancing; deferred in favor of the branch-protection mitigation.)
+
+## Event-driven sync (hub CI) — Path B
+
+The `wire` action (SKILL.md Step 4) installs CI on the hub so a **merge** drives `yad gate ci` —
+**CI is the SOLE writer of the ledger, and it writes only at merge, only to the default branch.**
+During review CI writes nothing: the platform PR/MR is the source of truth (native approvals +
+threads). The CLI is self-sufficient at merge: it derives the epic + artifact from the
+`review/EP-<slug>/<artifact-base>` head branch, takes the PR/MR number from the event (GitHub) or
+resolves it from the platform (GitLab), upserts the `hub-prs.json` entry itself, and **re-reads
+approvals fresh from the platform** — so no ledger needs to be pre-seeded on the branch.
+
+| Platform event | Phase | CI action |
+|---|---|---|
+| PR/MR opened / reopened / pushed / reviewed | pre-merge | **none** — review state lives on the platform; CI never touches the branch |
+| PR/MR closed **and merged** (the human act) | merge | `gate ci --branch <head> --pr <n> --merged` → re-read approvals, advance the step + flip the artifact `status:` **on the default branch** |
+| Schedule (`*/15`) | reconcile | Safety net: enumerate recently-**merged** `review/EP-*` PRs/MRs via the API and advance any not yet `done` (idempotent). Recovers a merge whose merge-time run failed transiently, and on GitLab also picks up a squash merge whose commit dropped the branch name (and a bare approval — GitLab fires no pipeline on one). **GitHub:** a scheduled workflow, automatic once committed. **GitLab:** a pipeline schedule with `SDLC_GATE_SYNC=true` (one-time setup) |
+
+**Why no pre-merge write fixes the gate.** Keeping CI off the PR head means an in-flight approval is
+never dismissed by a CI commit, and the PR's required checks never strand on a `[skip ci]` CI commit.
+Correctness is unaffected: at merge CI re-reads the PR/MR approvals from the platform and re-checks
+each `artifactHash` against the merged content, so revoke-on-change still holds. The only ledger
+commit — the advance plus the `draft → approved` status flip — lands on the **default branch** with
+`[skip ci]`.
+
+**The ledger is CI-owned (bridge mode only).** Humans never commit gate-state files: the `ledger-guard`
+check (yad-checks) FAILs any commit on a review PR that touches `.sdlc/{state,approvals,comments,hub-prs}
+.json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). Under Path B **no
+CI commit lands in a review PR at all**, so the only ledger change the guard can see there is a human
+edit — which it rejects. (The `verified-commits` gate still vets every commit's signature + author;
+its gate-bot exemption is now vestigial in-PR because CI no longer commits there.) `yad gate open`
+opens the PR only; local `yad gate sync` is advisory in bridge mode (writes nothing). After a merge,
+everyone `git checkout <default> && git pull`. (Without the bridge, humans own the ledger locally and
+these guards are no-ops.)
+
+**Loop prevention & races.** The only ledger commit lands on the **default branch** at merge, which
+fires no PR trigger; it carries `[skip ci]` to guard sibling workflows. Because CI never pushes the
+review branch, there is no `synchronize` / MR-pipeline loop to prevent — and it is now **safe to enable**
+the platform's **"dismiss stale approvals on push"** (GitHub) / **"remove all approvals when commits
+are added to the source branch"** (GitLab): only the owner's own artifact pushes dismiss approvals,
+which is exactly the intended revoke-on-change. Merge advances serialize on the default branch; 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.
 - 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.
-- Protected default branch (GitHub): prefer a ruleset bypass for Actions; else a fine-grained PAT as
-  `SDLC_GATE_TOKEN` passed to `actions/checkout`; else leave it — the run fails **visibly** and manual
-  `yad gate sync` remains the fallback. Never wire branch protection that couples the merge itself to
-  the gate.
-
-**Manual sync stays first-class.** `yad gate sync <epic> [artifact]` is unchanged and always valid —
-the CI is the same sync on a trigger, and the file ledger is still the source of truth.
+  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.
+
+**Manual sync & recovery.** In bridge mode `yad gate sync` is **advisory** (read-only) — it prints the
+predicate but writes nothing, so it is **not** a recovery path when CI fails. If a merge-time run fails
+(can't push, API hiccup), recovery is the scheduled **reconcile** job (automatic; it re-advances merged
+reviews not yet `done`). To force it immediately, a maintainer runs the same command CI runs, locally on
+the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged` (this writes + pushes,
+unlike advisory `yad gate sync`). File-only mode (no platform) keeps `yad gate sync` as the local writer.
+The file ledger is still the source of truth.
 
 ### Manual end-to-end verification (GitHub)
 
 1. On a scratch hub: `yad setup` (platform github, roster with a second account) → `yad check --fix`
    installs `.github/workflows/yad-gate-sync.yml`; commit + push it.
-2. Author an epic → `yad gate open EP-x epic.md` → the review PR opens.
-3. Second account **approves** → the Actions run commits `approvals.json` to the default branch.
-4. Second account **requests changes** → the run records the blocking comment; `yad gate status EP-x`
-   (after `git pull`) shows the gate held.
-5. Resolve the thread, approve again, a human **merges** → the closed-event run advances `state.json`
-   (`epic-review: done`, `currentStep: architecture`).
-6. `git pull` locally — `yad gate status EP-x` matches the platform history.
-
-GitLab variant: same flow on an MR; a bare approval appears after the next schedule tick.
+2. Author an epic → `yad gate open EP-x epic.md` → the review PR opens. CI writes nothing yet — review
+   state lives on the platform.
+3. Second account **approves** / **requests changes** → no CI run touches the branch; the PR's native
+   approvals + threads are the source of truth (local `yad gate sync` is advisory and shows the
+   predicate without writing).
+4. Resolve the thread, approve again, a human **merges** → the mergesync run advances `state.json`
+   (`epic-review: done`, `currentStep: architecture`) + flips `epic.md` to `approved` **on the
+   default branch**.
+5. `git checkout <default> && git pull` locally — `yad gate status EP-x` matches the platform history.
+
+GitLab variant: same flow on an MR; the advance lands on the merge push (or the next schedule tick if
+a squash merge dropped the branch name).