yadflow 3.14.0 → 3.15.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [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)
+
+
+### Features
+
+* **testing:** add maestro as a testing-tool adapter ([7718b50](https://github.com/abdelrahmannasr/yadflow/commit/7718b502814ee8e0eb46f5e6f20342fc2471dbd7))
+
 # [3.14.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.2...v3.14.0) (2026-08-10)
 
 

package/cli/manifest.mjs

@@ -135,7 +135,7 @@ export const DESIGN_PRIMARY = 'figma';
 // is the fallback `registerTesting`/setup use when an unknown tool is named, and `none` is the explicit
 // artifacts-only choice. (doctor does NOT fall back — an unknown tool there is a hard YAD-CFG-003 fail,
 // mirroring the design-tool YAD-CFG-002.)
-export const TESTING_TOOLS = ['playwright', 'cypress', 'pytest'];
+export const TESTING_TOOLS = ['playwright', 'cypress', 'pytest', 'maestro'];
 export const TESTING_PRIMARY = 'playwright';
 
 // Supported learning-tool adapters (mirrors skills/sdlc/config.yaml `learning.tools`); `LEARNING_PRIMARY`

package/cli/setup.mjs

@@ -590,9 +590,12 @@ export async function runSetup(root, opts = {}) {
     }
 
     // Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
-    S('Connect a testing tool (playwright / cypress / pytest / none)');
+    // Banner + guide read TESTING_TOOLS rather than spelling the adapters out: this is the list that
+    // actually grows (maestro joined it), and a hardcoded copy here would quietly offer the user fewer
+    // tools than the prompt below accepts.
+    S(`Connect a testing tool (${TESTING_TOOLS.join(' / ')} / none)`);
     guide([
-      'Where yad-test-cases generates automation. playwright/cypress/pytest, or none for artifacts-only.',
+      `Where yad-test-cases generates automation. ${TESTING_TOOLS.join('/')}, or none for artifacts-only.`,
       'Skipping is safe — test-cases authors test-cases.md only.',
     ]);
     if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.14.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/sdlc/config.yaml

@@ -198,7 +198,7 @@ design:
 # (test-links.json) is written by yad-test-cases per epic.
 testing:
   registry: "{project-root}/.sdlc/testing.json"      # project-wide testing connection (NOT per-epic)
-  tools: [playwright, cypress, pytest]                # supported adapters; an unknown tool falls back to `primary`
+  tools: [playwright, cypress, pytest, maestro]       # supported adapters; an unknown tool falls back to `primary`
   primary: playwright                                 # the default/named provider
   degrade: artifacts-only                             # no tool / no MCP => yad-test-cases authors test-cases.md only
   links: "{project-root}/epics/EP-<slug>/.sdlc/test-links.json"   # per-epic case->test map (yad-test-cases)

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-connect-testing/SKILL.md

@@ -21,7 +21,7 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
 - `{project-root}` resolves from the project working directory (the **product hub**).
 - The integration is **Playwright-first but pluggable** (`config.yaml` `testing.tools`): a testing-tool
   *adapter*, like the GitHub/GitLab platform adapter or the design-tool adapter. Playwright is the
-  primary provider; `cypress` and `pytest` are second providers; `none` → artifacts-only.
+  primary provider; `cypress`, `pytest` and `maestro` are second providers; `none` → artifacts-only.
 - **The testing tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the
   same shape as the design tool's MCP, not Repomix's `npx`. The skill detects the MCP and degrades when
   it is absent; it never installs an MCP server.
@@ -34,7 +34,7 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
 ## Inputs
 
 - `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
-- `tool` — `playwright` | `cypress` | `pytest` | another adapter id (`config.yaml` `testing.tools`).
+- `tool` — `playwright` | `cypress` | `pytest` | `maestro` | another adapter id (`config.yaml` `testing.tools`).
   `none` records a deliberate artifacts-only project.
 - `project_url` — the testing tool's project/config reference (e.g. a `playwright.config.ts` path or a
   test-runner project URL). Optional — a connection with no suite yet is valid; `yad-test-cases` can
@@ -51,9 +51,13 @@ way `registerRepo` falls back on an unknown platform). Then **detect the tool's
 - **playwright** → a Playwright MCP server (drives a browser, generates/runs E2E + API specs).
 - **cypress** → the Cypress MCP (generate/run Cypress specs).
 - **pytest** → a pytest MCP (generate/run service-layer tests).
+- **maestro** → the Maestro MCP, bundled in the Maestro CLI and started as `maestro mcp` over STDIO
+  (drives iOS simulators, Android emulators and Chromium; generates/runs Maestro flows). Mobile E2E,
+  where Playwright has no reach.
 - another adapter → its named MCP.
 
-Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `pytest-mcp`) and whether
+Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `pytest-mcp` |
+`maestro-mcp`) and whether
 it is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
 **stores no tokens**; `project_url`/`suites` are plain references, never credentials.
 

package/skills/yad-connect-testing/references/testing-context.md

@@ -15,6 +15,7 @@ Detection is best-effort against the user's own authenticated MCP session:
 | `playwright` | a Playwright MCP | **generate** — author + run E2E/API specs against the app |
 | `cypress` | the Cypress MCP | **generate** — author + run Cypress specs |
 | `pytest` | a pytest MCP | **generate** — author + run service-layer tests |
+| `maestro` | the Maestro MCP (`maestro mcp`, bundled in the CLI, STDIO) | **generate** — author + run Maestro flows on iOS/Android/Chromium |
 | any | a read-only runner MCP | **link** — reference an existing suite and read results back |
 | other | the adapter's named MCP | per that adapter |
 
@@ -34,6 +35,11 @@ the cases `test-cases.md` enumerates and the acceptance criteria the stories def
   the code-maps from `yad-test-cases` Step 2b), one spec per high-priority (P0/P1) case, and runs them
   via the MCP to confirm they execute.
 - **Cypress / pytest** — the lens authors the equivalent specs in that framework's layout.
+- **Maestro** — the lens authors `.yaml` flows under the repo's Maestro directory (one flow per
+  high-priority case), targeting the app id / screen elements the code-maps name rather than invented
+  ones, and runs them via the MCP against a simulator/emulator to confirm they execute. Mobile E2E is
+  the top of that pyramid: keep the flow count small and push detail down to the unit/integration
+  levels the repo already has.
 
 Reuse what already exists: load the connected code repos' code-maps (`yad-test-cases` Step 2b) so
 generated tests target real endpoints/components, not invented ones, and prefer the lowest useful test

package/skills/yad-connect-testing/references/testing-registry.md

@@ -14,8 +14,8 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
 
 ```json
 {
-  "tool": "playwright",                              // playwright | cypress | pytest | <adapter id> | none (artifacts-only)
-  "provider": "playwright-mcp",                      // the concrete MCP: playwright-mcp | cypress-mcp | pytest-mcp | null
+  "tool": "playwright",                              // playwright | cypress | pytest | maestro | <adapter id> | none
+  "provider": "playwright-mcp",                      // the concrete MCP: playwright-mcp | cypress-mcp | pytest-mcp | maestro-mcp | null
   "project_url": "tests/playwright.config.ts",       // project/config reference; null if none yet
   "auth": "user",                                    // ALWAYS the user's own MCP session — never a token
   "suites": { "backend": null, "mobile": null },     // optional default suite refs per repo

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-test-cases/SKILL.md

@@ -94,7 +94,8 @@ Read `{project-root}/.sdlc/testing.json` (`config.yaml` `testing.registry`). Dec
   the Markdown artifact only and record `testing: none` in the frontmatter with a one-line note
   (mirrors the `design: none` degrade). Skip to Step 4.
 - **A tool is connected and its MCP is available:** adopt the `test architect` lens and, using the
-  provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest via theirs) drive
+  provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest/Maestro via
+  theirs — Maestro authors mobile flows where Playwright has no reach) drive
   `bmad-testarch-automate`:
   - **Generate** — when the provider is write-capable, author one automation test per high-priority
     (P0/P1) case into the connected code repo(s) for the repos in `epic.repos`, reusing the code-maps
@@ -120,7 +121,7 @@ status: draft
 owner: <inherit from epic.md owner>   # the epic owner carries through; not retyped
 repos: [<inherit from epic>]
 code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps that informed the tests (Step 2b)
-testing: <none | { tool: <playwright|cypress|pytest|…>, direction: <generated|linked>, suite: <url/path>, tests: <N> }>   # the connected testing tool (Step 3b)
+testing: <none | { tool: <playwright|cypress|pytest|maestro|…>, direction: <generated|linked>, suite: <url/path>, tests: <N> }>   # the connected testing tool (Step 3b)
 ---
 
 ## Test strategy & risk