yadflow 3.13.0 → 3.13.1

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
 ```