yadflow 2.13.0 → 2.15.0

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-epic/SKILL.md

@@ -40,7 +40,10 @@ exists for the idea.
 
 Either mode runs Step 3b (branch), Step 4 (write the epic), and Step 6 (stop at the gate).
 
-If `state.json` exists but `currentStep != "epic"`, stop and point the user at `yad-status` / the gate.
+**Precondition gate (rail):** if `state.json` already exists (analysis-ran or re-entry), run
+`yad next EP-<slug> --check epic` — if it exits non-zero, **STOP** and surface the blocker, pointing the
+user at `yad next EP-<slug>`. When no `state.json` exists yet, this is the greenfield entry point — the
+check is not applicable, so proceed and seed state.
 
 ### Step 2 — Shape the idea (assist: analyst) — or read the analysis
 - **Analysis skipped:** ask the user for a one-line feature idea if not provided, then adopt the

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).

package/skills/yad-hub-bridge/templates/github/yad-gate-sync.yml

@@ -1,52 +1,60 @@
 # yad-managed: yad-hub-bridge
-# Event-driven gate sync for the PRODUCT HUB. When a reviewer approves, requests changes, or a
-# human merges a review/EP-* PR, this workflow runs `yad gate ci`, which maps the platform state
-# into the file ledger (epics/<epic>/.sdlc/*.json + reviews/*.md) and commits ONLY those ledger
-# files to the default branch. It never approves and never merges — the merge click remains the
-# human approval act; the gate predicate is the same one `yad gate sync` runs locally.
+# Merge-time gate sync for the PRODUCT HUB (Path B). CI is the SOLE writer of the ledger, and it
+# writes ONLY at merge, ONLY to the default branch.
 #
-# Loop prevention: neither `pull_request_review` nor `pull_request` fires on a push to the default
-# branch, and the ledger commit carries [skip ci] to guard every other workflow.
+# During review there is NO CI write: the platform PR is the source of truth (native approvals +
+# review threads). CI never pushes to the review branch, so an in-flight approval is never dismissed
+# by a CI commit and the PR's required checks never strand on one. Because nothing is pushed to the
+# PR head, you can safely enable "Dismiss stale pull request approvals when new commits are pushed"
+# — only the artifact owner's own pushes will dismiss approvals (the intended revoke-on-change).
 #
-# Protected default branch? The github.token push will fail (visibly — the run goes red and manual
-# `yad gate sync` still works). Options, in order of preference:
-#   a) add a ruleset bypass so GitHub Actions may push to the default branch, or
-#   b) store a fine-grained PAT as the SDLC_GATE_TOKEN secret and pass it to actions/checkout via
-#      `with: { token: ${{ secrets.SDLC_GATE_TOKEN }} }` — the one exception to the bridge's
-#      no-stored-tokens rule; see skills/yad-hub-bridge/references/bridge.md.
+# Two jobs:
+#   MERGE (PR closed + merged): the fast path. Check out the default branch (the human merge already
+#   landed the artifact there) and run `yad gate ci --branch <head> --pr <n> --merged`. CI re-reads
+#   the PR's approvals fresh from the platform, advances the step, and flips the artifact `status:` to
+#   approved — committing that advance to the default branch with [skip ci].
+#
+#   RECONCILE (schedule, every 15 min): the safety net. The merge job's `closed` event fires once and
+#   never repeats, so a transient API/GraphQL/push failure (or a fail-closed degraded approval read)
+#   would otherwise strand a merged review until someone reran it by hand. This periodic job discovers
+#   recently-merged review PRs from the API and advances any not yet done (idempotent — a step already
+#   `done` is skipped). On GitHub a scheduled workflow runs automatically once committed (no setup).
+#
+# 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.
 name: yad-gate-sync
 on:
-  pull_request_review:
-    types: [submitted, dismissed]
   pull_request:
-    types: [closed, synchronize] # closed -> merged advance; synchronize -> prompt revoke-on-change
+    types: [closed]
+  schedule:
+    - cron: "*/15 * * * *"
 
 permissions:
