yadflow 3.15.3 → 3.15.4

package/CHANGELOG.md

@@ -1,3 +1,5 @@
+## [3.15.4](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.3...v3.15.4) (2026-08-12)
+
 ## [3.15.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.2...v3.15.3) (2026-08-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.15.3",
+  "version": "3.15.4",
   "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, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-architecture/SKILL.md

@@ -178,9 +178,22 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 > of hash-binding.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
-In `state.json`: set `architecture.status: "done"`, set `architecture-review.status: "in_review"`, and
-set `currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
-real reviewers approve, through the gate.
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit the artifact set — **`architecture.md`, `contract.md`, and
+`.sdlc/contract-lock.json`** (artifact-side, not ledger) — then hand off to `yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`architecture.status: "done"`, set `architecture-review.status: "in_review"`, and set
+`currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
+real reviewers approve, through the gate. On this branch `yad gate open` makes the same edit, so it
+is a no-op once the gate has run.
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the paths to `architecture.md`, `contract.md`, and `contract-lock.json`; the contract hash;

package/skills/yad-backfill/SKILL.md

@@ -99,6 +99,12 @@ thread off it, `promote` is what makes that anchor real — run it once the feat
   "wake" the state chain — set `currentStep: "epic"`, `epic` step `status: "in_progress"` — then run
   `yad-epic` → `yad-architecture` → … the normal way. This re-locks a contract that subsequent thread
   changes will inherit.
+- **Bridge mode — promote is not wired.** The `state.json` edits above mutate an epic whose ledger is
+  already on the base ref, so the `#162` seed exemption does not apply and `ledger-guard` rejects the
+  commit; unlike the authoring steps there is no `yad backfill` CLI and no `gate ci` path that performs
+  the promotion instead. On a bridge hub, STOP and report this — the promotion needs the gate bot (or a
+  maintainer landing it out of band). Only the `epic.md` half is safe to commit. Tracked as a gap; do
+  **not** push the ledger edit around the guard.
 - Never auto-advances; a human confirms the promotion.
 
 ### Step 7 — Stop (no auto-advance)

package/skills/yad-epic/SKILL.md

@@ -169,14 +169,31 @@ Notes:
 
 ### Step 5b — Advance the authoring step — analysis-ran only
 *(Only when analysis ran — `state.json` already exists from `yad-analysis`.)*
-In `state.json`: set `epic.status: "done"`, set `epic-review.status: "in_review"`, and set
-`currentStep: "epic-review"`. Write `state.json`. Do **not** re-seed and do **not** touch
-`approvals.json` — only real reviewers approve, through the gate.
-
-> Since 3.11 the CLI closes the authoring step itself whenever its review gate opens or advances
-> (`yad gate open` / `sync`), so this edit is a no-op when the gate has already run. Keep making it —
-> it keeps `state.json` truthful before the gate opens — but it is no longer load-bearing: an epic
-> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`).
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit **`epic.md` only** — nothing else under `.sdlc/` — then hand off
+to `yad-review-gate`.
+
+> **This is not the Step 5 seed exemption.** `ledger-guard` exempts a *brand-new* epic's ledger
+> (creation, not mutation, #162). On this path `state.json` already exists from `yad-analysis` and
+> reached the base ref through the analysis review — so the guard is absolute here.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`epic.status: "done"`, set `epic-review.status: "in_review"`, and set `currentStep: "epic-review"`.
+Write `state.json`. Do **not** re-seed and do **not** touch `approvals.json` — only real reviewers
+approve, through the gate.
+
+> **File-only branch only.** Since 3.11 the CLI closes the authoring step itself whenever its review
+> gate opens or advances (`yad gate open` / `sync`), so this edit is a no-op when the gate has already
+> run. It keeps `state.json` truthful before the gate opens, but it is no longer load-bearing: an epic
+> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`). In bridge mode
+> `gate open` writes nothing and local `gate sync` is advisory — `gate ci` closes the step at merge.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `epic.md`, and that the next action is **review** via

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

@@ -54,16 +54,28 @@ touched `repos` — never a forked or copied gate.
 
 ### Step 2 — Dispatch on `action`
 
