yadflow 4.6.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -25,7 +25,7 @@ product_config() {
25
25
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
26
26
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
27
27
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
28
- echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
28
+ echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
29
29
  return 1
30
30
  fi
31
31
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -65,7 +65,7 @@ BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
65
65
  # Fail CLOSED if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
66
66
  # Never let an undiffable range silently report "no surface change" — that would green-light a bypass.
67
67
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
68
- echo "FAIL [contract-check]: base ref '${BASE}' not found — fetch full history / check the base branch."
68
+ echo "FAIL [contract-check]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
69
69
  exit 1
70
70
  fi
71
71
  # Two readings (issue #363). The TRAILER, and the slice files the branch's own commits touch, are read
@@ -84,7 +84,7 @@ RANGE="${BASE}..HEAD"
84
84
  # closed. No merge base at all (a shallow clone, unrelated history) fails closed too.
85
85
  _mbs="$(git merge-base --all "$BASE" HEAD 2>/dev/null)" || _mbs=""
86
86
  if [ -z "$_mbs" ]; then
87
- echo "FAIL [contract-check]: '${BASE}' and HEAD share no history — fetch full history (a shallow clone has no merge base) or check the base branch."
87
+ echo "FAIL [contract-check]: '${BASE}' and HEAD share no history — a shallow clone has no merge base: check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), or give the branch this change targets as the base."
88
88
  exit 1
89
89
  fi
90
90
  _mb_count="$(printf '%s\n' "$_mbs" | wc -l | tr -d ' ')"
@@ -100,7 +100,7 @@ elif [ "$_mt" = 1 ]; then
100
100
  echo "FAIL [contract-check]: this branch does not merge cleanly into ${BASE}, so what it changes there cannot be read. Merge ${BASE} into the branch, resolve the conflicts, then push again."
101
101
  exit 1
102
102
  elif [ "$_mt" != 129 ]; then
103
- echo "FAIL [contract-check]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — fetch the full history of both, then run again."
103
+ echo "FAIL [contract-check]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
104
104
  exit 1
105
105
  elif [ "$_mb_count" != 1 ]; then
106
106
  echo "FAIL [contract-check]: '${BASE}' and HEAD have ${_mb_count} merge bases, and this git (older than 2.38) cannot build the merge into ${BASE}. Merge ${BASE} into the branch, then push again."
@@ -111,8 +111,8 @@ else
111
111
  # the rename into the merge unseen (review 4). Rename detection itself has limits the real merge does
112
112
  # not share (review 5: `diff.renameLimit`), so it is not used: a path the base REMOVED — deleted or
113
113
  # moved away — that the branch MODIFIES fails closed. Both deleting it is a clean merge, and passes.
114
- _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [contract-check]: git could not list what ${BASE} removed since the branch split off."; exit 1; }
115
- _mine="$(git diff --no-renames --name-status -z "$_mbs" HEAD | tr '\n\0' '?\n' | awk 'NR % 2 == 1 { s = $0; next } s == "M" || s == "T"')" || { echo "FAIL [contract-check]: git could not list what this branch changes."; exit 1; }
114
+ _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [contract-check]: git could not list what '${BASE}' removed since the branch split off — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again. Git 2.38 or newer on the runner builds the merge instead and skips this step."; exit 1; }
115
+ _mine="$(git diff --no-renames --name-status -z "$_mbs" HEAD | tr '\n\0' '?\n' | awk 'NR % 2 == 1 { s = $0; next } s == "M" || s == "T"')" || { echo "FAIL [contract-check]: git could not list what this branch changes since it split off from '${BASE}' — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again. Git 2.38 or newer on the runner builds the merge instead and skips this step."; exit 1; }
116
116
  # A here-string, not a pipe: `grep -q` stops at the first match, and a large list written into a pipe
117
117
  # it has left would end in SIGPIPE — read as "no match" under pipefail (review 5).
118
118
  if [ -n "$_gone" ] && [ -n "$_mine" ] && grep -Fxq -f <(printf '%s\n' "$_mine") <<<"$_gone"; then
@@ -171,7 +171,7 @@ links="$(git ls-tree -r -z --full-tree HEAD | tr '\n\0' '?\n' | awk '
171
171
  (fs in story) && story[fs] != c[2] { once("s/" c[2], "specs/" story[fs] (n == 2 ? " and specs/" c[2] " (one file" : "/ and specs/" c[2] "/ (one folder") " on macOS and Windows)") }
172
172
  !(fs in story) { story[fs] = c[2] }
173
173
  n >= 3 && c[3] != "contracts" && fold(c[3]) == "contracts" { once("c/" c[2] "/" c[3], "specs/" c[2] "/" c[3] (n == 3 ? " (a file" : "/ (a folder") " spelled other than contracts — the same name on macOS and Windows)") }
174
- ')" || { echo "FAIL [contract-check]: could not read the tree at HEAD — the links under specs/ cannot be checked."; exit 1; }
174
+ ')" || { echo "FAIL [contract-check]: git could not read the tree at HEAD, so the links under specs/ cannot be checked — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."; exit 1; }
175
175
  if [ -n "$links" ]; then
176
176
  echo "FAIL [contract-check]: specs/ holds a symlink, a submodule or a second spelling — this gate cannot see what it points at:"
177
177
  printf '%s\n' "$links"
@@ -296,7 +296,7 @@ record_path() {
296
296
  }
297
297
  product_for() {
298
298
  _link="specs/$1/link.md"
299
- prod=""; prod_note=""; prod_fail=""
299
+ prod=""; prod_note=""; prod_fail=""; _fix_where="product-repo in specs/$1/link.md"; _fix_when=""; _src="product-repo"; _fix_eg="../../.yad/product, from the story's folder"
300
300
  yad_tmp # here, in this shell: a $(…) below would set it, and its EXIT trap, in a subshell only
301
301
  product_rel="$(link_val product-repo "$_link")"
302
302
  _from="$_link"
@@ -349,6 +349,17 @@ SIBLINGS
349
349
  }${_link} names product-repo '${product_rel}', but ${_from} on ${BASE} says '${_base_rel}' — the Product is read from the base value; a new one counts once it merges."
350
350
  product_rel="$_base_rel"
351
351
  fi
352
+ # What a failure below tells the person to change (#351): the source that was read. Only on a first
353
+ # spec (the base names no Product) is it this PR's own link.md, which counts at once; anything else is
354
+ # read from the base, so a change to it counts only after it merges.
355
+ if [ -n "$_use_rec" ]; then
356
+ _src="path '${_rec}' in .sdlc/product-link.json"; _fix_eg=".yad/product, from the repo root"
357
+ _fix_where="path in .sdlc/product-link.json"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
358
+ elif [ -n "$_base_rel" ]; then
359
+ _fix_where="product-repo in ${_from}"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
360
+ else
361
+ _fix_where="product-repo in ${_link}"; _fix_when=" in this pull request"
362
+ fi
352
363
  # A Product this repo keeps, asked of the base first (see above). Both joins resolve_product may pick.
353
364
  case "$product_rel" in
354
365
  '') _cands="" ;;
