yadflow 3.13.0 → 3.13.1

package/cli/platform.mjs

@@ -298,6 +298,86 @@ export function readPr(platform, n, opts = {}) {
   return platform === 'gitlab' ? readPrGitLab(n, opts) : readPrGitHub(n, opts);
 }
 
+// ---- find the PR/MR for a branch ----------------------------------------------------------------
+// The review PR/MR opened for `review/EP-<slug>/<artifact>`, by HEAD/source branch. Under the bridge
+// the ledger records that pointer only at merge (CI is the sole writer), so without this a human has
+// no way to name the review a merged PR belongs to — `gate sync` would just report "no open review PR
+// recorded" for a PR that is sitting merged on the platform (issue #158).
+//
+// State is deliberately UNfiltered: the interesting case is a MERGED PR that never advanced. Newest
+// first, so a re-opened review resolves to its current PR and not a superseded one. Returns
+// { ok, number, url } — never throws; `ok:false` carries the reason.
+export function findPrForBranch(platform, branch, { cwd } = {}) {
+  if (!branch) return { ok: false, reason: 'no branch given' };
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'gitlab') {
+    const r = run('glab', ['api', `projects/:id/merge_requests?source_branch=${encodeURIComponent(branch)}&order_by=updated_at&sort=desc&per_page=1`], { cwd });
+    if (!r.ok) return { ok: false, reason: r.stderr || 'glab api merge_requests failed' };
+    let rows;
+    try { rows = JSON.parse(r.stdout); } catch { return { ok: false, reason: 'unreadable glab api response' }; }
+    const mr = Array.isArray(rows) ? rows[0] : null;
+    if (!mr?.iid) return { ok: false, reason: `no merge request found for source branch ${branch}` };
+    return { ok: true, number: Number(mr.iid), url: mr.web_url || null };
+  }
+  const r = run('gh', ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '1', '--json', 'number,url'], { cwd });
+  if (!r.ok) return { ok: false, reason: r.stderr || 'gh pr list failed' };
+  let rows;
+  try { rows = JSON.parse(r.stdout); } catch { return { ok: false, reason: 'unreadable gh pr list response' }; }
+  const pr = Array.isArray(rows) ? rows[0] : null;
+  if (!pr?.number) return { ok: false, reason: `no pull request found for head branch ${branch}` };
+  return { ok: true, number: Number(pr.number), url: pr.url || null };
+}
+
+// The head/source branch of a PR/MR, so a caller can confirm a number a human typed actually belongs
+// to the review it is about to bind approvals to. Returns { ok, branch }; never throws.
+export function prBranch(platform, n, { cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'gitlab') {
+    const r = run('glab', ['api', `projects/:id/merge_requests/${Number(n)}`], { cwd });
+    if (!r.ok) return { ok: false, reason: r.stderr || 'glab api merge_request failed' };
+    try {
+      const mr = JSON.parse(r.stdout);
+      return mr?.source_branch ? { ok: true, branch: mr.source_branch } : { ok: false, reason: `MR !${n} has no source_branch` };
+    } catch { return { ok: false, reason: 'unreadable glab api response' }; }
+  }
+  const r = run('gh', ['pr', 'view', String(n), '--json', 'headRefName'], { cwd });
+  if (!r.ok) return { ok: false, reason: r.stderr || 'gh pr view failed' };
+  try {
+    const pr = JSON.parse(r.stdout);
+    return pr?.headRefName ? { ok: true, branch: pr.headRefName } : { ok: false, reason: `PR #${n} has no headRefName` };
+  } catch { return { ok: false, reason: 'unreadable gh pr view response' }; }
+}
+
+// Is `branch` on ORIGIN? `gate open` opens a PR against the review branch but never creates or pushes
+// it — and neither does the platform CLI, since `gh pr create --head <b>` explicitly disables its
+// automatic push. So a branch that exists only locally is just as unusable as one that does not exist
+// at all, and checking locally would wave it through into the opaque platform error this replaces.
+// Returns null when git cannot answer (not a checkout, no origin, network/auth failure) — "unknown"
+// must never read as "missing" and block.
+export function branchExists(cwd, branch) {
+  if (!run('git', ['rev-parse', '--git-dir'], { cwd }).ok) return null;
+  // This runs synchronously on the `gate open` path, so "cannot ask" has to be FAST — a blocked probe
+  // is a hung command, not the intended null. Three separate ways it could block:
+  //   GIT_TERMINAL_PROMPT=0  — git's own credential prompt (https origins)
+  //   GIT_SSH_COMMAND        — ssh's passphrase / host-key prompts, which git's flag does NOT cover
+  //                            (an unset host key otherwise waits on "Are you sure…?" forever)
+  //   timeout                — anything else that stalls: a black-holed host, a wedged helper
+  // A caller's own GIT_SSH_COMMAND wins; we only supply the default.
+  const remote = run('git', ['ls-remote', '--exit-code', '--heads', 'origin', branch], {
+    cwd,
+    timeout: 10_000,
+    env: {
+      ...process.env,
+      GIT_TERMINAL_PROMPT: '0',
+      GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -oBatchMode=yes -oStrictHostKeyChecking=accept-new',
+    },
+  });
+  if (remote.ok) return true;
+  // exit 2 is ls-remote's own "no matching ref" — the only definite negative. Anything else (no
+  // remote configured, auth, offline) is a question we could not ask.
+  return remote.code === 2 ? false : null;
+}
+
 // ---- create a PR/MR -----------------------------------------------------------------------------
 // `assignees` = the committer/PR-opener (always set, so the PR is owned by whoever pushed it);
 // `reviewers` = the scope's reviewers + domain-owners (computed by reviewersForScopes). On GitHub an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.13.0",
