yadflow 3.12.2 → 3.13.1

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