@@ -378,7 +389,7 @@ CANDS
378
389
  case "$prod" in /*) _pc="$prod" ;; *) _pc="./$prod" ;; esac
379
390
  _phys="$(cd -P "$_pc" 2>/dev/null && pwd -P)" || _phys=""
380
391
  if [ -z "$_phys" ]; then
381
- prod_fail="product-repo resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read."
392
+ prod_fail="${_src} resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read. Point ${_fix_where} at a folder the job can read${_fix_when}."
382
393
  return 0
383
394
  fi
384
395
  # Not inside this repo's own git folder (review 7). git never lists `.git/` as tracked, yet a PR
@@ -391,7 +402,7 @@ CANDS
391
402
  _p="$_phys"
392
403
  while :; do
393
404
  if [ "$_p" -ef "$_gd" ]; then
394
- prod_fail="product-repo resolves to '${prod}', inside this repo's own git folder — what is there is git's, shaped by branch names, not a Product."
405
+ prod_fail="${_src} resolves to '${prod}', inside this repo's own git folder — what is there is git's, shaped by branch names, not a Product. Point ${_fix_where} at the Product checkout (${_fix_eg})${_fix_when}."
395
406
  return 0
396
407
  fi
397
408
  case "$_p" in /|'') break ;; esac
@@ -423,15 +434,18 @@ CANDS
423
434
  $_kept
424
435
  KEPT
425
436
  [ -n "$_kept_here" ] || return 0
426
- if [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
437
+ if [ -n "$_use_rec" ]; then _what="path '${_rec}' in .sdlc/product-link.json reaches nothing"
438
+ elif [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
427
439
  if [ "$(printf '%s' "$_kept_here" | grep -c .)" -gt 1 ]; then
428
- prod_fail="${_what}, and ${BASE} keeps more than one Product holding ${_epic_of} ($(printf '%s' "$_kept_here" | tr '\n' ' ' | sed -E 's/ +$//')) — the gate cannot tell which is meant."
440
+ prod_fail="${_what}, and ${BASE} keeps more than one Product holding ${_epic_of} ($(printf '%s' "$_kept_here" | tr '\n' ' ' | sed -E 's/ +$//')) — the gate cannot tell which is meant. Set ${_fix_where} to one of them${_fix_when}."
429
441
  return 0
430
442
  fi
431
443
  _k="$(printf '%s' "$_kept_here" | head -1)"
432
444
  prod_note="${prod_note:+$prod_note
433
445
  }${_what} here; the Product this repo keeps at '${_k}' on ${BASE} holds ${_epic_of}, so that one is read."
434
446
  product_rel="$_k"
447
+ # The value read did not resolve to it: the gate picked it. Say so in what base_product prints.
448
+ _src="${_what}, so the Product this repo keeps"
435
449
  [ "$_k" != . ] || _k=""
436
450
  base_product "$_k"
437
451
  return 0
@@ -443,12 +457,12 @@ KEPT
443
457
  tracked_verdict() {
444
458
  case "$1" in
445
459
  entry:*)
446
- prod_fail="product-repo reaches the Product through '${1#*:}', a symlink, submodule or file this repo tracks — what is behind it is this PR's to choose. Point product-repo at the Product itself."
460
+ prod_fail="${_src} reaches the Product through '${1#*:}', a symlink, submodule or file this repo tracks — what is behind it is this PR's to choose. Point ${_fix_where} at the Product itself${_fix_when}."
447
461
  return 0 ;;
448
462
  tree:*)
449
463
  _r="${1#*:}"
450
464
  if git cat-file -e "${BASE}:${_r:+$_r/}.sdlc/product.json" 2>/dev/null || git cat-file -e "${BASE}:${_r:+$_r/}.sdlc/hub.json" 2>/dev/null; then base_product "$_r"; return 0; fi
451
- prod_fail="product-repo resolves to '${_r:-.}', which holds files this repo tracks, but ${BASE} does not track '${_r:+$_r/}.sdlc/product.json' (or the older hub.json) there, so it is not a Product kept in this repo. Untrack those files (git rm -r --cached '${_r:-.}') or point product-repo at the Product."
465
+ prod_fail="${_src} resolves to '${_r:-.}', which holds files this repo tracks, but ${BASE} does not track '${_r:+$_r/}.sdlc/product.json' (or the older hub.json) there, so it is not a Product kept in this repo. Untrack those files (git rm -r --cached '${_r:-.}'), or point ${_fix_where} at the Product${_fix_when}."
452
466
  return 0 ;;
453
467
  esac
454
468
  return 1
@@ -481,7 +495,7 @@ KEPT
481
495
  base_product() {
482
496
  _r="$1"; _e="${_r:+$_r/}epics"
483
497
  if [ "$(git cat-file -t "${BASE}:${_e}" 2>/dev/null)" != tree ]; then
484
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and ${BASE} has no '${_e}' folder — there is nothing on the base to read."
498
+ prod_fail="${_src} resolves to '${_r:-.}', a Product this repo keeps, and ${BASE} has no '${_e}' folder — there is nothing on the base to read. Merge that Product's epics into ${BASE} first, or point ${_fix_where} at the Product checkout${_fix_when}."
485
499
  return 0
486
500
  fi
487
501
  # (awk reads to the end rather than stopping at the first hit: stopping left `tr` writing into a
@@ -510,7 +524,7 @@ base_product() {
510
524
  GIT_INDEX_FILE="${_arch_dir}.idx" git ls-files -z -- ':(glob)**/.gitattributes' |
