yadflow 3.15.0 → 3.15.2

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [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)
+
+
+### Bug Fixes
+
+* **checks:** close the silent-PASS holes the [#161](https://github.com/abdelrahmannasr/yadflow/issues/161) fix left open ([0f180ab](https://github.com/abdelrahmannasr/yadflow/commit/0f180abc72618fcd793ef6717fe1e128aa5ccfa5))
+* **checks:** pin every changed contract slice, not just the first ([a79a946](https://github.com/abdelrahmannasr/yadflow/commit/a79a946aa37c08615741082bc638d006f7e80b76)), closes [#161](https://github.com/abdelrahmannasr/yadflow/issues/161)
+* **checks:** read hub.json and the contract lock across line breaks ([43a618d](https://github.com/abdelrahmannasr/yadflow/commit/43a618d0822ed8576b9a164889bc53a52bbdf713)), closes [#161](https://github.com/abdelrahmannasr/yadflow/issues/161)
+
 # [3.15.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.14.0...v3.15.0) (2026-08-10)
 
 

package/package.json

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

@@ -72,8 +72,9 @@ the approver(s) + date. Only a `verified: true` backfill spec counts as real.
 
 ### Step 5 — `gate` (block changes per touched feature)
 `bash checks/backfill-check.sh <base>` blocks a change that touches a feature being backfilled until
-that feature's spec is `verified: true`. It is **per touched feature** — a change touching feature A is
-not blocked by an unverified feature B. Forward-spec'd features (those with their own `specs/<story>/`)
+that feature's spec is `verified: true`. `<base>` is optional and resolves like every other gate's —
+see "Resolving `<base>`" in `../yad-checks/references/check-gates.md`. It is **per touched feature** —
+a change touching feature A is not blocked by an unverified feature B. Forward-spec'd features (those with their own `specs/<story>/`)
 are not this gate's concern.
 
 ### Step 6 — `promote` (flip a stub epic → real, once its spec is approved)

package/skills/yad-backfill/templates/checks/backfill-check.sh

@@ -5,13 +5,37 @@
 # forward-spec'd (their own specs/<story>/) or not yet being backfilled are not this gate's concern.
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [backfill]: no base given — diffing against '${BASE}'."
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
   echo "FAIL [backfill]: base ref '${BASE}' not found — fetch full history / check the base branch."
   exit 1
 fi
 
-changed="$(git diff --name-only "${BASE}..HEAD")"
+# quotePath off so a non-ASCII feature directory still matches src/<feature>/ below.
+changed="$(git -c core.quotePath=false diff --name-only "${BASE}..HEAD")"
 # Feature = a directory under src/ (src/<feature>/...). Top-level src/*.js files are deliberately NOT
 # gated here (they belong to no single feature); only src/<feature>/ changes are checked.
 feats="$(printf '%s\n' "$changed" | sed -nE 's#^src/([^/]+)/.*#\1#p' | sort -u)"

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

@@ -15,6 +15,7 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
    `specs/<story>/contracts/`) without a `Contract-Change: yes` trailer **and** an updated, re-locked
    contract upstream, it **FAILS and routes back to the architecture gate**. The shared surface is
    never widened from inside a code repo (Phase 2 contract representation: delimited block + SHA-256 lock).
+   Every story whose slice the diff touches is checked, not just the first — see `references/check-gates.md`.
 3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
    The CI job sets `YAD_TEST_MAX_WORKERS` (default `2`); the gate caps jest/vitest test concurrency at
    that and is a no-op for other runners (see `references/check-gates.md`).
@@ -54,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`
@@ -141,6 +146,10 @@ bash checks/spec-link.sh "<base>"
 bash checks/contract-check.sh "<base>"
 bash checks/build-test-lint.sh
 ```
+`<base>` is optional for the gates that take one (`build-test-lint` takes none) — omitted, the gate
+resolves the trunk (configured `default_branch`, else `origin/HEAD`, else `origin/main`) and prints
+the base it chose; pass it (or `SDLC_BASE`) when the PR/MR targets another branch.
+
 A non-zero exit is a FAIL. Summarize which gates passed and, for any failure, the exact remediation
 (spec-link: add the `Task:` trailer / spec; contract-check: route back to the architecture gate and
 re-lock the contract; build/test/lint: fix the failing lint/test).

package/skills/yad-checks/references/check-gates.md

@@ -19,6 +19,27 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 | pr-title | the PR/MR title (from the CI event payload) | `yad-pr-template` (`config.yaml build.pr_title_style`) |
 | pr-template | the PR/MR body (from the CI event payload) | `yad-pr-template` (the committed PR/MR template) |
 
+## Resolving `<base>` (every gate that takes one)
+
+The `<base>` argument is **optional**. The order is: the **argument**, else `SDLC_BASE`, else the
+**configured** `default_branch` (`.sdlc/hub.json`, or `SDLC_HUB_CONFIG`), else the remote's
+**published default branch** (`git symbolic-ref refs/remotes/origin/HEAD`), else `origin/main` —
+the same order the CLI resolves (`cli/hubcommit.mjs`, `cli/repo.mjs`), so a gate never diffs a
+different range than the `yad` commands run beside it. Each candidate must actually **resolve**
+before it is used, so a *dangling* `origin/HEAD` (trunk renamed, the old remote-tracking ref pruned)
+falls through instead of failing the gate on a fully-fetched repo. CI always passes the base
+explicitly (`origin/<PR base>` / `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`), so this governs
+local runs.
+
+Hardcoding `origin/main` diffed the wrong range on a repo whose trunk is `develop`/`master` — either
+failing closed for the wrong reason, or, where a stale `main` still existed, silently diffing a range
+that both mis-reports the surface and drags unrelated stories into contract-check's per-story fidelity
+pass (issue #161). An auto-resolved base is **printed as a note**, so the range a local run gated is
+never implicit. Like the `product-repo` block below, this one is duplicated verbatim across the
+scripts (they are standalone by design) and pinned byte-identical by a test — which covers every
+base-taking gate, including `yad-backfill`'s `backfill-check.sh` and the installed copies this repo's
+own CI runs, plus an assertion that each one actually *assigns* `BASE` from it.
+
 ## 1. spec-link (`templates/checks/spec-link.sh`)
 
 - Checks every non-merge commit in `<base>..HEAD` **per commit** (not aggregated across the range),
@@ -38,11 +59,13 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 - An empty range (no non-merge commits) **PASSes**.
 - Portable across bash 3.2 (macOS) and 4+ (no `mapfile`).
 - **Fails closed** when `<base>` can't be resolved (so a shallow clone / wrong base never PASSes blind).
+  `<base>` is optional — see [Resolving `<base>`](#resolving-base-every-gate-that-takes-one).
 
 ## 2. contract-check (`templates/checks/contract-check.sh`)
 
 - **Fails closed** if `<base>` can't be resolved — an undiffable range must never report "no surface
-  change" and silently green-light a bypass.
+  change" and silently green-light a bypass. `<base>` is optional — see
+  [Resolving `<base>`](#resolving-base-every-gate-that-takes-one).
 - Computes the changed files in `<base>..HEAD`.
 - If **nothing** under `specs/*/contracts/**` changed → **PASS** (normal implementation only *consumes*
   the contract).
@@ -52,6 +75,19 @@ repo uses. Each reads conventions established by earlier steps — it invents no
     require `link.md`'s pinned `contract-lock` hash to match the product repo's current
     `contract-lock.json`. A claimed change that still pins the **old** lock **FAILS** — re-run
     `yad-spec` so the slice matches the re-locked contract.
+  - The fidelity check runs for **every story whose slice the diff touches**, and **aggregates**: each
+    story reports (matched / stale / deferred), and any stale pin fails the gate. `git diff
+    --name-only` is path-sorted, so reading one story off the first changed path validated whichever
+    story sorted first and left the rest unpinned — a later story pinning a stale hash passed, and a
+    first story with no `link.md` deferred the whole check before the stale one was ever read
+    (issue #161). One clean-or-deferred story never masks another's stale pin, the same rule spec-link
+    applies per commit.
+  - A lock the gate can **read but not parse** (truncated, half-written, or a changed schema — no
+    `"hash": "sha256:…"`) **FAILS**. It used to short-circuit the comparison into the "hash matches"
+    note, i.e. the gate affirmatively reported a match it never made.
+- The changed-file list is read with `core.quotePath=false`. With git's default, a path holding a
+  non-ASCII byte comes back quoted and octal-escaped, so a slice like `specs/EP-démo-S01/contracts/…`
+  never matched the surface pattern and an undeclared widening passed untouched.
 - This enforces the Phase 2 rule: the shared surface is owned upstream and is never widened from inside
   a code repo. The hash recipe is in `../yad-architecture/references/contract-format.md`.
 
@@ -129,6 +165,7 @@ non-merge commit in `<base>..HEAD`:
 - **Profiles** (`--profile code|hub`): the subject rule is identical on both; the gate never requires
   the `Task:` trailer (spec-link owns that on code repos; hub commits are not task-scoped).
 - **Fails closed** when `<base>` can't be resolved.
+  `<base>` is optional — see [Resolving `<base>`](#resolving-base-every-gate-that-takes-one).
 
 ## 6. pr-title (`templates/checks/pr-title.sh`)
 
@@ -319,9 +356,13 @@ line). Code repos run the same three with `--profile code` inside the main `yad-
 
 ## Running by hand (Phase 3 is manual)
 
-From inside the code repo, against the PR/MR base (e.g. `master`):
+From inside the code repo, against the PR/MR base (e.g. `master`). For the gates that take one, the
+base argument is optional — omit it and the gate resolves the trunk in the order above (configured
+`default_branch`, else `origin/HEAD`, else `origin/main`), printing the base it chose; pass it (or
+`export SDLC_BASE=…`) whenever the PR targets something else. `build-test-lint` takes no base at all.
 
 ```bash
+bash checks/spec-link.sh                 # -> diffs the resolved trunk, and says which one
 bash checks/spec-link.sh master
 bash checks/contract-check.sh master
 bash checks/build-test-lint.sh

package/skills/yad-checks/templates/checks/commit-message.sh

@@ -25,7 +25,30 @@ while [ $# -gt 0 ]; do
 done
 case "$PROFILE" in code|hub) ;; *) echo "FAIL [commit-message]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
 
-BASE="${ARGS[0]:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${ARGS[0]:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${ARGS[0]:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [commit-message]: no base given — diffing against '${BASE}'."
 
 # Fail closed if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then

package/skills/yad-checks/templates/checks/contract-check.sh

@@ -8,7 +8,30 @@
 # architecture gate. Normal implementation that only CONSUMES the contract passes untouched.
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [contract-check]: no base given — diffing against '${BASE}'."
 
 # Fail CLOSED if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
 # Never let an undiffable range silently report "no surface change" — that would green-light a bypass.
@@ -18,7 +41,10 @@ if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
 fi
 RANGE="${BASE}..HEAD"
 
-changed="$(git diff --name-only "$RANGE")"
+# core.quotePath=false: with the default ON, git wraps any path holding a non-ASCII byte in quotes
+# and octal-escapes it, so a slice like specs/EP-démo-S01/contracts/api.md never matches the pattern
+# below — the surface change would be invisible to the gate it exists to stop.
+changed="$(git -c core.quotePath=false diff --name-only "$RANGE")"
 surface="$(printf '%s\n' "$changed" | grep -E '^specs/[^/]+/contracts/' || true)"
 
 if [ -z "$surface" ]; then
@@ -72,9 +98,22 @@ resolve_product() {
 
 # Fidelity check (best-effort): when the product repo is reachable, the story's link.md must pin the
 # CURRENT product lock — proof the contract was actually updated/re-locked upstream, not just flagged.
-story="$(printf '%s\n' "$surface" | head -1 | sed -E 's#^specs/([^/]+)/contracts/.*#\1#')"
-link="specs/${story}/link.md"
-if [ -f "$link" ]; then
+#
+# Checked for EVERY story whose slice the diff touches, not just the first one. `git diff --name-only`
+# is path-sorted, so reading a single story off `head -1` validated whichever story sorted first and
+# left the rest unpinned: a second story pinning a STALE hash passed, and a first story with no
+# link.md deferred the whole check before the stale one was ever read (issue #161). Failures are
+# AGGREGATED — every story reports, so one clean-or-deferred story never masks another's stale pin
+# (the same rule spec-link applies per commit).
+stories="$(printf '%s\n' "$surface" | sed -E 's#^specs/([^/]+)/contracts/.*#\1#' | sort -u)"
+rc=0
+while IFS= read -r story; do
+  [ -z "$story" ] && continue
+  link="specs/${story}/link.md"
+  if [ ! -f "$link" ]; then
+    echo "note [contract-check]: no ${link} — fidelity check deferred (spec-link gates the link itself)."
+    continue
+  fi
   product_rel="$(link_val product-repo "$link")"
   pinned="$(printf '%s' "$(link_val contract-lock "$link")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
   epic="$(printf '%s' "$story" | sed -E 's/-S[0-9]+$//')"   # story EP-<slug>-S0N -> epic EP-<slug>
@@ -85,20 +124,40 @@ if [ -f "$link" ]; then
   lock=""
   [ -n "$prod" ] && lock="${prod}/epics/${epic}/.sdlc/contract-lock.json"
   if [ -n "$product_rel" ] && [ -f "$lock" ]; then
-    current="$(sed -nE 's/.*"hash":[[:space:]]*"sha256:([0-9a-f]+)".*/\1/p' "$lock" | head -1)"
-    if [ -n "$current" ] && [ "$current" != "$pinned" ]; then
+    # Newline-tolerant, first-match: `"hash":` and its value may legally sit on separate lines, and an
+    # unparseable lock is a FAIL below — so a formatting choice must not become a gate failure.
+    # `|| current=""` is load-bearing: under `pipefail` a no-match grep fails the whole pipeline, which
+    # under `set -e` would abort the gate instead of reaching the unparseable-lock FAIL below.
+    current="$(tr '\n' ' ' < "$lock" | grep -oE '"hash"[[:space:]]*:[[:space:]]*"sha256:[0-9a-f]+"' | head -1 | sed -E 's/.*sha256:([0-9a-f]+)"$/\1/')" || current=""
+    # A lock we can READ but cannot PARSE proves nothing, and an empty `current` used to short-circuit
+    # the comparison below straight into the "hash matches" note — the gate affirmatively reporting a
+    # match it never made. Fail closed instead: a truncated, half-written or schema-changed lock is a
+    # broken lock, and a Contract-Change is being claimed against it.
+    if [ -z "$current" ]; then
+      echo "FAIL [contract-check]: ${lock} has no readable \"hash\": \"sha256:…\" value —"
+      echo "  the lock cannot prove ${link}'s pin. Re-lock the contract upstream (yad-architecture Step 5)."
+      rc=1
+      continue
+    fi
+    if [ "$current" != "$pinned" ]; then
       echo "FAIL [contract-check]: Contract-Change claimed, but ${link} still pins ${pinned:0:12}…"
       echo "  while the product lock is ${current:0:12}… — re-run yad-spec so the slice matches the re-locked contract."
-      exit 1
+      rc=1
+      continue
     fi
-    echo "note [contract-check]: link.md hash matches the product lock (${current:0:12}…)."
+    echo "note [contract-check]: ${link} hash matches the product lock (${current:0:12}…)."
   else
     # Say so. A skipped fidelity check used to be indistinguishable from a passed one, which is how a
     # mis-resolved product-repo could turn a stale-pin FAIL into a silent PASS (issue #149).
     echo "note [contract-check]: product lock not reachable at ${lock:-<no product-repo in link.md>} — fidelity check deferred."
   fi
-else
-  echo "note [contract-check]: no ${link} — fidelity check deferred (spec-link gates the link itself)."
+done <<EOF
+$stories
+EOF
+
+if [ "$rc" != 0 ]; then
+  echo "FAIL [contract-check]: a changed slice pins a stale contract lock (see above) — the surface was not re-locked upstream for every story in this diff."
+  exit 1
 fi
 
 echo "PASS [contract-check]: surface change accompanied by Contract-Change: yes (and an updated contract)."

package/skills/yad-checks/templates/checks/epic-open.sh

@@ -11,7 +11,30 @@
 # Fails CLOSED on an unresolvable base.
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [epic-open]: no base given — diffing against '${BASE}'."
 
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
   echo "FAIL [epic-open]: base ref '${BASE}' not found — fetch full history / check the base branch."

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
@@ -32,7 +34,30 @@ if [ ! -f "$HUB" ] || ! grep -Eq '"(bridge_enabled|bridge)"[[:space:]]*:[[:space
   exit 0
 fi
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [ledger-guard]: no base given — diffing against '${BASE}'."
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
   echo "FAIL [ledger-guard]: base ref '${BASE}' not found — fetch full history / check the base branch."
   exit 1
@@ -91,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
@@ -111,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/checks/lineage-check.sh

@@ -10,7 +10,30 @@
 # best-effort: the commit PASSes with a note (spec-link already proved the story link).
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [lineage-check]: no base given — diffing against '${BASE}'."
 
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
   echo "FAIL [lineage-check]: base ref '${BASE}' not found — fetch full history / check the base branch."

package/skills/yad-checks/templates/checks/reconcile-debt-check.sh

@@ -10,7 +10,30 @@
 # ci/chore/build/test exempt. Fails CLOSED on an unresolvable base.
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [reconcile-debt]: no base given — diffing against '${BASE}'."
 
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
   echo "FAIL [reconcile-debt]: base ref '${BASE}' not found — fetch full history / check the base branch."

package/skills/yad-checks/templates/checks/spec-link.sh

@@ -10,7 +10,30 @@
 # range), so the report names every offending commit.
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [spec-link]: no base given — diffing against '${BASE}'."
 
 # Fail closed if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then

package/skills/yad-checks/templates/checks/verified-commits.sh

@@ -26,7 +26,30 @@
 # GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope; see the pipeline fragment header.
 set -euo pipefail
 
-BASE="${1:-${SDLC_BASE:-origin/main}}"
+# --- shared base resolution (byte-identical across the gates; they are standalone by design, so it
+# --- is duplicated, not sourced) ---
+# With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
+# whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
+# (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
+# DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
+# candidate instead of failing the gate on a fully-fetched repo. CI always passes the base explicitly,
+# so this governs local runs only. The `|| _x=""` guards are load-bearing: under `set -e` a failing
+# command substitution in an assignment aborts the script.
+resolve_base() {
+  # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
+  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
+  for _c in "origin/${_cfg}" "${_head}" origin/main; do
+    case "$_c" in ''|origin/) continue ;; esac
+    if git rev-parse --verify --quiet "${_c}^{commit}" >/dev/null 2>&1; then printf '%s' "$_c"; return; fi
+  done
+  printf '%s' origin/main
+}
+
+BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
+[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [verified-commits]: no base given — diffing against '${BASE}'."
 
 # Fail closed if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
 if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then

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-docs/templates/app/package-lock.json

@@ -2382,9 +2382,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
-      "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
       "dev": true,
       "funding": [
         {

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