yadflow 4.5.2 → 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 (101) hide show
  1. package/CHANGELOG.md +206 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +174 -18
  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 +396 -123
  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 +442 -33
  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/lib.mjs +12 -1
  23. package/cli/lifecycle/defaults/1.json +96 -0
  24. package/cli/lifecycle/lifecycle.schema.json +121 -0
  25. package/cli/lifecycle.mjs +695 -0
  26. package/cli/next.mjs +34 -11
  27. package/cli/openpr.mjs +81 -5
  28. package/cli/platform.mjs +21 -0
  29. package/cli/pr-list.mjs +49 -3
  30. package/cli/product-index.mjs +6 -3
  31. package/cli/product-token.mjs +186 -0
  32. package/cli/productcommit.mjs +33 -0
  33. package/cli/recommend.mjs +3 -1
  34. package/cli/repo-publish.mjs +2 -2
  35. package/cli/run-checks.mjs +586 -0
  36. package/cli/ship-drift.mjs +384 -0
  37. package/cli/standup.mjs +1 -1
  38. package/cli/status.mjs +282 -0
  39. package/cli/test-build.mjs +1559 -0
  40. package/cli/test-run-checks.mjs +603 -0
  41. package/cli/test-worktree.mjs +520 -0
  42. package/cli/thread.mjs +50 -3
  43. package/cli/tidy.mjs +2 -2
  44. package/cli/toolbox.mjs +36 -5
  45. package/cli/workspace.mjs +4 -1
  46. package/cli/worktree-record.mjs +53 -0
  47. package/cli/worktree.mjs +379 -0
  48. package/package.json +4 -3
  49. package/skills/sdlc/config.yaml +28 -20
  50. package/skills/sdlc/module-help.csv +1 -1
  51. package/skills/yad-backfill/references/backfill.md +8 -1
  52. package/skills/yad-backfill/templates/checks/backfill-check.sh +54 -6
  53. package/skills/yad-change/SKILL.md +3 -0
  54. package/skills/yad-checks/SKILL.md +47 -5
  55. package/skills/yad-checks/references/check-gates.md +124 -12
  56. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  57. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  58. package/skills/yad-checks/templates/checks/contract-check.sh +354 -48
  59. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  60. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  61. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  62. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  63. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  64. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  65. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  66. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  67. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  68. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  69. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  70. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  71. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  72. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  73. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  74. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  75. package/skills/yad-commit/SKILL.md +4 -2
  76. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  77. package/skills/yad-docs/templates/app/package.json +2 -2
  78. package/skills/yad-engineer-review/SKILL.md +45 -20
  79. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  80. package/skills/yad-epic/references/state-schema.md +83 -20
  81. package/skills/yad-implement/SKILL.md +75 -13
  82. package/skills/yad-implement/references/implement-conventions.md +8 -1
  83. package/skills/yad-implement/templates/.gitmessage +3 -0
  84. package/skills/yad-open-pr/SKILL.md +21 -0
  85. package/skills/yad-pr-template/SKILL.md +6 -2
  86. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  87. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  88. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  89. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  90. package/skills/yad-product-bridge/SKILL.md +14 -1
  91. package/skills/yad-product-bridge/references/bridge.md +29 -5
  92. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  93. package/skills/yad-reconcile/SKILL.md +30 -0
  94. package/skills/yad-review-gate/SKILL.md +8 -2
  95. package/skills/yad-review-gate/references/gating.md +26 -1
  96. package/skills/yad-run/SKILL.md +52 -28
  97. package/skills/yad-run/references/run-loop.md +42 -21
  98. package/skills/yad-spec/SKILL.md +142 -17
  99. package/skills/yad-spec/references/spec-handoff.md +68 -5
  100. package/skills/yad-status/SKILL.md +7 -0
  101. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -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[@]}"