511
525
  GIT_INDEX_FILE="${_arch_dir}.idx" xargs -0 git update-index --force-remove -- &&
512
526
  GIT_WORK_TREE="${_arch_dir}/${_e}" GIT_INDEX_FILE="${_arch_dir}.idx" git checkout-index -a -f; } >/dev/null 2>&1; then
513
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE}."
527
+ prod_fail="${_src} resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE} — run the job again; if it repeats, check the code out with full history and no partial-clone filter (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\")."
514
528
  return 0
515
529
  fi
516
530
  _arch_key="x$_r"
@@ -636,15 +650,15 @@ phys_dir() { (cd "$1" 2>/dev/null && pwd -P) || true; }
636
650
  quote_story() {
637
651
  _qs="$1"; _qbad=0; current=""
638
652
  if ! story_ok "$_qs"; then
639
- echo " ${_qs}: specs/${_qs}/contracts is not under a story ID — it quotes no lock."; return 1
653
+ echo " ${_qs}: specs/${_qs}/contracts is not under a story ID, so it quotes no lock — move it under its story's folder (specs/EP-<slug>-S<n>/contracts/) or delete it, and commit that with Contract-Change: yes (yad commit --contract-change): moving or removing slice files changes the surface, so it needs the trailer."; return 1
640
654
  fi
641
655
  _qp="specs/${_qs}/contracts" # a story ID holds no pattern character, so this pathspec is exact
642
656
  yad_tmp
643
- git diff --no-renames --diff-filter=D --name-only -z "$DIFF_FROM" "$DIFF_TO" -- "$_qp" > "$_yad_tmp/q-gone" || { echo " ${_qs}: git could not list the slice's deletions."; return 1; }
644
- { git diff --no-renames --diff-filter=d --name-only -z "$DIFF_FROM" "$DIFF_TO" -- "$_qp" && git log --full-history --no-merges --no-renames --format= --name-only -z "$RANGE" -- "$_qp"; } | sort -z -u > "$_yad_tmp/q-files" || { echo " ${_qs}: git could not list the slice's changes."; return 1; }
657
+ git diff --no-renames --diff-filter=D --name-only -z "$DIFF_FROM" "$DIFF_TO" -- "$_qp" > "$_yad_tmp/q-gone" || { echo " ${_qs}: git could not list the slice's deletions — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again; or, if the surface really changes, declare it (see below)."; return 1; }
658
+ { git diff --no-renames --diff-filter=d --name-only -z "$DIFF_FROM" "$DIFF_TO" -- "$_qp" && git log --full-history --no-merges --no-renames --format= --name-only -z "$RANGE" -- "$_qp"; } | sort -z -u > "$_yad_tmp/q-files" || { echo " ${_qs}: git could not list the slice's changes — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again; or, if the surface really changes, declare it (see below)."; return 1; }
645
659
  # Never a PASS by an empty list: the surface named this story, so its slice has changed files.
646
660
  if [ ! -s "$_yad_tmp/q-files" ] && [ ! -s "$_yad_tmp/q-gone" ]; then
647
- echo " ${_qs}: git listed no changed slice file for this story — the quote cannot be checked."; return 1
661
+ echo " ${_qs}: git listed no changed slice file for this story, so the quote cannot be checked — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again; or, if the surface really changes, declare it (see below)."; return 1
648
662
  fi
649
663
  if [ -s "$_yad_tmp/q-gone" ]; then
650
664
  tr '\n\0' '?\n' < "$_yad_tmp/q-gone" | while IFS= read -r _f; do echo " ${_f}: this removes slice file(s) — a deletion changes the surface."; done
@@ -673,12 +687,26 @@ quote_story() {
673
687
  _qepic="$(story_epic "$_qs")"
674
688
  _qlock=""
675
689
  [ -n "$prod" ] && _qlock="${prod}/epics/${_qepic}/.sdlc/contract-lock.json"
676
- if [ -z "$_qlock" ] || [ ! -f "$_qlock" ]; then
677
- echo " ${_qs}: cannot check ${_qs}'s slice against its lock — the Product's lock is not reachable at ${_qlock:-<no product-repo in ${_ql}>}."
690
+ # Three states, three fixes (#380): no Product reached here (no value, or a folder that is not there), a
691
+ # Product without the epic, or an epic without a lock.
692
+ if [ -z "$prod" ] || [ ! -d "$prod" ]; then
693
+ # On the repo's first spec (no value on the base, E119) the trailer does not help: CI must reach the
694
+ # Product either way (review 2).
695
+ _qor="; or, if the surface really changes, declare it (see below)"
696
+ [ -n "$_base_rel" ] || _qor="; this is the repo's first spec, so CI must reach the Product either way"
697
+ echo " ${_qs}: cannot check ${_qs}'s slice against its lock, because no Product is reached from ${_ql}${prod:+ (it reads '${prod}')} — let CI check the Product out (run yad check --fix --push from the Product, which writes .sdlc/product-link.json, and set the YAD_PRODUCT_TOKEN secret), then run again${_qor}."
698
+ return 1
699
+ fi
700
+ if [ ! -d "${prod}/epics/${_qepic}" ]; then
701
+ echo " ${_qs}: cannot check ${_qs}'s slice against its lock, because the Product has no ${_qepic} (${prod}/epics/) — if ${_qepic} is new, merge its Shape review PRs into the Product's default branch first; if the story id in the slice's folder name is wrong, rename the folder or delete the slice, and commit that with Contract-Change: yes (yad commit --contract-change): moving or removing slice files changes the surface, so it needs the trailer."
702
+ return 1
703
+ fi
704
+ if [ ! -f "$_qlock" ]; then
705
+ echo " ${_qs}: cannot check ${_qs}'s slice against its lock, because the Product holds no ${_qlock} — lock ${_qepic}'s contract upstream first (yad-architecture Step 5), then re-run yad-spec; an epic on a short lane (chore/spike) locks none, so delete the slice, and commit that with Contract-Change: yes (yad commit --contract-change): moving or removing slice files changes the surface, so it needs the trailer."
678
706
  return 1
679
707
  fi
680
708
  current="$(lock_hash "$_qlock")" || current=""
681
- if [ -z "$current" ]; then echo " ${_qs}: ${_qlock} has no readable \"hash\": \"sha256:…\" value."; return 1; fi
709
+ if [ -z "$current" ]; then echo " ${_qs}: ${_qlock} has no readable \"hash\": \"sha256:…\" value — lock the contract again upstream (yad-architecture Step 5), then run again."; return 1; fi
682
710
  if [ -z "$_qpin" ]; then
683
711
  echo " ${_qs}: ${_ql} names no contract-lock — re-run yad-spec, which copies it from the Product."; return 1
684
712
  fi
@@ -704,21 +732,21 @@ quote_story() {
704
732
  [ -n "$_qepics" ] || _qowner_sdlc=""
705
733
  case "$_qowner_sdlc" in
706
734
  "$_qepics"/*/.sdlc) ;;
707
- *) echo " ${_qs}: ${_qepic}'s pointer lock names '${_qref}', which is not another epic's lock in this Product."; return 1 ;;
735
+ *) echo " ${_qs}: ${_qepic}'s pointer lock names '${_qref}', which is not another epic's lock in this Product — fix ref (a path to the owner epic's .sdlc/contract-lock.json) or inheritedFrom (the owner epic's ID) in ${_qlock} (the yad-change skill writes them)."; return 1 ;;
708
736
  esac
709
737
  _qowner_lock="${_qowner_sdlc}/$(basename "$_qref")"
710
738
  if [ "$(basename "$_qref")" != "contract-lock.json" ] || [ ! -f "$_qowner_lock" ]; then
711
- echo " ${_qs}: ${_qepic}'s pointer lock names '${_qref}', and there is no lock there."; return 1
739
+ echo " ${_qs}: ${_qepic}'s pointer lock names '${_qref}', and there is no lock there — fix ref (a path to the owner epic's .sdlc/contract-lock.json) or inheritedFrom (the owner epic's ID) in ${_qlock} (the yad-change skill writes them)."; return 1
712
740
  fi
713
741
  if [ "$(lock_hash "$_qowner_lock")" != "$current" ]; then
714
742
  echo " ${_qs}: ${_qepic}'s pointer lock copies ${current:0:12}…, but its owner now locks another surface — re-copy the owner's hash (yad-change)."; return 1
715
743
  fi
716
744
  _qc="$(dirname "$_qowner_sdlc")/contract.md"
717
745
  fi
718
- if [ ! -f "$_qc" ]; then echo " ${_qs}: ${_qc} is not there — nothing to quote from."; return 1; fi
746
+ if [ ! -f "$_qc" ]; then echo " ${_qs}: ${_qc} is not there, so there is nothing to quote from — write that epic's contract.md in the Product and lock it (yad-architecture Step 5)."; return 1; fi
719
747
  surface_lines "$_qc" > "$_yad_tmp/surface"
720
748
  _qh="$(sha256_hex < "$_yad_tmp/surface")" || _qh=""
721
- if [ -z "$_qh" ]; then echo " ${_qs}: no sha256sum or shasum on this machine — the lock cannot be checked."; return 1; fi
749
+ if [ -z "$_qh" ]; then echo " ${_qs}: no sha256sum or shasum on this machine, so the lock cannot be checked — use a runner image with coreutils (sha256sum) or perl (shasum)."; return 1; fi
722
750
  if [ "$_qh" != "$current" ]; then
723
751
  echo " ${_qs}: the Product's contract.md no longer matches its lock (${_qh:0:12}… vs ${current:0:12}…) — re-lock it upstream (yad-architecture Step 5)."
724
752
  return 1
@@ -739,7 +767,7 @@ quote_story() {
739
767
  fi
740
768
  # A zero byte ends a line for some awks (macOS), so text after it was never compared (review 2).
741
769
  if ! tr -d '\000' < "$_yad_tmp/q-file" | cmp -s - "$_yad_tmp/q-file"; then
742
- echo " ${_f}: holds a zero byte — a slice is text; it is not read."; _qbad=1; continue
770
+ echo " ${_f}: holds a zero byte, and a slice is text, so it is not read — remove the zero byte, or re-run yad-spec, which writes the slice again."; _qbad=1; continue
743
771
  fi
744
772
  _qv="$(awk -v title="# Contract slice — ${_qs}" -v bom="$(printf '\357\273\277')" '
745
773
  function norm(x) { sub(/\r$/, "", x); sub(/[ \t]+$/, "", x); return x }
@@ -778,11 +806,11 @@ quote_story() {
778
806
  none) echo " ${_f}: has no CONTRACT-QUOTE block, so it cannot be told from a change."; _qbad=1 ;;
779
807
  count) echo " ${_f}: every CONTRACT-QUOTE block must be closed, BEGIN before END, none inside another."; _qbad=1 ;;
780
808
  many) echo " ${_f}: holds more than one CONTRACT-QUOTE block — one block per file; quote another part of the surface in another file."; _qbad=1 ;;
781
- empty) echo " ${_f}: a CONTRACT-QUOTE block quotes nothing."; _qbad=1 ;;
809
+ empty) echo " ${_f}: a CONTRACT-QUOTE block quotes nothing — re-run yad-spec, which writes the slice again."; _qbad=1 ;;
782
810
  outside*) echo " ${_f}: this line sits outside the CONTRACT-QUOTE block: ${_qv#outside?} — only blank lines and, first, the title '# Contract slice — ${_qs}' may; notes go in spec.md or plan.md."; _qbad=1 ;;
783
811
  miss*) echo " ${_f}: this line is not in the locked surface: ${_qv#miss?}"; _qbad=1 ;;
784
812
  run*) echo " ${_f}: the block starting '${_qv#run?}' is not one unbroken run of the locked surface, in its order — quote whole consecutive lines."; _qbad=1 ;;
785
- *) echo " ${_f}: could not be read."; _qbad=1 ;;
813
+ *) echo " ${_f}: could not be read — re-run yad-spec, which writes the slice again."; _qbad=1 ;;
786
814
  esac
787
815
  done < "$_yad_tmp/q-files"
788
816
  return "$_qbad"
@@ -828,8 +856,8 @@ QSTORIES
828
856
  echo " -> If it changes the surface: Route back to the architecture gate — update + re-lock contract.md"
829
857
  echo " in the product repo, or, if this epic is on a short lane (chore/spike) and has no architecture"
830
858
  echo " gate, move the surface change to a new epic on the classic route,"
831
- echo " re-run yad-spec, then implement with Contract-Change: yes. The surface is never widened"
832
- echo " from inside a code repo."
859
+ echo " re-run yad-spec, then implement with Contract-Change: yes (\`yad commit --contract-change\` adds"
860
+ echo " the trailer). The surface is never widened from inside a code repo."
833
861
  exit 1
834
862
  fi
835
863
  while IFS= read -r story; do
@@ -970,7 +998,7 @@ STORYSURF
970
998
  echo "note [contract-check]: ${story}'s slice belongs to ${epic}, which the Product does not have, and this only removes it — allowed."
971
999
  continue
972
1000
  fi
973
- echo "FAIL [contract-check]: ${story}'s slice belongs to ${epic}, which does not exist in the Product (${prod}/epics/) — an orphan slice."
1001
+ echo "FAIL [contract-check]: ${story}'s slice belongs to ${epic}, which does not exist in the Product (${prod}/epics/) — an orphan slice. Check the story id in the slice's folder name; if ${epic} is new, merge its Shape review PRs into the Product's default branch first. A PR that only deletes the slice passes."
974
1002
  rc=1
975
1003
  continue
976
1004
  elif [ -z "$_base_rel" ] && [ -z "$only_removes" ] && { [ -z "$prod" ] || [ ! -d "$prod" ]; }; then
@@ -28,7 +28,7 @@ product_config() {
28
28
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
29
29
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
30
30
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
31
- echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
31
+ echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
32
32
  return 1
33
33
  fi
34
34
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -61,7 +61,7 @@ BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
61
61
  [ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [epic-open]: no base given — diffing against '${BASE}'."
62
62
 
63
63
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
64
- echo "FAIL [epic-open]: base ref '${BASE}' not found — fetch full history / check the base branch."
64
+ echo "FAIL [epic-open]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
65
65
  exit 1
66
66
  fi
67
67
  RANGE="${BASE}..HEAD"
@@ -136,7 +136,7 @@ record_path() {
136
136
  }
137
137
  product_for() {
138
138
  _link="specs/$1/link.md"
139
- prod=""; prod_note=""; prod_fail=""
139
+ prod=""; prod_note=""; prod_fail=""; _fix_where="product-repo in specs/$1/link.md"; _fix_when=""; _src="product-repo"; _fix_eg="../../.yad/product, from the story's folder"
140
140
  yad_tmp # here, in this shell: a $(…) below would set it, and its EXIT trap, in a subshell only
141
141
  product_rel="$(link_val product-repo "$_link")"
142
142
  _from="$_link"
@@ -189,6 +189,17 @@ SIBLINGS
189
189
  }${_link} names product-repo '${product_rel}', but ${_from} on ${BASE} says '${_base_rel}' — the Product is read from the base value; a new one counts once it merges."
190
190
  product_rel="$_base_rel"
191
191
  fi
192
+ # What a failure below tells the person to change (#351): the source that was read. Only on a first
193
+ # spec (the base names no Product) is it this PR's own link.md, which counts at once; anything else is
194
+ # read from the base, so a change to it counts only after it merges.
195
+ if [ -n "$_use_rec" ]; then
196
+ _src="path '${_rec}' in .sdlc/product-link.json"; _fix_eg=".yad/product, from the repo root"
197
+ _fix_where="path in .sdlc/product-link.json"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
198
+ elif [ -n "$_base_rel" ]; then
199
+ _fix_where="product-repo in ${_from}"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
200
+ else
201
+ _fix_where="product-repo in ${_link}"; _fix_when=" in this pull request"
202
+ fi
192
203
  # A Product this repo keeps, asked of the base first (see above). Both joins resolve_product may pick.
193
204
  case "$product_rel" in
194
205
  '') _cands="" ;;
@@ -218,7 +229,7 @@ CANDS
218
229
  case "$prod" in /*) _pc="$prod" ;; *) _pc="./$prod" ;; esac
219
230
  _phys="$(cd -P "$_pc" 2>/dev/null && pwd -P)" || _phys=""
220
231
  if [ -z "$_phys" ]; then
221
- prod_fail="product-repo resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read."
232
+ prod_fail="${_src} resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read. Point ${_fix_where} at a folder the job can read${_fix_when}."
222
233
  return 0
223
234
  fi
224
235
  # Not inside this repo's own git folder (review 7). git never lists `.git/` as tracked, yet a PR
@@ -231,7 +242,7 @@ CANDS
231
242
  _p="$_phys"
232
243
  while :; do
233
244
  if [ "$_p" -ef "$_gd" ]; then
234
- prod_fail="product-repo resolves to '${prod}', inside this repo's own git folder — what is there is git's, shaped by branch names, not a Product."
245
+ prod_fail="${_src} resolves to '${prod}', inside this repo's own git folder — what is there is git's, shaped by branch names, not a Product. Point ${_fix_where} at the Product checkout (${_fix_eg})${_fix_when}."
235
246
  return 0
236
247
  fi
237
248
  case "$_p" in /|'') break ;; esac
@@ -263,15 +274,18 @@ CANDS
263
274
  $_kept
264
275
  KEPT
265
276
  [ -n "$_kept_here" ] || return 0
266
- if [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
277
+ if [ -n "$_use_rec" ]; then _what="path '${_rec}' in .sdlc/product-link.json reaches nothing"
278
+ elif [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
267
279
  if [ "$(printf '%s' "$_kept_here" | grep -c .)" -gt 1 ]; then
268
- prod_fail="${_what}, and ${BASE} keeps more than one Product holding ${_epic_of} ($(printf '%s' "$_kept_here" | tr '\n' ' ' | sed -E 's/ +$//')) — the gate cannot tell which is meant."
280
+ prod_fail="${_what}, and ${BASE} keeps more than one Product holding ${_epic_of} ($(printf '%s' "$_kept_here" | tr '\n' ' ' | sed -E 's/ +$//')) — the gate cannot tell which is meant. Set ${_fix_where} to one of them${_fix_when}."
269
281
  return 0
270
282
  fi
271
283
  _k="$(printf '%s' "$_kept_here" | head -1)"
272
284
  prod_note="${prod_note:+$prod_note
273
285
  }${_what} here; the Product this repo keeps at '${_k}' on ${BASE} holds ${_epic_of}, so that one is read."
274
286
  product_rel="$_k"
287
+ # The value read did not resolve to it: the gate picked it. Say so in what base_product prints.
288
+ _src="${_what}, so the Product this repo keeps"
275
289
  [ "$_k" != . ] || _k=""
276
290
  base_product "$_k"
277
291
  return 0
@@ -283,12 +297,12 @@ KEPT
283
297
  tracked_verdict() {
284
298
  case "$1" in
285
299
  entry:*)
286
- prod_fail="product-repo reaches the Product through '${1#*:}', a symlink, submodule or file this repo tracks — what is behind it is this PR's to choose. Point product-repo at the Product itself."
300
+ prod_fail="${_src} reaches the Product through '${1#*:}', a symlink, submodule or file this repo tracks — what is behind it is this PR's to choose. Point ${_fix_where} at the Product itself${_fix_when}."
287
301
  return 0 ;;
288
302
  tree:*)
289
303
  _r="${1#*:}"
290
304
  if git cat-file -e "${BASE}:${_r:+$_r/}.sdlc/product.json" 2>/dev/null || git cat-file -e "${BASE}:${_r:+$_r/}.sdlc/hub.json" 2>/dev/null; then base_product "$_r"; return 0; fi
291
- prod_fail="product-repo resolves to '${_r:-.}', which holds files this repo tracks, but ${BASE} does not track '${_r:+$_r/}.sdlc/product.json' (or the older hub.json) there, so it is not a Product kept in this repo. Untrack those files (git rm -r --cached '${_r:-.}') or point product-repo at the Product."
305
+ prod_fail="${_src} resolves to '${_r:-.}', which holds files this repo tracks, but ${BASE} does not track '${_r:+$_r/}.sdlc/product.json' (or the older hub.json) there, so it is not a Product kept in this repo. Untrack those files (git rm -r --cached '${_r:-.}'), or point ${_fix_where} at the Product${_fix_when}."
292
306
  return 0 ;;
293
307
  esac
294
308
  return 1
@@ -321,7 +335,7 @@ KEPT
321
335
  base_product() {
322
336
  _r="$1"; _e="${_r:+$_r/}epics"
323
337
  if [ "$(git cat-file -t "${BASE}:${_e}" 2>/dev/null)" != tree ]; then
324
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and ${BASE} has no '${_e}' folder — there is nothing on the base to read."
338
+ prod_fail="${_src} resolves to '${_r:-.}', a Product this repo keeps, and ${BASE} has no '${_e}' folder — there is nothing on the base to read. Merge that Product's epics into ${BASE} first, or point ${_fix_where} at the Product checkout${_fix_when}."
325
339
  return 0
326
340
  fi
327
341
  # (awk reads to the end rather than stopping at the first hit: stopping left `tr` writing into a
@@ -350,7 +364,7 @@ base_product() {
350
364
  GIT_INDEX_FILE="${_arch_dir}.idx" git ls-files -z -- ':(glob)**/.gitattributes' |
351
365
  GIT_INDEX_FILE="${_arch_dir}.idx" xargs -0 git update-index --force-remove -- &&
352
366
  GIT_WORK_TREE="${_arch_dir}/${_e}" GIT_INDEX_FILE="${_arch_dir}.idx" git checkout-index -a -f; } >/dev/null 2>&1; then
353
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE}."
367
+ prod_fail="${_src} resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE} — run the job again; if it repeats, check the code out with full history and no partial-clone filter (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\")."
354
368
  return 0
355
369
  fi
356
370
  _arch_key="x$_r"
@@ -459,6 +473,61 @@ epic_sealed() {
459
473
  return 0
460
474
  }
461
475
 
476
+ # --- shared SHA exemption (byte-identical in spec-link / lineage-check / epic-open / reconcile-debt-check;
477
+ # --- the gates are deliberately standalone, so it is duplicated, not sourced) ---
478
+ # A commit already on a shared branch cannot be reworded without rewriting that branch, so one bad trailer
479
+ # would fail every later PR whose range still holds it — and a release PR to the default branch walks the
480
+ # whole release, so it fails again on every release until that commit reaches the base. `.sdlc/gate-exempt`
481
+ # names such commits, one full SHA per line, `#` comments allowed; every per-commit gate passes
482
+ # them, so a commit is waived once, in a reviewed change, instead of on every pipeline. A listed commit
483
+ # skips EVERY check of the gate, not only its trailer's — a sealed epic or a frozen thread included. SDLC_GATE_EXEMPT
484
+ # names another path in the repo. It comes from the pipeline config, which a PR may change where the PR's
485
+ # own pipeline runs; it still names a file on the BASE whose every entry must be a full SHA, so it cannot
486
+ # list the PR's own commits — and a PR that changes the pipeline could drop the gates anyway, which
487
+ # required checks and branch protection, not this script, prevent. The list is read from the BASE, never from this PR — a PR that could
488
+ # list its own commits would wave itself past every gate; an entry counts once it merges. An entry must be
489
+ # a FULL hex SHA: git reads 40 hex characters (64 in a SHA-256 repo) as a commit, but looks a short one up as a tag or branch name
490
+ # first — so a tag named like a listed short SHA would stand in for another commit, and a short SHA also
491
+ # grows ambiguous as the repo grows. An entry that is not one, or names no commit here, exempts nothing;
492
+ # both are said as notes, so a typo is visible.
493
+ GATE_EXEMPT_FILE="${SDLC_GATE_EXEMPT:-.sdlc/gate-exempt}"
494
+ exempt_shas=''
495
+ load_exempt_shas() {
496
+ # Three dots: against the merge base, so a base that moved on is not mistaken for this PR's change.
497
+ # Only exit 1 means "it changed"; an error (no merge base) says nothing about the file.
498
+ _ex_rc=0
499
+ git diff --quiet "${BASE}...HEAD" -- "$GATE_EXEMPT_FILE" 2>/dev/null || _ex_rc=$?
500
+ if [ "$_ex_rc" -eq 1 ]; then
501
+ echo "note [$1]: ${GATE_EXEMPT_FILE} changes in this PR — the list is read from ${BASE}, not from this PR; the new one counts once it merges."
502
+ fi
503
+ git cat-file -e "${BASE}:${GATE_EXEMPT_FILE}" 2>/dev/null || return 0
504
+ _ex_list="$(git show "${BASE}:${GATE_EXEMPT_FILE}" 2>/dev/null | sed -E 's/#.*//; s/^[[:space:]]+//; s/[[:space:]]+$//')" || _ex_list=""
505
+ while IFS= read -r _ex; do
506
+ [ -z "$_ex" ] && continue
507
+ case "$_ex" in
508
+ *[!0123456789abcdef]*) echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not a lowercase hex SHA — it exempts nothing." ; continue ;;
509
+ esac
510
+ if [ "${#_ex}" -ne 40 ] && [ "${#_ex}" -ne 64 ]; then
511
+ echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not a full SHA (40 characters, or 64 in a SHA-256 repo) — it exempts nothing (a short one could be taken over by a tag or branch of that name)."
512
+ continue
513
+ fi
514
+ _ex_full="$(git rev-parse --verify --quiet "${_ex}^{commit}" 2>/dev/null)" || _ex_full=""
515
+ # Only an entry git reads back as exactly itself: hex of the other hash's length (64 in a SHA-1 repo,
516
+ # 40 in a SHA-256 one) is looked up as a tag or branch name first, so a ref of that name would stand in;
517
+ # and an annotated tag's own SHA peels to its commit's — the list names commits, as rev-list walks them.
518
+ if [ -z "$_ex_full" ] || [ "$_ex_full" != "$_ex" ]; then
519
+ echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not the full SHA of a commit here — it exempts nothing."
520
+ continue
521
+ fi
522
+ exempt_shas="${exempt_shas}${_ex_full}
523
+ "
524
+ done <<EXEMPT_LIST
525
+ $_ex_list
526
+ EXEMPT_LIST
527
+ }
528
+ is_exempt_sha() { [ -n "$exempt_shas" ] && printf '%s' "$exempt_shas" | grep -qxF "$1"; }
529
+ load_exempt_shas epic-open
530
+
462
531
  commits="$(git rev-list --no-merges "$RANGE")"