+  "version": "3.13.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",
@@ -62,8 +62,8 @@
   ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
     "eslint": "^10.5.0",
     "semantic-release": "^25.0.3"
   }

package/skills/yad-architecture/SKILL.md

@@ -155,16 +155,28 @@ themselves) and write `{project-root}/epics/EP-<slug>/.sdlc/contract-lock.json`:
 ```
 
 Canonicalization (so the hash round-trips): hash the surface region as written between the markers,
-LF line endings, no leading/trailing blank-line normalization beyond what is in the file. Recompute
-the same way later; if it differs, the contract surface changed. The reference command:
+LF line endings, including the newline that terminates the last surface line, and no leading/trailing
+blank-line normalization beyond what is in the file. Recompute the same way later; if it differs, the
+contract surface changed. The command below **is** the definition — `yad` computes the identical
+digest, so `yad doctor` can verify `contract-lock.json` against the live `contract.md` and FAIL when
+the surface drifted from its lock:
 
 ```bash
 awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
-  epics/EP-<slug>/contract.md | shasum -a 256
+  epics/EP-<slug>/contract.md | tr -d '\r' | shasum -a 256
 ```
 
 (See `references/contract-format.md` for the altitude rule and the exact hashing recipe.)
 
+> **Upgrading from a yadflow before this recipe and the CLI agreed.** The CLI used to omit the final
+> newline, so the digest it bound approvals to differed from the one the recipe above wrote into
+> `contract-lock.json` — always, on every surface. Lock files are unaffected (they were written by the
+> recipe and are now verifiable), but **architecture approvals recorded under the old CLI are bound to
+> the old digest and go stale once**. An in-flight `architecture-review` therefore needs re-approval
+> after the upgrade; a step already `done` stays done and is reported by `yad doctor` (see the
+> `…:stale` check) rather than silently re-opened. Nothing else re-binds on its own — that is the point
+> of hash-binding.
+
 ### Step 6 — Advance the authoring step (NOT the gate)
 In `state.json`: set `architecture.status: "done"`, set `architecture-review.status: "in_review"`, and
 set `currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only

package/skills/yad-architecture/references/contract-format.md