-  contents: write # push the ledger commit
+  contents: write # push the merge-advance ledger commit to the default branch
   pull-requests: read # gh pr view + reviewThreads GraphQL
 
-# Serialize runs repo-wide so ledger pushes never race; sync reads the FULL platform state each
-# time, so a queued superseded run loses nothing.
-concurrency:
-  group: yad-gate-sync
-  cancel-in-progress: false
-
 jobs:
-  sync:
+  mergesync:
+    # The human merge of a review branch: advance the step + flip the artifact status on the default
+    # branch. Nothing runs pre-merge — review state lives on the platform until the merge.
     if: >
+      github.event_name == 'pull_request' &&
       startsWith(github.event.pull_request.head.ref, 'review/EP-') &&
-      (github.event_name == 'pull_request_review' ||
-       github.event.action == 'synchronize' ||
-       github.event.pull_request.merged == true)
+      github.event.pull_request.merged == true
     runs-on: ubuntu-latest
+    # Serialize every advance with the reconcile job — they all push the default branch.
+    concurrency:
+      group: yad-gate-mergesync
+      cancel-in-progress: false
     env:
       GH_TOKEN: ${{ github.token }}
     steps:
-      # Check out the BASE branch (not the PR merge ref): the ledger lives there, and `gate ci`
-      # overlays the artifact from the head ref itself so approvals bind to the reviewed content.
-      # A head branch auto-deleted on merge is fine: the event payload still carries head.ref (the
-      # string `gate ci` parses), and a failed fetch just skips the overlay — by then the artifact
-      # is already on the base branch via the merge.
+      # Check out the default branch — the merge already landed the artifact here.
       - uses: actions/checkout@v4
         with:
           ref: ${{ github.event.pull_request.base.ref }}
@@ -54,10 +62,52 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
-      - name: Sync the gate ledger
+      - name: Advance the gate on merge
         run: |
           git config user.name  "yad-gate-sync[bot]"
           git config user.email "yad-gate-sync[bot]@users.noreply.github.com"
-          npx -y -p yadflow@2 yad gate ci \
+          npx -y -p yadflow@3 yad gate ci \
             --branch "${{ github.event.pull_request.head.ref }}" \
-            --pr "${{ github.event.pull_request.number }}"
+            --pr "${{ github.event.pull_request.number }}" \
+            --merged
+
+  reconcile:
+    # Safety net: recover any merged review PR whose merge-time run failed transiently (the `closed`
+    # event never re-fires). Idempotent — `yad gate ci` skips a step that is already `done`.
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: yad-gate-mergesync
+      cancel-in-progress: false
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Reconcile recently-merged review PRs
+        run: |
+          git config user.name  "yad-gate-sync[bot]"
+          git config user.email "yad-gate-sync[bot]@users.noreply.github.com"
+          # A stuck merged review is always recent; window generously and let `gate ci` no-op the rest.
+          # Page the search API fully (no fixed result cap) so a stuck PR is never missed for volume.
+          # Aggregate failures and exit nonzero so a persistent API/push failure surfaces (red run)
+          # instead of silently stranding a merged gate behind a green safety-net. Read from a file,
+          # not a pipe, so the failure flag survives (a piped `while` runs in a subshell).
+          SINCE="$(date -u -d '7 days ago' +%Y-%m-%d 2>/dev/null || date -u -v-7d +%Y-%m-%d)"
+          rc=0
+          gh api --paginate -X GET search/issues \
+            --raw-field q="repo:${GITHUB_REPOSITORY} type:pr is:merged merged:>=${SINCE}" \
+            --jq '.items[].number' > /tmp/yad-merged-prs || rc=1
+          while read -r N; do
+            [ -n "$N" ] || continue
+            REF="$(gh pr view "$N" --json headRefName --jq '.headRefName' 2>/dev/null)" || rc=1
+            case "$REF" in
+              review/EP-*) npx -y -p yadflow@3 yad gate ci --branch "$REF" --pr "$N" --merged || rc=1 ;;
+            esac
+          done < /tmp/yad-merged-prs
+          exit $rc