463
532
  if [ -z "$commits" ]; then
464
533
  echo "PASS [epic-open]: no non-merge commits in ${RANGE}"
@@ -471,6 +540,10 @@ while IFS= read -r sha; do
471
540
  short="$(git log -1 --format=%h "$sha")"
472
541
  subject="$(git log -1 --format=%s "$sha")"
473
542
  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | awk '!f && length($0) { print; f = 1 }')"
543
+ if is_exempt_sha "$sha"; then
544
+ echo "PASS [epic-open]: ${short} '${subject}' — SHA exemption (${GATE_EXEMPT_FILE} on ${BASE})"
545
+ continue
546
+ fi
474
547
  # The type exemption waives the REQUIREMENT for an owning epic, not the VALIDITY of one that is
475
548
  # claimed — same rule spec-link applies. Exempting on the subject alone would let `chore(x): …` plus
476
549
  # a Task trailer pointing at a SEALED epic add behaviour to it, which is exactly what this gate exists
@@ -496,7 +569,7 @@ while IFS= read -r sha; do
496
569
  # slip through as "not reachable" — an empty epic would collapse ep_dir to <product>/epics/ (a real
497
570
  # dir) and pass the seal check as if the epic were open.
498
571
  if ! printf '%s' "$epic" | grep -qE '^EP-[a-z0-9-]+$'; then