@@ -27,7 +27,7 @@ product_config() {
27
27
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
28
28
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
29
29
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
30
- 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
30
+ 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
31
31
  return 1
32
32
  fi
33
33
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -60,7 +60,7 @@ BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
60
60
  [ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [lineage-check]: no base given — diffing against '${BASE}'."
61
61
 
62
62
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
63
- echo "FAIL [lineage-check]: base ref '${BASE}' not found — fetch full history / check the base branch."
63
+ echo "FAIL [lineage-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)."
64
64
  exit 1
65
65
  fi
66
66
  RANGE="${BASE}..HEAD"
@@ -135,7 +135,7 @@ record_path() {
135
135
  }
136
136
  product_for() {
137
137
  _link="specs/$1/link.md"
138
- prod=""; prod_note=""; prod_fail=""
138
+ 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"
139
139
  yad_tmp # here, in this shell: a $(…) below would set it, and its EXIT trap, in a subshell only
140
140
  product_rel="$(link_val product-repo "$_link")"
141
141
  _from="$_link"
@@ -188,6 +188,17 @@ SIBLINGS
188
188
  }${_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."
189
189
  product_rel="$_base_rel"
190
190
  fi
191
+ # What a failure below tells the person to change (#351): the source that was read. Only on a first
192
+ # spec (the base names no Product) is it this PR's own link.md, which counts at once; anything else is
193
+ # read from the base, so a change to it counts only after it merges.
194
+ if [ -n "$_use_rec" ]; then
195
+ _src="path '${_rec}' in .sdlc/product-link.json"; _fix_eg=".yad/product, from the repo root"
196
+ _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"
197
+ elif [ -n "$_base_rel" ]; then
198
+ _fix_where="product-repo in ${_from}"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
199
+ else
200
+ _fix_where="product-repo in ${_link}"; _fix_when=" in this pull request"
201
+ fi
191
202
  # A Product this repo keeps, asked of the base first (see above). Both joins resolve_product may pick.
192
203
  case "$product_rel" in
193
204
  '') _cands="" ;;
@@ -217,7 +228,7 @@ CANDS
217
228
  case "$prod" in /*) _pc="$prod" ;; *) _pc="./$prod" ;; esac
218
229
  _phys="$(cd -P "$_pc" 2>/dev/null && pwd -P)" || _phys=""
219
230
  if [ -z "$_phys" ]; then
220
- prod_fail="product-repo resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read."
231
+ 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}."
221
232
  return 0
222
233
  fi
223
234
  # Not inside this repo's own git folder (review 7). git never lists `.git/` as tracked, yet a PR
@@ -230,7 +241,7 @@ CANDS
230
241
  _p="$_phys"
231
242
  while :; do
232
243
  if [ "$_p" -ef "$_gd" ]; then
233
- 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."
244
+ 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}."
234
245
  return 0
235
246
  fi
236
247
  case "$_p" in /|'') break ;; esac
@@ -262,15 +273,18 @@ CANDS
262
273
  $_kept
263
274
  KEPT
264
275
  [ -n "$_kept_here" ] || return 0
265
- if [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
276
+ if [ -n "$_use_rec" ]; then _what="path '${_rec}' in .sdlc/product-link.json reaches nothing"
277
+ elif [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
266
278
  if [ "$(printf '%s' "$_kept_here" | grep -c .)" -gt 1 ]; then
267
- 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."
279
+ 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}."
268
280
  return 0
269
281
  fi
270
282
  _k="$(printf '%s' "$_kept_here" | head -1)"
271
283
  prod_note="${prod_note:+$prod_note
272
284
  }${_what} here; the Product this repo keeps at '${_k}' on ${BASE} holds ${_epic_of}, so that one is read."
273
285
  product_rel="$_k"
286
+ # The value read did not resolve to it: the gate picked it. Say so in what base_product prints.
287
+ _src="${_what}, so the Product this repo keeps"
274
288
  [ "$_k" != . ] || _k=""
275
289
  base_product "$_k"
276
290
  return 0
@@ -282,12 +296,12 @@ KEPT
282
296
  tracked_verdict() {
283
297
  case "$1" in
284
298
  entry:*)
285
- 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."
299
+ 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}."
286
300
  return 0 ;;
287
301
  tree:*)
288
302
  _r="${1#*:}"
289
303
  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
290
- 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."
304
+ 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}."
291
305
  return 0 ;;
292
306
  esac
293
307
  return 1
@@ -320,7 +334,7 @@ KEPT
320
334
  base_product() {
321
335
  _r="$1"; _e="${_r:+$_r/}epics"
322
336
  if [ "$(git cat-file -t "${BASE}:${_e}" 2>/dev/null)" != tree ]; then
323
- 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."
337
+ 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}."
324
338
  return 0
325
339
  fi
326
340
  # (awk reads to the end rather than stopping at the first hit: stopping left `tr` writing into a
@@ -349,7 +363,7 @@ base_product() {
349
363
  GIT_INDEX_FILE="${_arch_dir}.idx" git ls-files -z -- ':(glob)**/.gitattributes' |
350
364
  GIT_INDEX_FILE="${_arch_dir}.idx" xargs -0 git update-index --force-remove -- &&
351
365
  GIT_WORK_TREE="${_arch_dir}/${_e}" GIT_INDEX_FILE="${_arch_dir}.idx" git checkout-index -a -f; } >/dev/null 2>&1; then
352
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE}."
366
+ 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\")."
353
367
  return 0
