yadflow 3.15.1 → 3.15.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [3.15.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.1...v3.15.2) (2026-08-11)
+
+
+### Bug Fixes
+
+* **checks:** exempt a new epic's ledger seed from ledger-guard ([ba923c2](https://github.com/abdelrahmannasr/yadflow/commit/ba923c2a3823e8bf17b2fc59b41f0160a3a11a19)), closes [#162](https://github.com/abdelrahmannasr/yadflow/issues/162)
+
 ## [3.15.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.15.0...v3.15.1) (2026-08-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.15.1",
+  "version": "3.15.2",
   "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-analysis/SKILL.md

@@ -138,6 +138,10 @@ Notes:
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory.
+- Commit the seed on the `analysis/EP-<slug>` branch, and cut `review/EP-<slug>/analysis` from it so the
+  epic's **first** review PR/MR carries the ledger to the default branch. In bridge mode `ledger-guard`
+  exempts a new epic's ledger (creation, not mutation, #162); every later change to it is CI's. See
+  `../yad-epic/references/state-schema.md`, "Authoring branches".
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `analysis.md`, and that the next action is **review** via

package/skills/yad-change/SKILL.md

@@ -134,6 +134,12 @@ Seed `.sdlc/approvals.json` with one **provenance** record per inherited gate (N
 `{ "artifact": "<art>", "step": "<…-review>", "status": "inherited", "from": "<epic>", "boundHash": "<hash>", "date": "<today>" }`.
 Seed `.sdlc/comments.json` = `[]` and create `reviews/`.
 
+Commit the seed on the `change/EP-<slug>` branch. It reaches the hub's default branch through this
+change-epic's **first** review PR/MR — cut the `review/EP-<slug>/<artifact>` branch from `change/…` so
+it carries the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation,
+#162), so no direct push to a protected default branch is needed; every later change to that ledger is
+CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
+
 When `architecture` is **inherited**, materialize the **pointer-lock** `.sdlc/contract-lock.json`:
 `{ "artifact": "contract.md", "hash": "<parent surface hash, verbatim>", "lockedAt": "<today>", "inheritedFrom": "<epic>", "ref": "../../<epic>/.sdlc/contract-lock.json" }`.
 There is no `contract.md` in the change-epic, so the surface cannot drift, and `contract-check` passes

package/skills/yad-checks/SKILL.md

@@ -55,7 +55,11 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
     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`
+    spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. So is a **new epic's seed**:
+    no CI path can create a ledger (`gate ci` only *advances* an existing chain, at merge, on the
+    default branch), so an epic whose `.sdlc/state.json` is absent from the base ref may be created by
+    a human on its first review PR/MR — **creation, not mutation** (#162). Once the ledger is on the
+    default branch the guard is absolute again. 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`

package/skills/yad-checks/templates/checks/ledger-guard.sh

@@ -11,6 +11,8 @@
 # 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 brand-new epic's ledger — CREATION is not mutation (#162). No CI path can seed one, so the
+#   seed rides the first review PR/MR; see the carve-out below. Mutation stays bot-only.
 #
 # 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
@@ -114,19 +116,81 @@ trusted_bot() {
   signature_verified "$1"
 }
 
+# ---- seeding carve-out: creation is not mutation (#162) ---------------------------------------
+# A brand-new epic's ledger has no CI author. `gate ci` only ADVANCES an existing chain — it bails on
+# a missing state.json ("the review branch is cut from the default branch, so it should carry it") and
+# writes only at merge, on the default branch — and the engine itself reads a missing state.json as
+# "not seeded yet". `gate open` writes nothing in bridge mode, and `checkpoint` stages back-half
+# ledgers only. So the seed the authoring skills write (yad-epic / yad-change / yad-analysis /
+# yad-discovery / yad-stub) can reach the trunk ONLY through the first review PR/MR — the one place
+# this gate runs. Guarding it there makes the documented flow unshippable on a protected trunk, so an
+# epic whose ledger is absent from the BASE ref is exempt: that ledger is human-authored by
+# construction and the reviewer sees the whole of it in the diff. The moment its state.json is on the
+# base ref the guard is absolute again.
+#
+# Anchored on state.json — the ledger root, the same "is this epic seeded?" question the engine asks —
+# NOT on the individual file: adding hub-prs.json to an epic that IS on the base ref still FAILs.
+# Anchored on the BASE ref, not the parent commit, so delete-then-re-add cannot reset the exemption
+# (the deletion is itself a guarded change).
+#
+# The slug match is CASE-FOLDED on purpose. Git paths are byte-exact, but macOS/Windows checkouts are
+# not: seeding `epics/ep-x/.sdlc/state.json` beside an on-base `epics/EP-X/` would probe as a brand-new
+# epic, pass, and then land ON TOP of the real ledger in every case-insensitive clone — a mutation
+# laundered as a creation. So the base's seeded slugs are read once (one ls-tree, not one probe per
+# path) and compared folded.
+#
+# Slugs are held in ARRAYS read from NUL-delimited git output, never in a space- or newline-delimited
+# string: git permits a newline inside a path, and a `EP-<newline>x` slug split across two records
+# would drop the real epic out of the on-base list and let a mutation through as a "creation". Both
+# arrays carry one empty sentinel element so `"${a[@]}"` is safe under `set -u` on bash 3.2 (macOS),
+# which has no associative arrays; a slug is never empty, so the sentinel can never match.
+base_slugs=("")                     # every epic with a ledger on BASE, lowercased
+base_slugs_loaded=0
+noted_slugs=("")                    # slugs already announced, so the note prints once each
+fold() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+in_list() {                         # $1 = needle, $2… = haystack
+  _needle="$1"; shift
+  for _item in "$@"; do [ "$_item" = "$_needle" ] && return 0; done
+  return 1
+}
+is_seeding() {                      # $1 = epic slug; 0 when that epic has no ledger on BASE
+  if [ "$base_slugs_loaded" = 0 ]; then
+    while IFS= read -r -d '' _p; do
+      case "$_p" in
+        epics/*/.sdlc/state.json)
+          _s="${_p#epics/}"; _s="${_s%%/*}"
+          base_slugs[${#base_slugs[@]}]="$(fold "$_s")"
+          ;;
+      esac
+    done < <(git -c core.quotePath=false ls-tree -r --name-only -z "${BASE}" -- epics 2>/dev/null || true)
+    base_slugs_loaded=1
+  fi
+  _f="$(fold "$1")"
+  in_list "$_f" "${base_slugs[@]}"  && return 1
+  in_list "$_f" "${noted_slugs[@]}" && return 0
+  noted_slugs[${#noted_slugs[@]}]="$_f"
+  echo "note [ledger-guard]: epics/$1 has no ledger on ${BASE} — new epic, its seed is exempt (creation, not mutation)."
+  return 0
+}
+
 violations=0
 for sha in $commits; do
   touches_ledger=0
-  while IFS= read -r f; do
+  # quotePath=false + -z on both git reads: a path git chose to escape ("epics/EP-caf\303\251/…") and a
+  # path holding a newline both match no arm below, so the gate would fail OPEN on exactly the paths it
+  # is meant to guard. NUL is the only byte a git path cannot contain.
+  while IFS= read -r -d '' 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)
+        _slug="${f#epics/}"; _slug="${_slug%%/*}"
+        is_seeding "$_slug" && continue      # a new epic's seed — not a mutation of a CI-owned ledger
         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")
+  done < <(git -c core.quotePath=false diff-tree --no-commit-id --name-only -r -z "$sha")
   if [ "$touches_ledger" = 1 ] && ! trusted_bot "$sha"; then
     violations=$((violations + 1))
   fi
@@ -134,7 +198,18 @@ 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."
+  # An epic's seed is exempt only while its ledger is off the base ref. Once the first review PR merges
+  # (squashed or rebased, so the SHAs differ), those same seed commits still sitting on a sibling
+  # authoring branch read as mutations — the author did nothing wrong and the remedy is a rebase, so
+  # name it rather than leaving them with "do not commit the ledger yourself".
+  echo "hint [ledger-guard]: if these are seed commits from an already-merged review PR, rebase this branch onto the updated ${BASE} — the seed carve-out applies only until the ledger is on the base ref."
   exit 1
 fi
-echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit."
+# Say WHICH rule passed the range: claiming "every change is a bot commit" would be false on a range
+# whose only ledger change was a human seed the carve-out let through.
+if [ "${#noted_slugs[@]}" -gt 1 ]; then   # >1: the sentinel element is always there
+  echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit or a new epic's seed."
+else
+  echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit."
+fi
 exit 0

package/skills/yad-checks/templates/github/yad-hub-checks.yml

@@ -55,7 +55,9 @@ jobs:
           body="$(mktemp)"; printf '%s' "$PR_BODY" > "$body"
           bash checks/pr-template.sh --profile hub --head "$PR_HEAD" --changed "$changed" "$body"
 
-  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
+  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,hub-prs}.json
+  # or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
+  # brand-new epic's seed, which no CI path can write, so it rides this first review PR (#162).
   ledger-guard:
     runs-on: ubuntu-latest
     if: github.event.action != 'edited'

package/skills/yad-checks/templates/gitlab/yad-hub-checks.gitlab-ci.yml

@@ -44,7 +44,9 @@ yad-hub-pr-template:
     - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
     - bash checks/pr-template.sh --profile hub --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
 
-# The gate ledger is CI-owned: reject non-bot commits to .sdlc/*.json or reviews/*.md.
+# The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,hub-prs}.json
+# or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
+# brand-new epic's seed, which no CI path can write, so it rides this first review MR (#162).
 yad-hub-ledger-guard:
   extends: .yad_hub_mr_only
   needs: []

package/skills/yad-discovery/SKILL.md

@@ -112,6 +112,10 @@ Notes:
   never escalates to domain owners (no contract surface is touched yet).
 - Also create an empty approvals ledger `.sdlc/approvals.json` and comments ledger
   `.sdlc/comments.json`, each containing `[]`, and the `reviews/` directory.
+- Commit the seed on the `discovery/EP-discovery` branch, and cut `review/EP-discovery/discovery` from
+  it so the **first** review PR/MR carries the ledger to the default branch. In bridge mode
+  `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162); every later change to it
+  is CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the path to the discovery set, and that the next action is **review** via `yad-review-gate`

package/skills/yad-epic/SKILL.md

@@ -152,6 +152,10 @@ Notes:
 - `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
   when `stories-review` passes — at which point the epic is already `ready-for-build`, so the build half
   runs alongside the tester. They never gate `ready-for-build` (see `references/state-schema.md`).
+- Commit the seed on this step's authoring branch. It reaches the hub's default branch through the
+  epic's **first** review PR/MR — cut `review/EP-<slug>/epic` from the authoring branch so it carries
+  the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162);
+  every later change to it is CI's. See `references/state-schema.md`, "Authoring branches".
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the

package/skills/yad-epic/references/state-schema.md

@@ -94,6 +94,16 @@ The shared procedure (run once the `EP-<slug>` is known):
    hub's default branch (`git checkout -b <step>/EP-<slug>`).
 3. Author and commit the step's artifact(s) on that branch. The bridge's `review/…` branch is created
    separately at review time and is untouched by this step.
+
+**How the seed reaches the default branch.** The `.sdlc/` ledger is seeded once, by hand, on the
+**entry** step's authoring branch (`analysis/…`, `epic/…`, `change/…`, `discovery/…`) — no CLI or CI
+path creates one (`yad gate ci` only *advances* an existing chain, at merge, on the default branch).
+So for the **first** gate of an epic, cut `review/EP-<slug>/<artifact-base>` from that authoring
+branch: the review PR/MR then carries the seed alongside the artifact, and the ledger lands on the
+default branch when it merges. In bridge mode `ledger-guard` exempts exactly this case — **creation,
+not mutation** (#162) — so no direct push to a protected default branch is needed. For every **later**
+gate the ledger is already on the default branch: cut the review branch from there, commit the
+artifact only, and leave `.sdlc/{state,approvals,comments,hub-prs}.json` and `reviews/*.md` to CI.
 | `type` | `author` \| `review+approve` | Authoring step or a team review gate. |
 | `artifact` | filename or folder | The file/folder this step produces or gates. |
 | `assistance` | `none` \| `review` \| `heavy` | Dial 1 — how much AI helps (build plan §2). |

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

@@ -52,7 +52,10 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
 ### Step 2 — `open` (create the review PR/MR)
 1. From the hub default branch, create `review/EP-<slug>/<artifact-base>` and ensure the artifact file
    (and, for architecture, `contract.md` + `.sdlc/contract-lock.json`) is committed on it. Push as the
-   local user.
+   local user. **First gate of a new epic:** cut the review branch from the **authoring** branch
+   (`epic/…`, `change/…`, `analysis/…`, `discovery/…`) instead, so it carries the `.sdlc/` **seed** —
+   that PR/MR is the only way a new epic's ledger reaches the default branch, and `ledger-guard`
+   exempts it (see step 4).
 2. Open the PR/MR with `gh`/`glab` using the hub body template (`yad-pr-template` `templates/hub/…`),
    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
@@ -68,7 +71,9 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
    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.)
+   PR only and writes no ledger.) The **one** exception is a brand-new epic's **seed** — no CI path can
+   create a ledger, so an epic whose `.sdlc/state.json` is absent from the base ref may be created by a
+   human on this first PR/MR (#162). Every later change to it is CI's alone.
 5. Report the PR/MR URL and the required reviewers. **Do not** record approvals or advance — reviewers
    act on the platform; CI (`yad gate ci`) reconciles it onto the default branch at merge.
 
@@ -143,7 +148,8 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
 - **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").
+  "Known limitation"). Safe to require: a new epic's `.sdlc/` seed rides its first review PR/MR, so
+  nobody needs a direct push to the default branch to start an epic (#162).
 - **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

@@ -155,7 +155,9 @@ During review CI writes nothing: the platform PR/MR is the source of truth (nati
 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.
+approvals fresh from the platform** — so no ledger needs to be pre-seeded on the branch. (It only
+*advances* a chain, though: it cannot **create** one. A brand-new epic's seed therefore travels the
+other way — up through its first review PR/MR; see "the seed of a new epic" below.)
 
 | Platform event | Phase | CI action |
 |---|---|---|
@@ -174,13 +176,26 @@ commit — the advance plus the `draft → approved` status flip — lands on th
 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;
+edit — which it rejects, with one carve-out for a new epic's seed (below). (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.)
 
-**The one sanctioned human ledger write: `yad gate repair`.** It heals a `YAD-STATE-005` chain (an
+**The one sanctioned human ledger write *in a review PR*: the seed of a new epic.** `gate ci` only
+**advances** an existing chain — it bails on a missing `state.json`, and the engine reads that absence
+as "not seeded yet" — so no CI path can ever create a ledger. The seed the authoring skills write
+(`yad-epic`, `yad-change`, `yad-analysis`, `yad-discovery`, `yad-stub`) can reach the default branch
+only through the epic's **first** review PR/MR, which is exactly where `ledger-guard` runs. So the gate
+exempts **creation**: an epic whose `.sdlc/state.json` is absent from the PR's base ref may have its
+ledger written by a human there (#162). It stays a narrow carve-out — the probe is against the base
+ref, not the parent commit, so deleting an on-trunk `state.json` to "re-seed" it is itself a rejected
+mutation, and the moment the ledger is on the default branch every further change is CI's alone. Cut
+that first review branch from the authoring branch (`epic/…`, `change/…`) so it carries the seed; no
+direct push to a protected default branch is needed.
+
+**The one sanctioned human ledger write *on the default branch*: `yad gate repair`.** It heals a `YAD-STATE-005` chain (an
 authoring step stranded behind a review gate that already advanced) by writing `state.json` alone. This
 is not a `ledger-guard` gap: the repair commits to the **default branch**, where `ledger-guard` — which
 only inspects review PRs — never runs, and where the `yad-update-guard` (platform-Verified signature +

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

@@ -176,7 +176,9 @@ PR only — against the `review/<epic>/<artifact>` branch, which must already ex
 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).
+nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it). The single
+exception is an epic's **seed** — no CI path can create a ledger, so a brand-new epic's `.sdlc/` rides
+its **first** review PR/MR, cut from the authoring branch (creation, not mutation, #162).
 
 Under that CLI the gate **advances on merge**: a review PR/MR whose reviewer rule is satisfied, whose
 comment threads are **all resolved**, and which has been **merged** auto-marks the step `done` and

package/skills/yad-stub/SKILL.md

@@ -115,6 +115,11 @@ into normal authoring with zero re-seeding.
 Also create the empty ledgers `{.sdlc/approvals.json}` and `{.sdlc/comments.json}` (each `[]`) and the
 `reviews/` directory. **Do NOT** write a `contract-lock.json` — a stub has no locked surface yet.
 
+Commit the seed on this step's authoring branch; it reaches the hub's default branch through the
+epic's **first** review PR/MR (or, for a stub, the PR that carries the stub itself). In bridge mode
+`ledger-guard` exempts a new epic's ledger — creation, not mutation (#162) — while every later change
+to it stays CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
+
 ### Step 6 — Stop; hand off (NO auto-advance)
 Report the new `EP-<slug>`, that it is a **stub (backfill pending)**, and the two next moves:
 - **File bugs now:** `yad-change` (`--parent EP-<slug>`, `kind: defect|change`) — the defect threads off