yadflow 3.12.2 → 3.13.1

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

@@ -10,7 +10,7 @@ predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The bridge
 |---|---|
 | GitHub review `APPROVED` / GitLab MR approval (`approved_by`) | an `approved` record in `approvals.json`, role resolved from the roster (owner/reviewer) or derived domain-owner, tagged `"source": "bridge"` |
 | GitHub `COMMENTED` / `CHANGES_REQUESTED`; GitLab discussions/notes | a line under `## <name> (<role>)` in `reviews/<artifact>--<date>--comments.md` + a `comments.json` record; **never** an approval. `CHANGES_REQUESTED` is also flagged as blocking in the comments file |
-| GitHub review dismissed / GitLab approval revoked | the prior bridge `approved` record for that approver is removed on re-sync (see idempotency) |
+| GitHub review dismissed / GitLab approval revoked | the prior bridge `approved` record for that approver is removed on re-sync **while the step is open**; once the step is `done` the record is kept as the audit trail of why it passed (see idempotency) |
 
 `approvals.json` records from the bridge carry `"source": "bridge"`; **manual** approvals have no such
 tag and are **never** touched by `sync` — the two coexist.
@@ -82,10 +82,21 @@ login and requested too — otherwise an escalated step is structurally unsatisf
 ## Idempotent re-sync
 
 - Key bridge approvals on `(step, approver, role, domain)`. On re-sync, **upsert** — do not append a
-  duplicate. Remove any bridge approval whose platform review was dismissed/revoked.
-- Key synced comments on the platform comment id so the same comment is not appended twice.
-- Update the step's `hub-prs.json` `lastSyncedAt` after a successful sync.
-- Running `sync` twice with no platform change is a no-op on the ledger.
+  duplicate.
+- **On an OPEN step**, remove any bridge approval whose platform review was dismissed/revoked: the
+  platform is the live source of truth while the review is in flight.
+- **On a step already `done`**, the record is only added to or refreshed in place — an approval the
+  platform no longer reports is **kept**. Those approvals are the audit record of *why* the gate
+  passed; a roster edit, an approval reset, or a degraded-but-successful read would otherwise erase
+  them and leave the step `done` with zero approvals.
+- Key synced comments on the platform comment id so the same comment is not appended twice. Comment
+  rounds are recorded for an **open** step only, so re-visiting a merged review does not append a new
+  round per pass.
+- Update the step's `hub-prs.json` `lastSyncedAt` when the sync **learned something** — every sync on
+  an open step, and on a closed one only when the approval record actually changed (a re-opened review
+  that was re-approved). An identical re-sync leaves it alone, so the ledger does not churn.
+- Running `sync` twice with no platform change is a no-op on the ledger — byte-identical, including
+  `comments.json` and the dated `reviews/*.md` side files.
 
 ## Contract re-lock invalidates prior platform approvals too
 
