yadflow 3.15.0 → 3.15.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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.1",
   "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-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-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`).
@@ -141,6 +142,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

@@ -32,7 +32,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

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-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": [
         {