354
368
  fi
355
369
  _arch_key="x$_r"
@@ -442,6 +456,61 @@ resolve_product() {
442
456
  esac
443
457
  }
444
458
 
459
+ # --- shared SHA exemption (byte-identical in spec-link / lineage-check / epic-open / reconcile-debt-check;
460
+ # --- the gates are deliberately standalone, so it is duplicated, not sourced) ---
461
+ # A commit already on a shared branch cannot be reworded without rewriting that branch, so one bad trailer
462
+ # would fail every later PR whose range still holds it — and a release PR to the default branch walks the
463
+ # whole release, so it fails again on every release until that commit reaches the base. `.sdlc/gate-exempt`
464
+ # names such commits, one full SHA per line, `#` comments allowed; every per-commit gate passes
465
+ # them, so a commit is waived once, in a reviewed change, instead of on every pipeline. A listed commit
466
+ # skips EVERY check of the gate, not only its trailer's — a sealed epic or a frozen thread included. SDLC_GATE_EXEMPT
467
+ # names another path in the repo. It comes from the pipeline config, which a PR may change where the PR's
468
+ # own pipeline runs; it still names a file on the BASE whose every entry must be a full SHA, so it cannot
469
+ # list the PR's own commits — and a PR that changes the pipeline could drop the gates anyway, which
470
+ # required checks and branch protection, not this script, prevent. The list is read from the BASE, never from this PR — a PR that could
471
+ # list its own commits would wave itself past every gate; an entry counts once it merges. An entry must be
472
+ # 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
473
+ # first — so a tag named like a listed short SHA would stand in for another commit, and a short SHA also
474
+ # grows ambiguous as the repo grows. An entry that is not one, or names no commit here, exempts nothing;
475
+ # both are said as notes, so a typo is visible.
476
+ GATE_EXEMPT_FILE="${SDLC_GATE_EXEMPT:-.sdlc/gate-exempt}"
477
+ exempt_shas=''
478
+ load_exempt_shas() {
479
+ # Three dots: against the merge base, so a base that moved on is not mistaken for this PR's change.
480
+ # Only exit 1 means "it changed"; an error (no merge base) says nothing about the file.
481
+ _ex_rc=0
482
+ git diff --quiet "${BASE}...HEAD" -- "$GATE_EXEMPT_FILE" 2>/dev/null || _ex_rc=$?
483
+ if [ "$_ex_rc" -eq 1 ]; then
484
+ 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."
485
+ fi
486
+ git cat-file -e "${BASE}:${GATE_EXEMPT_FILE}" 2>/dev/null || return 0
487
+ _ex_list="$(git show "${BASE}:${GATE_EXEMPT_FILE}" 2>/dev/null | sed -E 's/#.*//; s/^[[:space:]]+//; s/[[:space:]]+$//')" || _ex_list=""
488
+ while IFS= read -r _ex; do
489
+ [ -z "$_ex" ] && continue
490
+ case "$_ex" in
491
+ *[!0123456789abcdef]*) echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not a lowercase hex SHA — it exempts nothing." ; continue ;;
492
+ esac
493
+ if [ "${#_ex}" -ne 40 ] && [ "${#_ex}" -ne 64 ]; then
494
+ 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)."
495
+ continue
496
+ fi
497
+ _ex_full="$(git rev-parse --verify --quiet "${_ex}^{commit}" 2>/dev/null)" || _ex_full=""
498
+ # Only an entry git reads back as exactly itself: hex of the other hash's length (64 in a SHA-1 repo,
499
+ # 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;
500
+ # and an annotated tag's own SHA peels to its commit's — the list names commits, as rev-list walks them.
501
+ if [ -z "$_ex_full" ] || [ "$_ex_full" != "$_ex" ]; then
502
+ echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not the full SHA of a commit here — it exempts nothing."
503
+ continue
504
+ fi
505
+ exempt_shas="${exempt_shas}${_ex_full}
506
+ "
507
+ done <<EXEMPT_LIST
508
+ $_ex_list
509
+ EXEMPT_LIST
510
+ }
511
+ is_exempt_sha() { [ -n "$exempt_shas" ] && printf '%s' "$exempt_shas" | grep -qxF "$1"; }
512
+ load_exempt_shas lineage-check
513
+
445
514
  commits="$(git rev-list --no-merges "$RANGE")"