@@ -201,6 +212,40 @@ the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged` (th
 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.
 
+Because CI records the `hub-prs.json` pointer only at merge, a review the ledger has never seen still
+has to be nameable — otherwise `sync` refuses a PR that is sitting merged on the platform. With no
+recorded pointer, `yad gate sync <epic> <artifact>` resolves the PR/MR from the review branch
+(`review/<epic>/<artifact>`) itself, and `--pr <n>` names it outright:
+
+```bash
+yad gate sync EP-x architecture.md --pr 42   # advisory in bridge mode; the writer without the bridge
+```
+
+An explicit `--pr` also **overrides** a recorded pointer, since a re-opened review is a new PR the
+ledger has not seen. Before its reviewers are bound to the artifact's hash, the number is confirmed to
+be the PR for that artifact's review branch — a mismatch is refused, and a platform that cannot answer
+warns and proceeds. The bridge rule is unchanged: the resolved pointer is adopted into the ledger only
+on the writer path, so a human never leaves a gate-state file in their working tree for `ledger-guard`
+to reject.
+
+**In bridge mode `gate sync` stays advisory even with `--pr`** — it prints the predicate and writes
+nothing, because CI owns the ledger. The recovery that actually writes is the command CI itself runs,
+on the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged`.
+
+**Serialization.** Both wired jobs push the ledger to the default branch, and on GitLab the scheduled
+sweep's recent-MR window overlaps whatever the merge-push pipeline is handling — so they are pinned to
+one at a time (`concurrency: yad-gate-mergesync` on GitHub, `resource_group: yad-gate-mergesync` on
+GitLab). Without it both runs produce the same advance, one pushes, and the other rebases onto it and
+lands a duplicate `chore(gate): advance …` commit under a different SHA — unreviewed churn, since
+those commits carry `[skip ci]` and go straight to the default branch. An already-wired GitLab hub
+picks the `resource_group` up on the next `yad update` / `yad check --fix`.
+
+**`yad gate open` does not create or push the review branch.** It opens a PR/MR *against*
+`review/<epic>/<artifact>`, so that branch must already be **on origin** — a local-only branch is no
+use, because `gh pr create --head` does not push either. `yad open-pr`, run from the branch, pushes it
+and then delegates here. Opening with the branch absent is refused up front, before any ledger write,
+rather than failing inside `gh`/`glab`; an origin that cannot be reached at all only warns.
+
 ### Manual end-to-end verification (GitHub)
 
 1. On a scratch hub: `yad setup` (platform github, roster with a second account) → `yad check --fix`

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

@@ -17,8 +17,10 @@
 #   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).
+#   recently-merged review PRs from the API and advances any not yet done. Idempotent: a step that is
+#   already `done` is never re-advanced (the chain is one-way), and re-syncing it writes nothing unless
+#   its approvals genuinely changed — so re-visiting a merged review for a week costs one no-op read per
+#   pass, not a commit. 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.
 #