499
- echo "FAIL [epic-open]: ${short} ${task} — link.md has no valid product-repo/epic metadata."
572
+ echo "FAIL [epic-open]: ${short} ${task} — ${link} has no valid epic: value (EP-<slug>). Set epic: $(story_epic "$story") in it: a story's epic is the prefix of its id."
500
573
  rc=1
501
574
  continue
502
575
  fi
@@ -510,7 +583,7 @@ while IFS= read -r sha; do
510
583
  if [ -n "$prod_note" ]; then printf '%s\n' "$prod_note" | sed "s/^/note [epic-open]: ${short} /"; fi
511
584
  # The empty-product-repo half of the malformed check, on the value product_for settled on (E117).
512
585
  if [ -z "$product_rel" ]; then
513
- echo "FAIL [epic-open]: ${short} ${task} — link.md has no valid product-repo/epic metadata."
586
+ echo "FAIL [epic-open]: ${short} ${task} — ${link} names no product-repo, and no .sdlc/product-link.json on ${BASE} names the Product. Set product-repo in ${link} (the yad-spec skill writes it), or run \`yad check --fix --push\` from the Product to write the record into this repo."
514
587
  rc=1
515
588
  continue
516
589
  fi
@@ -525,7 +598,7 @@ while IFS= read -r sha; do
525
598
  continue