+> **Check the mode first — in bridge mode you write nothing to the ledger.** Read `.sdlc/hub.json`:
+> **bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`. Under the bridge
+> the ledger is CI-owned — `ledger-guard` rejects any non-bot commit touching
+> `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`, local `yad gate
+> sync` is advisory, and `yad gate ci --merged` writes the whole transition when the review PR merges.
+> So every "set / append / write" instruction below is the **file-only, or a platform with no
+> gate-sync CI** path. In bridge mode do the human-facing half — present the artifact, route the
+> required reviewers, help the owner address comments — and let the platform PR/MR carry the review
+> state; the approvals, comments, review records and the advance all land through CI at merge.
+
 **`open`** — Present the artifact for review. Summarise what changed, list the required reviewers per
 the rule above, and tell reviewers how to comment/approve. Set the step `status` to `in_review` and
 `currentStep` to this step in `state.json` if not already. Do not advance.
 
-If `.sdlc/hub.json` has a non-null `platform`, `bridge_enabled: true`, `config.yaml` `hub.bridge: true`,
-and `gh`/`glab` is authenticated, **also open a review PR/MR on the hub** by invoking
-`yad-hub-bridge action: open` (epic + artifact). Record the PR in `epics/<epic>/.sdlc/hub-prs.json`
-(`{step, artifact, platform, number, url, branch, lastSyncedAt}`) and report the URL + required
-reviewers. Otherwise (no platform / disabled / no CLI) proceed **file-only** exactly as before — no
-error. Opening the PR records no approvals and never advances.
+If `.sdlc/hub.json` has a non-null `platform` and `bridge_enabled: true` (or legacy `bridge: true` —
+`.sdlc/hub.json` is the only source the CLI reads, see `isBridge` in `cli/gate.mjs`), and `gh`/`glab`
+is authenticated, **also open a review PR/MR on the hub** by invoking `yad-hub-bridge action: open`
+(epic + artifact), and report the URL + required reviewers. **CI records the PR** in
+`epics/<epic>/.sdlc/hub-prs.json` (`{step, artifact, platform, number, url, branch, lastSyncedAt}`) —
+write that file yourself only on the file-only path. Otherwise (no platform / disabled / no CLI)
+proceed **file-only** exactly as before — no error. Opening the PR records no approvals and never
+advances.
 
 **`comment`** — Capture reviewer feedback. Append/create a review file
 `reviews/<artifact-base>--<YYYY-MM-DD>--comments.md` with a heading per reviewer:

package/skills/yad-stories/SKILL.md

@@ -101,12 +101,26 @@ As a <role>, I want <capability>, so that <outcome>.
 `repos` is the field the later build phase reads to know where to scaffold specs — set it precisely.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
-In `state.json`: set `stories.status: "done"`, set `stories-review.status: "in_review"`, and set
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit **the story files under `stories/` only** — nothing else
+under `.sdlc/` — then hand off to `yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`stories.status: "done"`, set `stories-review.status: "in_review"`, and set
 `currentStep: "stories-review"`. Write `state.json`. Do **not** touch `approvals.json`.
 
-> Since 3.11 the CLI also closes the authoring step when its review gate opens or advances, so this
-> edit is a no-op once `yad gate open` has run. A `stories` step left `in_progress` behind a passed
-> `stories-review` used to block the parallel `test-cases` track (`YAD-STATE-005`).
+> **File-only branch only.** Since 3.11 the CLI also closes the authoring step when its review gate
+> opens or advances, so this edit is a no-op once `yad gate open` has run. A `stories` step left
+> `in_progress` behind a passed `stories-review` used to block the parallel `test-cases` track
+> (`YAD-STATE-005`). In bridge mode `gate open` writes nothing and local `gate sync` is advisory —
+> `gate ci` closes the step at merge.
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the story IDs created, the repos each touches, and that the next action is **review** via

package/skills/yad-test-cases/SKILL.md

@@ -162,9 +162,24 @@ Keep the `## Automation (<tool>)` section of `test-cases.md` in step with this f
 degraded (`testing: none`), do **not** write `test-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
-In `state.json`: set `test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave
-`currentStep` at `ready-for-build`** — this is the parallel track; moving `currentStep` would pull it
-back from the build half. Write `state.json`. Do **not** touch `approvals.json`.
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit the artifact set — **`test-cases.md` and, when a testing
+tool was used, `.sdlc/test-links.json`** (artifact-side, not ledger; generated tests live in their
+own code repo, not here) — then hand off to `yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave `currentStep` at
+`ready-for-build`** — this is the parallel track; moving `currentStep` would pull it back from the
+build half. Write `state.json`. Do **not** touch `approvals.json`. On this branch `yad gate open`
+makes the same edit — `markInReview` leaves `currentStep` alone once it is `ready-for-build`
+(`cli/epic-state.mjs`) — so it is a no-op once the gate has run.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the path to `test-cases.md`, the connected testing tool and what it produced (e.g. "Playwright —

package/skills/yad-ui/SKILL.md

@@ -171,8 +171,22 @@ Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file.
 (`design: none`), do **not** write `design-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
-In `state.json`: set `ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
-`currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`.
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+
+**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+`epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
+`yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
+fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
+is pushed around the gate. Commit the artifact set — **`ui-design.md`, `DESIGN.md`, and, when a
+design tool was used, `.sdlc/design-links.json`** (artifact-side, not ledger) — then hand off to
+`yad-review-gate`.
+
+**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+`ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
+`currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`. On this
+branch `yad gate open` makes the same edit, so it is a no-op once the gate has run.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, the connected design