@@ -73,7 +75,8 @@ jobs:
 
   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`.
+    # event never re-fires). Idempotent — `yad gate ci` never re-advances a step that is already `done`,
+    # and a re-sync of one writes nothing unless its approvals actually changed.
     if: github.event_name == 'schedule'
     runs-on: ubuntu-latest
     concurrency:

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

@@ -19,7 +19,8 @@
 #   - MERGE push (default branch, commit names a review branch): resolve the merged MR's IID from its
 #     source branch, then advance + flip status on the default branch — near-immediate.
 #   - SCHEDULED sweep (catch-up): enumerate recently-merged review MRs via the API and advance any
-#     not yet advanced (idempotent — a step already `done` is skipped). Covers bare approvals and
+#     not yet advanced (idempotent — an already-`done` step is never re-advanced, and re-syncing it
+#     writes nothing unless its approvals changed). Covers bare approvals and
 #     squash merges whose commit message dropped the branch name. Create a pipeline schedule
 #     (one-time, cannot be committed as code): cron `*/15 * * * *` with variable SDLC_GATE_SYNC=true.
 #     UI: CI/CD > Schedules, or:
@@ -39,6 +40,15 @@ variables:
 
 yad-gate-sync:
   needs: []
+  # Serialize every advance: the merge-push pipeline and the scheduled sweep both commit the ledger
+  # and push the DEFAULT branch, and the sweep's 7-day window covers MRs the merge path is still
+  # processing — so without this they race on the same MR. Both produce the advance, one pushes, the
+  # loser rebases onto it and pushes the same commit message under a different SHA. That is where the
+  # duplicate `chore(gate): advance …` commits with shifting SHAs come from, and every one of them
+  # carries [skip ci] and lands directly on the default branch, so nothing validates the churn.
+  # `resource_group` is GitLab's equivalent of the `concurrency` group the GitHub workflow sets on both
+  # of its jobs: at most one instance runs at a time, the rest queue.
+  resource_group: yad-gate-mergesync
   # Runner selection: set the YAD_RUNNER_TAGS CI/CD variable (e.g. `dind_runner`) to route this
   # docker job on instances whose runners are tag-locked (run_untagged: false) — it lives in
   # project Settings → CI/CD → Variables, so it survives every `yad` sync. When unset, current
@@ -69,7 +79,8 @@ yad-gate-sync:
       rc=0
       if [ "$CI_PIPELINE_SOURCE" = "schedule" ]; then
         # SCHEDULED SWEEP — discover merged review MRs from the platform (Path B keeps no per-branch
-        # ledger), then advance each. `gate ci` is idempotent: a step already `done` is skipped.
+        # ledger), then advance each. `gate ci` is idempotent: an already-`done` step is never
+        # re-advanced, and re-syncing it writes nothing unless its approvals changed.
         # A stuck review MR (a squash merge whose commit dropped the branch name, or a failed merge
         # push) is always RECENT, so sweep a generous recent window and PAGINATE it fully (--paginate)
         # — this bounds cost without the old hard 50-row cap that could permanently strand older MRs.

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

@@ -131,8 +131,9 @@ via the local user's `gh`/`glab`. For each:
 - an `APPROVED` review / MR approval → append an `approved` record to `approvals.json` tagged
   `"source": "bridge"`; a `COMMENTED`/`CHANGES_REQUESTED`/note → write to
   `reviews/<artifact-base>--<YYYY-MM-DD>--comments.md` + `comments.json` (never an approval).
-**Idempotent:** upsert bridge approvals by `(step, approver, role, domain)`, supersede revoked ones, and
-key comments on the platform comment id (re-running `sync` does not duplicate). **Manual approvals (no
+**Idempotent:** upsert bridge approvals by `(step, approver, role, domain)`, supersede revoked ones
+**while the step is open** (a step already `done` keeps its approvals — they are the record of why it
+passed), and key comments on the platform comment id (re-running `sync` does not duplicate). **Manual approvals (no
 `source` tag) are never touched.** For the architecture+contract step, discard bridge approvals dated
 before a new contract lock (re-lock invalidates platform approvals too). Then refresh the `approved.md`
 roster, set `hub-prs.json` `lastSyncedAt`, and **re-evaluate Step 3**. Under the PR-driven CLI (`yad
@@ -170,7 +171,9 @@ If the predicate **passes**:
 
 ### PR-driven automation (the `yad gate` CLI)
 When the hub has a platform, **CI is the sole writer of the ledger**. `yad gate open` opens the review
-PR only; CI (`yad gate ci`) writes the `.sdlc/` + `reviews/` records this skill describes. The skill's
+PR only — against the `review/<epic>/<artifact>` branch, which must already exist (create it and run
+`yad open-pr` from it, which pushes it first). CI (`yad gate ci`) writes the `.sdlc/` + `reviews/`
+records this skill describes. The skill's
 job is the human half: presenting the artifact, helping the owner address comments, and narrating the
 gate. Local `yad gate sync` is advisory in bridge mode (reads the platform, prints status, writes
 nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it).
@@ -179,6 +182,13 @@ Under that CLI the gate **advances on merge**: a review PR/MR whose reviewer rul
 comment threads are **all resolved**, and which has been **merged** auto-marks the step `done` and
 unblocks the next step. (Until those three hold, the step stays `in_review`.)
 
+**Re-reviewing a step that already advanced.** A step is advanced **once** — the chain is never pulled
+backward. But a step that is `done` is still *synced*: when the artifact is edited (for architecture, a
+re-locked contract surface) its prior approvals go stale, and the approvals arriving on the new review
+PR/MR are recorded and bound to the new content. `yad gate status` then shows the truth — how many
+approvals are live against what is in the file today, and how many were revoked — instead of a `done`
+step whose approvals all belong to the version before the edit.
+
 The flow is **merge-driven** (wired by `yad-hub-bridge` `wire`): during review CI writes nothing — the
 platform PR/MR is the source of truth (native approvals + threads), and CI never touches the review
 branch (so an in-flight approval is never dismissed and required checks never strand). On the human