@@ -49,7 +49,10 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 ```
 
 - `awk` emits every line strictly between the two markers (the `next` after BEGIN skips the BEGIN
-  line; setting `f=0` on END stops before printing END).
+  line; setting `f=0` on END stops before printing END), each **terminated by a newline** — so the
+  hashed bytes are the surface lines joined by LF **plus a trailing LF**. That trailing byte is part
+  of the digest; `yad` computes the identical value (`contractSurfaceHash`, `cli/epic-state.mjs`), so
+  the lock file and what the gate binds approvals to are the same number.
 - `tr -d '\r'` normalizes CRLF line endings to LF before hashing — the same surface must hash
   identically no matter which platform last saved the file (the CLI normalizes the same way).
 - `shasum -a 256` (BSD/macOS) or `sha256sum` (GNU/Linux) produce the same hex digest for identical

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

@@ -26,6 +26,10 @@ repo uses. Each reads conventions established by earlier steps — it invents no
 - Maintenance commits are **exempt**: a Conventional-Commits subject of type `ci`, `chore`, `build`,
   or `test` (optional `(scope)` / breaking `!`) **PASSes** without a link — CI wiring, dependency
   bumps, and test-infra changes legitimately link no story.
+- The exemption waives the **requirement** for a link, never the **validity** of one that is claimed.
+  A maintenance commit that *does* carry a `Task:` trailer is resolved like any other: a malformed id
+  or a missing `specs/<story>/link.md` **FAILS**. Otherwise the trailer is decorative on exempt
+  commits and an unlinked `chore:` is indistinguishable from one naming a story that never existed.
 - For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
 - The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
   `EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