446
515
  if [ -z "$commits" ]; then
447
516
  echo "PASS [lineage-check]: no non-merge commits in ${RANGE}"
@@ -454,6 +523,10 @@ while IFS= read -r sha; do
454
523
  short="$(git log -1 --format=%h "$sha")"
455
524
  subject="$(git log -1 --format=%s "$sha")"
456
525
  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | awk '!f && length($0) { print; f = 1 }')"
526
+ if is_exempt_sha "$sha"; then
527
+ echo "PASS [lineage-check]: ${short} '${subject}' — SHA exemption (${GATE_EXEMPT_FILE} on ${BASE})"
528
+ continue
529
+ fi
457
530
  # The type exemption waives the REQUIREMENT for an owning epic, not the VALIDITY of one that is
458
531
  # claimed — same rule spec-link applies. Exempting on the subject alone would let `chore(x): …` plus
459
532
  # a Task trailer pointing at an orphaned/sealed epic bypass this gate entirely.
@@ -479,7 +552,7 @@ while IFS= read -r sha; do
479
552
  fi
480
553
  epic="$(link_val epic "$link")"
481
554
  if [ -z "$epic" ]; then
482
- echo "FAIL [lineage-check]: ${short} ${task} — link.md has no 'epic:' (cannot place it in a thread)."
555
+ echo "FAIL [lineage-check]: ${short} ${task} — ${link} has no 'epic:' (cannot place it in a thread). Set epic: $(story_epic "$story") in it: a story's epic is the prefix of its id."
483
556
  rc=1
484
557
  continue
485
558
  fi
@@ -504,7 +577,7 @@ while IFS= read -r sha; do
504
577
  continue
505
578
  fi
506
579
  if [ ! -f "$epicmd" ]; then
507
- echo "FAIL [lineage-check]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link)."
580
+ echo "FAIL [lineage-check]: ${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."
508
581
  rc=1
509
582
  continue
510
583
  fi
@@ -531,12 +604,12 @@ while IFS= read -r sha; do
531
604
  # A change/defect/hotfix epic MUST thread to a real parent.
532
605
  parent="$(fm_val parent "$epicmd")"
533
606
  if [ -z "$parent" ]; then
534
- echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is type:${wtype} but declares no 'parent:' — a change-epic must thread to its predecessor."
607
+ echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is type:${wtype} but declares no 'parent:' — a change-epic must thread to its predecessor. Add parent: <the epic it changes> to epics/${epic}/epic.md in the Product, through its review PR (the yad-change skill writes it); \`yad thread\` lists the threads."
535
608
  rc=1
536
609
  continue
537
610
  fi
538
611
  if [ ! -f "${prod}/epics/${parent}/epic.md" ]; then
539
- echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the Product (orphan thread)."
612
+ echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the Product (orphan thread). Fix parent: in epics/${epic}/epic.md to an epic the Product has, or merge ${parent}'s Shape review PRs into the Product's default branch first."
540
613
  rc=1
541
614
  continue
542
615
  fi