package/skills/yad-review-gate/references/gating.md

@@ -42,7 +42,9 @@ content. This prevents "approve, then quietly change it" (build plan §5 spirit)
 For the architecture+contract review there is a second, content-based staleness check: recompute the
 SHA-256 of the contract-surface block and compare it to `.sdlc/contract-lock.json`. A mismatch means
 the locked surface changed even if the file's mtime looks fine — approvals are stale, re-lock and
-re-approve. (Hash recipe: `yad-architecture/references/contract-format.md`.)
+re-approve. (Hash recipe: `yad-architecture/references/contract-format.md`.) `yad` computes the
+identical digest, so `yad doctor` performs this comparison for every epic and FAILs on a surface that
+drifted from its lock — run it rather than recomputing by hand.
 
 ## Worked example — epic gate
 
@@ -91,8 +93,10 @@ approvals regardless of how they were recorded.
 - On PR/MR open the assignee is the committer and reviewers are the scope's `reviewer` + `domain-owner`
   members (minus the committer); the owner/author is recorded, not requested. See
   `../yad-hub-bridge/references/login-roster.md`.
-- `sync` is idempotent (upsert by `(step, approver, role, domain)`; supersede revoked; key comments on
-  comment id) and never touches **manual** approvals.
+- `sync` is idempotent (upsert by `(step, approver, role, domain)`; key comments on comment id) and
+  never touches **manual** approvals. A revoked approval is superseded **while the step is open**; once
+  the step is `done` its approvals are kept as the record of why it passed, and a re-sync only re-binds
+  new ones (see `../yad-hub-bridge/references/bridge.md` → "Idempotent re-sync").
 - The architecture+contract staleness rule applies to bridge approvals too: a re-lock discards bridge
   approvals dated before the new lock.
 - No platform / no CLI → the gate runs file-only with no error. Detail: `../yad-hub-bridge/references/bridge.md`.

package/skills/yad-spec/references/spec-handoff.md

@@ -68,7 +68,7 @@ story: EP-<slug>-S0N
 epic: EP-<slug>
 repo: <repo>
 feature-id: EP-<slug>-S0N
-product-repo: <absolute or relative path to the product repo>
+product-repo: <path to the product repo — absolute, or relative to THIS file's dir (specs/<story>/)>
 contract-lock: sha256:<hex copied from epics/EP-<slug>/.sdlc/contract-lock.json>
 speckit: installed | not-installed
 generated: <YYYY-MM-DD>
@@ -86,6 +86,16 @@ The contract surface above is **referenced, not re-defined**. Any change to the
 back to the architecture gate in the product repo — it is never widened from this code repo.
 ```
 
+`product-repo` is the one field CI resolves on disk (contract-check, lineage-check, epic-open,
+reconcile-debt all read it). Every gate resolves it the SAME way: an **absolute** path is used as-is; a
+**relative** path is joined to this `link.md`'s own directory, `specs/<story>/` — `../../` climbs out
+of the story dir and out of `specs/` to the code-repo root, so a hub checked out beside the code repo
+is `../../../<hub-dir>`. A relative value that only resolves from the **repo root** still works too
+(what contract-check historically did), so older `link.md` files keep gating. Write it as an
+**unquoted scalar** — `"..."` or `'...'` is taken literally, and a leading `~`/`$VAR` is never
+expanded. An unreachable path degrades the hub-reading gates to a PASS-with-note rather than failing
+them, and each one now says so in its output.
+
 ## Do not re-invent the contract
 
 The spec **quotes** the locked surface; it never extends it. To confirm the surface the spec relies on
@@ -93,7 +103,7 @@ matches the lock, run from the **product** repo:
 
 ```bash
 awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
-  epics/EP-<slug>/contract.md | shasum -a 256
+  epics/EP-<slug>/contract.md | tr -d '\r' | shasum -a 256
 # compare against epics/EP-<slug>/.sdlc/contract-lock.json
 ```