@@ -168,10 +172,23 @@ After the contract locks and code ships, a change must not mutate a locked artif
 epic threaded to its parent (`config.yaml` `change:`). These three gates keep that discipline. All three
 resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md` (`epic` + `product-repo`)
 → the hub epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
-commits are exempt. When the **product hub is not reachable** from CI (the usual case for a code-repo
+commits **with no `Task:` trailer** are exempt — like spec-link, the exemption waives the requirement
+for an owning epic, never the validity of one that is claimed, so a maintenance subject cannot buy a
+pass past the sealed-epic / orphan-thread / frozen-thread checks. When the **product hub is not reachable** from CI (the usual case for a code-repo
 PR), each degrades to a **PASS-with-note** — the hub-side check (`yad doctor` / `yad reconcile`) covers
 that path, and spec-link still proves the story link.
 
+**Resolving `product-repo` (shared by all four hub-reading gates, contract-check included).** An
+**absolute** value is used as-is; a **relative** value is joined to the `link.md`'s own directory,
+`specs/<story>/`, falling back to a repo-root reading when only that resolves (what contract-check
+historically did, so `link.md` files written for it keep working). The `link.md` itself is read from
+its frontmatter block, falling back to a whole-file scan for a pre-frontmatter one. Every gate applies
+the identical rule — when they disagree, a value one gate can resolve becomes an unreachable path for
+another, and "unreachable" is a PASS-with-note, so the gate silently stops gating (issue #149). Each
+gate now **prints that note**, so a deferred check is never mistaken for a passed one. The block is
+duplicated verbatim across the four scripts (they are standalone by design) and a test asserts the
+four copies stay byte-identical.
+
 - **lineage-check** — reads the hub epic's `kind`/`parent` frontmatter. A `feature` (genesis) epic
   passes. A `change`/`defect`/`hotfix` epic **FAILS** unless it declares a `parent:` that resolves to a
   real `epics/<parent>/` in the hub (no orphan threads). This is the "every code change has an owning

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

@@ -38,15 +38,52 @@ if ! printf '%s\n' "$cc" | grep -qx 'yes'; then
   exit 1
 fi
 
+# --- shared link.md resolution (byte-identical in contract-check / lineage-check / epic-open /
+# --- reconcile-debt-check; the gates are deliberately standalone, so it is duplicated, not sourced) ---
+# Read one frontmatter value from the FIRST --- … --- block only. awk bounds to the first block (stops
+# at the first closing fence), so a body `---` or an absent key can never leak a body line. Plain
+# scalars only; trailing spaces/CR are stripped so they never become part of a path.
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r' | sed -E 's/[[:space:]]+$//'; }
+
+# Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
+# pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
+# rather than silently reading an empty value and skipping the check it guards. Deliberately separate
+# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+link_val() {
+  _v="$(fm_val "$1" "$2")"
+  [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
+  printf '%s' "$_v"
+}
+
+# Resolve link.md's `product-repo` to a path in THIS checkout. An ABSOLUTE value is used as-is. A
+# RELATIVE value is written relative to the link.md's own directory (specs/<story>/) — the canonical
+# form — but contract-check historically read it from the repo root, so a link.md authored against that
+# reading still resolves: prefer the canonical join, fall back to the root-relative one when only it
+# exists. All four gates share this verbatim, so a value one gate can reach is reachable from every
+# gate (issue #149). An unexpanded ~ or $VAR is returned untouched, so it fails the reachability test
+# loudly instead of being joined into a nonsense path.
+resolve_product() {
+  case "$1" in
+    '') return ;;
+    /*|'~'*|'$'*) printf '%s' "$1" ;;
+    *) if [ -d "specs/$2/$1" ] || [ ! -d "$1" ]; then printf 'specs/%s/%s' "$2" "$1"; else printf '%s' "$1"; fi ;;
+  esac
+}
+
 # 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
-  product_rel="$(sed -nE 's/^product-repo:[[:space:]]*(.*)$/\1/p' "$link" | head -1)"
-  pinned="$(sed -nE 's/^contract-lock:[[:space:]]*sha256:([0-9a-f]+).*$/\1/p' "$link" | head -1)"
+  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>
-  lock="${product_rel}/epics/${epic}/.sdlc/contract-lock.json"
+  prod="$(resolve_product "$product_rel" "$story")"
+  # Only build the lock path when the product repo actually resolved. With an empty `prod` the
+  # interpolation yields "/epics/<epic>/…" — a path rooted at the filesystem root, which is both a
+  # misleading thing to print and, on a machine that happened to have /epics, a foreign file to read.
+  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
@@ -55,7 +92,13 @@ if [ -f "$link" ]; then
       exit 1
     fi
     echo "note [contract-check]: link.md 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)."
 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

@@ -20,8 +20,37 @@ fi
 RANGE="${BASE}..HEAD"
 EXEMPT='ci|chore|build|test'
 
-# Read one frontmatter value from the FIRST --- … --- block only (awk stops at the first closing fence).
-fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r'; }
+# --- shared link.md resolution (byte-identical in contract-check / lineage-check / epic-open /
+# --- reconcile-debt-check; the gates are deliberately standalone, so it is duplicated, not sourced) ---
+# Read one frontmatter value from the FIRST --- … --- block only. awk bounds to the first block (stops
+# at the first closing fence), so a body `---` or an absent key can never leak a body line. Plain
+# scalars only; trailing spaces/CR are stripped so they never become part of a path.
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r' | sed -E 's/[[:space:]]+$//'; }
+
+# Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
+# pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
+# rather than silently reading an empty value and skipping the check it guards. Deliberately separate
+# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+link_val() {
+  _v="$(fm_val "$1" "$2")"
+  [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
+  printf '%s' "$_v"
+}
+
+# Resolve link.md's `product-repo` to a path in THIS checkout. An ABSOLUTE value is used as-is. A
+# RELATIVE value is written relative to the link.md's own directory (specs/<story>/) — the canonical
+# form — but contract-check historically read it from the repo root, so a link.md authored against that
+# reading still resolves: prefer the canonical join, fall back to the root-relative one when only it
+# exists. All four gates share this verbatim, so a value one gate can reach is reachable from every
+# gate (issue #149). An unexpanded ~ or $VAR is returned untouched, so it fails the reachability test
+# loudly instead of being joined into a nonsense path.
+resolve_product() {
+  case "$1" in
+    '') return ;;
+    /*|'~'*|'$'*) printf '%s' "$1" ;;
+    *) if [ -d "specs/$2/$1" ] || [ ! -d "$1" ]; then printf 'specs/%s/%s' "$2" "$1"; else printf '%s' "$1"; fi ;;
+  esac
+}
 
 # Is the epic SEALED? true iff it has >=1 story and EVERY stories/*.md frontmatter status is `shipped`.
 epic_sealed() {
@@ -50,11 +79,15 @@ while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
   subject="$(git log -1 --format=%s "$sha")"
-  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
-    echo "PASS [epic-open]: ${short} '${subject}' — maintenance commit (exempt)"
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  # The type exemption waives the REQUIREMENT for an owning epic, not the VALIDITY of one that is
+  # claimed — same rule spec-link applies. Exempting on the subject alone would let `chore(x): …` plus
+  # a Task trailer pointing at a SEALED epic add behaviour to it, which is exactly what this gate exists
+  # to refuse.
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: " && [ -z "$task" ]; then
+    echo "PASS [epic-open]: ${short} '${subject}' — maintenance commit, no Task trailer (exempt)"
     continue
   fi
-  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
   if ! printf '%s' "$task" | grep -qE '.+-T[0-9]+$'; then
     echo "note [epic-open]: ${short} has no resolvable Task trailer — deferring to spec-link."
     continue
@@ -62,8 +95,8 @@ while IFS= read -r sha; do
   story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
   link="specs/${story}/link.md"
   [ -f "$link" ] || { echo "note [epic-open]: ${short} ${task} — link.md missing (spec-link will FAIL)."; continue; }
-  product_rel="$(fm_val product-repo "$link")"
-  epic="$(fm_val epic "$link")"
+  product_rel="$(link_val product-repo "$link")"
+  epic="$(link_val epic "$link")"
   # A malformed link.md (empty product-repo, or an epic that is not a real EP-<slug>) must FAIL, not
   # slip through as "not reachable" — an empty epic would collapse ep_dir to <product>/epics/ (a real
   # dir) and pass the seal check as if the epic were open.
@@ -72,8 +105,7 @@ while IFS= read -r sha; do
     rc=1
     continue
   fi
-  # product-repo is relative to the link.md's directory (specs/<story>/), so join it there.
-  prod="specs/${story}/${product_rel}"
+  prod="$(resolve_product "$product_rel" "$story")"
   ep_dir="${prod}/epics/${epic}"
   if [ ! -d "$prod" ]; then
     echo "PASS [epic-open]: ${short} ${task} -> ${epic} (product repo not reachable — seal check deferred)."

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

@@ -19,10 +19,37 @@ fi
 RANGE="${BASE}..HEAD"
 EXEMPT='ci|chore|build|test'
 
+# --- shared link.md resolution (byte-identical in contract-check / lineage-check / epic-open /
+# --- reconcile-debt-check; the gates are deliberately standalone, so it is duplicated, not sourced) ---
 # Read one frontmatter value from the FIRST --- … --- block only. awk bounds to the first block (stops
 # at the first closing fence), so a body `---` or an absent key can never leak a body line. Plain
-# scalars only.
-fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r'; }
+# scalars only; trailing spaces/CR are stripped so they never become part of a path.
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r' | sed -E 's/[[:space:]]+$//'; }
+
+# Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
+# pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
+# rather than silently reading an empty value and skipping the check it guards. Deliberately separate
+# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+link_val() {
+  _v="$(fm_val "$1" "$2")"
+  [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
+  printf '%s' "$_v"
+}
+
+# Resolve link.md's `product-repo` to a path in THIS checkout. An ABSOLUTE value is used as-is. A
+# RELATIVE value is written relative to the link.md's own directory (specs/<story>/) — the canonical
+# form — but contract-check historically read it from the repo root, so a link.md authored against that
+# reading still resolves: prefer the canonical join, fall back to the root-relative one when only it
+# exists. All four gates share this verbatim, so a value one gate can reach is reachable from every
+# gate (issue #149). An unexpanded ~ or $VAR is returned untouched, so it fails the reachability test
+# loudly instead of being joined into a nonsense path.
+resolve_product() {
+  case "$1" in
+    '') return ;;
+    /*|'~'*|'$'*) printf '%s' "$1" ;;
+    *) if [ -d "specs/$2/$1" ] || [ ! -d "$1" ]; then printf 'specs/%s/%s' "$2" "$1"; else printf '%s' "$1"; fi ;;
+  esac
+}
 
 commits="$(git rev-list --no-merges "$RANGE")"
 if [ -z "$commits" ]; then
@@ -35,11 +62,14 @@ while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
   subject="$(git log -1 --format=%s "$sha")"
-  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
-    echo "PASS [lineage-check]: ${short} '${subject}' — maintenance commit (exempt)"
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  # The type exemption waives the REQUIREMENT for an owning epic, not the VALIDITY of one that is
+  # claimed — same rule spec-link applies. Exempting on the subject alone would let `chore(x): …` plus
+  # a Task trailer pointing at an orphaned/sealed epic bypass this gate entirely.
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: " && [ -z "$task" ]; then
+    echo "PASS [lineage-check]: ${short} '${subject}' — maintenance commit, no Task trailer (exempt)"
     continue
   fi
-  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
   # No / malformed Task trailer is spec-link's job to FAIL; here we only skip what we can't resolve.
   if ! printf '%s' "$task" | grep -qE '.+-T[0-9]+$'; then
     echo "note [lineage-check]: ${short} has no resolvable Task trailer — deferring to spec-link."
@@ -51,15 +81,14 @@ while IFS= read -r sha; do
     echo "note [lineage-check]: ${short} ${task} — specs/${story}/link.md missing (spec-link will FAIL)."
     continue
   fi
-  product_rel="$(fm_val product-repo "$link")"
-  epic="$(fm_val epic "$link")"
+  product_rel="$(link_val product-repo "$link")"
+  epic="$(link_val epic "$link")"
   if [ -z "$epic" ]; then
     echo "FAIL [lineage-check]: ${short} ${task} — link.md has no 'epic:' (cannot place it in a thread)."
     rc=1
     continue
   fi
-  # product-repo is relative to the link.md's directory (specs/<story>/), so join it there.
-  prod="specs/${story}/${product_rel}"
+  prod="$(resolve_product "$product_rel" "$story")"
   epicmd="${prod}/epics/${epic}/epic.md"
   # Defer ONLY when the product checkout itself is unreachable. A reachable hub whose epic is missing is
   # an orphaned story link — FAIL, do not pass it off as "not reachable".

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

@@ -19,7 +19,37 @@ fi
 RANGE="${BASE}..HEAD"
 EXEMPT='ci|chore|build|test'
 
-fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r'; }
+# --- shared link.md resolution (byte-identical in contract-check / lineage-check / epic-open /
+# --- reconcile-debt-check; the gates are deliberately standalone, so it is duplicated, not sourced) ---
+# Read one frontmatter value from the FIRST --- … --- block only. awk bounds to the first block (stops
+# at the first closing fence), so a body `---` or an absent key can never leak a body line. Plain
+# scalars only; trailing spaces/CR are stripped so they never become part of a path.
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r' | sed -E 's/[[:space:]]+$//'; }
+
+# Same, for a link.md field. yad-spec writes link.md WITH frontmatter, but code repos still carry
+# pre-frontmatter ones that contract-check used to read with a whole-file scan — so fall back to that
+# rather than silently reading an empty value and skipping the check it guards. Deliberately separate
+# from fm_val: hub artifacts (epic.md, stories/*.md) stay bounded to their first block.
+link_val() {
+  _v="$(fm_val "$1" "$2")"
+  [ -n "$_v" ] || _v="$(sed -nE "s/^$1:[[:space:]]*(.*)\$/\1/p" "$2" 2>/dev/null | head -1 | tr -d '\r' | sed -E 's/[[:space:]]+$//')"
+  printf '%s' "$_v"
+}
+
+# Resolve link.md's `product-repo` to a path in THIS checkout. An ABSOLUTE value is used as-is. A
+# RELATIVE value is written relative to the link.md's own directory (specs/<story>/) — the canonical
+# form — but contract-check historically read it from the repo root, so a link.md authored against that
+# reading still resolves: prefer the canonical join, fall back to the root-relative one when only it
+# exists. All four gates share this verbatim, so a value one gate can reach is reachable from every
+# gate (issue #149). An unexpanded ~ or $VAR is returned untouched, so it fails the reachability test
+# loudly instead of being joined into a nonsense path.
+resolve_product() {
+  case "$1" in
+    '') return ;;
+    /*|'~'*|'$'*) printf '%s' "$1" ;;
+    *) if [ -d "specs/$2/$1" ] || [ ! -d "$1" ]; then printf 'specs/%s/%s' "$2" "$1"; else printf '%s' "$1"; fi ;;
+  esac
+}
 
 # Thread ROOT of an epic: walk `parent:` to the genesis (no parent). COMPUTED — never trusts the
 # denormalized `thread:` cache, so a missing/wrong cache cannot bypass the freeze. Cycle-safe.
@@ -65,18 +95,20 @@ while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
   subject="$(git log -1 --format=%s "$sha")"
-  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  # The type exemption waives the REQUIREMENT for an owning epic, not the VALIDITY of one that is
+  # claimed — same rule spec-link applies. Exempting on the subject alone would let `chore(x): …` plus
+  # a Task trailer ship a change onto a thread that is frozen for open hotfix debt.
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: " && [ -z "$task" ]; then
     continue
   fi
-  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
   printf '%s' "$task" | grep -qE '.+-T[0-9]+$' || continue
   story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
   link="specs/${story}/link.md"
   [ -f "$link" ] || continue
-  product_rel="$(fm_val product-repo "$link")"
-  epic="$(fm_val epic "$link")"
-  # product-repo is relative to the link.md's directory (specs/<story>/), so join it there.
-  prod="specs/${story}/${product_rel}"
+  product_rel="$(link_val product-repo "$link")"
+  epic="$(link_val epic "$link")"
+  prod="$(resolve_product "$product_rel" "$story")"
   ep_dir="${prod}/epics/${epic}"
   if [ -z "$product_rel" ] || [ ! -d "$ep_dir" ]; then
     echo "PASS [reconcile-debt]: ${short} ${task} -> ${epic} (product repo not reachable — debt check deferred)."

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

@@ -3,8 +3,11 @@
 # Every NON-MAINTENANCE commit must link a real story/spec: it must carry a
 # `Task: <story>-<task>` trailer whose <story> resolves to a specs/<story>/link.md.
 # Maintenance commits (ci/chore/build/test) are EXEMPT — CI wiring, dependency bumps,
-# and test-infra changes legitimately link no story. Checked per commit (not aggregated
-# across the range), so the report names every offending commit.
+# and test-infra changes legitimately link no story. The exemption covers the ABSENCE of
+# a link, never a BROKEN one: a maintenance commit that carries a Task trailer is still
+# resolved, so `chore: x` + `Task: EP-ghost-S01-T01` fails exactly like any other commit
+# claiming a story that does not exist. Checked per commit (not aggregated across the
+# range), so the report names every offending commit.
 set -euo pipefail
 
 BASE="${1:-${SDLC_BASE:-origin/main}}"
@@ -32,11 +35,20 @@ while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
   subject="$(git log -1 --format=%s "$sha")"
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  exempt=0
+  note=''
   if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
-    echo "PASS [spec-link]: ${short} '${subject}' — maintenance commit (exempt)"
+    exempt=1
+    note=' (maintenance commit, trailer resolved anyway)'
+  fi
+  # The type exemption waives the REQUIREMENT for a link, not the VALIDITY of one that is claimed.
+  # Exempting on the subject alone left an unlinked `chore:` and a `chore:` naming a story that does
+  # not exist indistinguishable — both PASSed, so the trailer was decorative on every exempt commit.
+  if [ "$exempt" = 1 ] && [ -z "$task" ]; then
+    echo "PASS [spec-link]: ${short} '${subject}' — maintenance commit, no Task trailer (exempt)"
     continue
   fi
-  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
   if [ -z "$task" ]; then
     echo "FAIL [spec-link]: ${short} '${subject}' has no 'Task:' trailer"
     rc=1
@@ -52,7 +64,7 @@ while IFS= read -r sha; do
   fi
   story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
   if [ -f "specs/${story}/link.md" ]; then
-    echo "PASS [spec-link]: ${short} ${task} -> specs/${story}/link.md"
+    echo "PASS [spec-link]: ${short} ${task} -> specs/${story}/link.md${note}"
   else
     echo "FAIL [spec-link]: ${short} ${task} references specs/${story}/ but link.md is missing."
     rc=1