526
599
  fi
527
600
  if [ ! -d "$ep_dir" ]; then
528
- echo "FAIL [epic-open]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link)."
601
+ echo "FAIL [epic-open]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link). Check the story id in the Task trailer; if ${epic} is new, merge its Shape review PRs into the Product's default branch first."
529
602
  rc=1
530
603
  continue
531
604
  fi
@@ -62,7 +62,7 @@ product_config() {
62
62
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
63
63
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
64
64
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
65
- echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
65
+ echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
66
66
  return 1
67
67
  fi
68
68
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -166,7 +166,7 @@ resolve_base() {
166
166
  BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
167
167
  [ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [ledger-guard]: no base given — diffing against '${BASE}'."
168
168
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
169
- echo "FAIL [ledger-guard]: base ref '${BASE}' not found — fetch full history / check the base branch."
169
+ echo "FAIL [ledger-guard]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
170
170
  exit 1
171
171
  fi
172
172
  RANGE="${BASE}..HEAD"
@@ -358,7 +358,7 @@ for sha in $commits; do
358
358
  done
359
359
 
360
360
  if [ "$violations" -gt 0 ]; then
361
- echo "FAIL [ledger-guard]: ${violations} commit(s) change CI-owned gate files without a verified gate-bot signature. The ledger is CI-owned — let CI sync the gate; do not commit .sdlc/*.json or reviews/*.md yourself."
361
+ echo "FAIL [ledger-guard]: ${violations} commit(s) change CI-owned gate files without a verified gate-bot signature. The ledger is CI-owned — let CI sync the gate; do not commit .sdlc/*.json or reviews/*.md yourself. Every commit in the range is checked, so a new commit that undoes the change does not help: rewrite your own commits listed above (git rebase -i ${BASE}) so each leaves those files as ${BASE} has them, and force-push."
362
362
  if [ "${#overrides[@]}" -gt 0 ]; then
363
363
  echo "note [ledger-guard]: these commits carry a Ledger-Override trailer — the reason a person gave for committing past the local hook (\`yad commit --manual\` writes it). It is quoted for the reviewer and does not change the verdict:"
364
364
  printf '%s\n' "${overrides[@]}"