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
@@ -31,7 +31,7 @@ product_config() {
31
31
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
32
32
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
33
33
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
34
- 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
34
+ 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
35
35
  return 1
36
36
  fi
37
37
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -92,7 +92,7 @@ BASE="${ARGS[0]:-${SDLC_BASE:-$(resolve_base)}}"
92
92
 
93
93
  # Fail closed if the base ref can't be resolved (shallow clone / wrong base branch / unfetched ref).
94
94
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
95
- echo "FAIL [commit-message]: base ref '${BASE}' not found — fetch full history / check the base branch."
95
+ echo "FAIL [commit-message]: 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)."
96
96
  exit 1
97
97
  fi
98
98
  RANGE="${BASE}..HEAD"
@@ -142,4 +142,10 @@ done <<EOF
142
142
  $commits
143
143
  EOF
144
144
 
145
+ # Every failure above is fixed the same way: the commit is reworded, which rewrites it, so the branch is
146
+ # force-pushed. Said once, with the real base, after the list (#386).
147
+ if [ "$rc" -ne 0 ]; then
148
+ echo " -> Reword each commit listed above: \`git commit --amend\` for the last one, or \`git rebase -i ${BASE}\` (mark it 'reword') for an older one; then force-push the branch (\`git push --force-with-lease\`)."
149
+ fi
150
+
145
151
  exit "$rc"
@@ -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,10 +65,61 @@ 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
+ # Two readings (issue #363). The TRAILER, and the slice files the branch's own commits touch, are read
72
+ # from this branch's commits: `git log BASE..HEAD` (three dots in `log` would add the base's commits
73
+ # too). The CHANGE is what merging the branch into the base makes it — the block below.
71
74
  RANGE="${BASE}..HEAD"
75
+ # What this branch changes is what MERGING it into BASE would change (#363 reviews 1, 3 and 4). A diff
76
+ # from the base's TIP (two dots) blamed the branch for what the base did after it split off. A diff from
77
+ # the merge base missed two things the real merge does: with several merge bases it reads from ONE, so a
78
+ # hand-resolved merge could undo what the other side brought in (review 1); and the merge follows a
79
+ # RENAME on the base, so an edit to a file the base moved into a protected path lands there unseen
80
+ # (review 4). `git merge-tree --write-tree` (git 2.38+) builds the merge without touching anything, and
81
+ # the diff runs from BASE to it — what GitHub's own merge checkout gives. A branch that does not merge
82
+ # cleanly fails closed: the platform cannot merge it either. An older git falls back to the merge base,
83
+ # with one merge base only and no base-side rename of a file the branch changes; otherwise it fails
84
+ # closed. No merge base at all (a shallow clone, unrelated history) fails closed too.
85
+ _mbs="$(git merge-base --all "$BASE" HEAD 2>/dev/null)" || _mbs=""
86
+ if [ -z "$_mbs" ]; then
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
+ exit 1
89
+ fi
90
+ _mb_count="$(printf '%s\n' "$_mbs" | wc -l | tr -d ' ')"
91
+ # The exit code says which case this is (review 5): 0 a clean merge, 1 a conflict, 129 a git older than
92
+ # 2.38 (it does not know --write-tree), anything else git could not build it (a missing object, say).
93
+ _mt=0
94
+ _mt_out="$(git merge-tree --write-tree --no-messages "$BASE" HEAD 2>/dev/null)" || _mt=$?
95
+ DIFF_TO="${_mt_out%%$'\n'*}"
96
+ if [ "$_mt" = 0 ] && [ -n "$DIFF_TO" ] && git rev-parse --verify --quiet "${DIFF_TO}^{tree}" >/dev/null 2>&1; then
97
+ DIFF_FROM="$(git rev-parse --verify --quiet "${BASE}^{commit}")"
98
+ [ "$_mb_count" = 1 ] || echo "note [contract-check]: '${BASE}' and HEAD have ${_mb_count} merge bases — the change is read as the merge into ${BASE} makes it."
99
+ elif [ "$_mt" = 1 ]; then
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
+ exit 1
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}) — 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
+ exit 1
105
+ elif [ "$_mb_count" != 1 ]; then
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."
107
+ exit 1
108
+ else
109
+ DIFF_FROM="$_mbs"; DIFF_TO="HEAD"
110
+ # The fallback reads the branch's own diff, so an edit to a file the base has since moved would follow
111
+ # the rename into the merge unseen (review 4). Rename detection itself has limits the real merge does
112
+ # not share (review 5: `diff.renameLimit`), so it is not used: a path the base REMOVED — deleted or
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 — 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
+ # A here-string, not a pipe: `grep -q` stops at the first match, and a large list written into a pipe
117
+ # it has left would end in SIGPIPE — read as "no match" under pipefail (review 5).
118
+ if [ -n "$_gone" ] && [ -n "$_mine" ] && grep -Fxq -f <(printf '%s\n' "$_mine") <<<"$_gone"; then
119
+ echo "FAIL [contract-check]: ${BASE} removed or moved a file this branch changes, and this git (older than 2.38) cannot follow it into the merge. Merge ${BASE} into the branch, then push again."
120
+ exit 1
121
+ fi
122
+ fi
72
123
 
73
124
  # No symlink and no submodule anywhere under specs/ (E115). The gate reads PATHS: a link lets the
74
125
  # content live somewhere the paths below never name. A symlink at `specs`, `specs/<story>` or
@@ -120,7 +171,7 @@ links="$(git ls-tree -r -z --full-tree HEAD | tr '\n\0' '?\n' | awk '
120
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)") }
121
172
  !(fs in story) { story[fs] = c[2] }
122
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)") }
123
- ')" || { 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; }
124
175
  if [ -n "$links" ]; then
125
176
  echo "FAIL [contract-check]: specs/ holds a symlink, a submodule or a second spelling — this gate cannot see what it points at:"
126
177
  printf '%s\n' "$links"
@@ -144,25 +195,22 @@ fi
144
195
  # slice change and failed the PR over a file that does not exist.
145
196
  # Both lists (this one and `deleted` below) are built the SAME way: the no-lock escape hatch compares
146
197
  # them line for line.
147
- changed="$(git diff --no-renames --name-only -z "$RANGE" | tr '\n\0' '?\n')"
148
- surface="$(printf '%s\n' "$changed" | grep -E '^specs/[^/]+/contracts(/|$)' || true)"
198
+ changed="$(git diff --no-renames --name-only -z "$DIFF_FROM" "$DIFF_TO" | tr '\n\0' '?\n')"
199
+ # The slice files the branch's OWN commits touch count too, even when the merge nets them to nothing
200
+ # (review 5, the user's decision): a "Rebase and merge" replays each commit, so a commit that mirrors the
201
+ # base's re-lock and a later one that undoes it lands the undo, while the merge shows no change. The
202
+ # base's commits are not in this range, so a slice that changed only there is still not this branch's.
203
+ # `--full-history` (review 6): `git log -- <path>` otherwise simplifies history and drops a merged side's
204
+ # commits whose result matches the other parent — a slice edit there would replay in a rebase unseen.
205
+ own="$(git log --full-history --no-merges --no-renames --format= --name-only -z "$RANGE" -- specs | tr '\n\0' '?\n')"
206
+ surface="$(printf '%s\n%s\n' "$changed" "$own" | grep -E '^specs/[^/]+/contracts(/|$)' | sort -u || true)"
149
207
 
150
- # Slice paths this diff DELETES. `--name-only` above lists a deleted file exactly like a changed one,
151
- # which is right for the trailer rule — removing an agreed endpoint IS a surface change — but it
152
- # creates a dead end for the one epic that should never have had a slice in the first place.
153
- #
154
- # A short-lane epic has no lock and never will (E40). Once a `specs/<story>/contracts/` file exists
155
- # under one, the unflagged rule below fails the commit, the no-lock rule further down fails the
156
- # flagged one, and the cleanup commit that DELETES the file fails too — so there is no diff that
157
- # passes, including the correct one. An escape hatch is not optional there.
158
- #
159
- # Deleting your own copy of a surface that nothing upstream has locked cannot widen it: with no lock
160
- # there is no agreed shape for the deletion to contradict. So a delete-only diff is allowed through
161
- # the no-lock branch (and only that branch — where a lock EXISTS, a deletion is still a real surface
162
- # change and every rule below applies to it unchanged).
163
- # --no-renames matters here too: a slice MOVED out of contracts/ is a delete of the old path, and
164
- # without it git reports an `R`, which --diff-filter=D never matches — the hatch would refuse the move.
165
- deleted="$(git diff --no-renames --diff-filter=D --name-only -z "$RANGE" | tr '\n\0' '?\n' | grep -E '^specs/[^/]+/contracts(/|$)' || true)"
208
+ # A story that only REMOVES its slice is told apart below by what LANDS (review 6): every touched slice
209
+ # path is gone from the merge. A short-lane epic has no lock and never will (E40); once a
210
+ # `specs/<story>/contracts/` file exists under one, the unflagged rule fails the commit and the no-lock
211
+ # rule fails the flagged one — so deleting the file has to pass, or there is no way out. Deleting your
212
+ # own copy of a surface nothing upstream has locked cannot widen it. Where a lock EXISTS, a deletion is
213
+ # still a real surface change, and every rule below applies to it unchanged.
166
214
 
167
215
  if [ -z "$surface" ]; then
168
216
  echo "PASS [contract-check]: diff does not touch the contract surface (specs/*/contracts and everything under it)."
@@ -173,15 +221,11 @@ echo "note [contract-check]: diff touches the contract surface:"
173
221
  printf '%s\n' "$surface" | sed 's/^/ /'
174
222
 
175
223
  cc="$(git log "$RANGE" --format='%(trailers:key=Contract-Change,valueonly)' | sed '/^$/d' | tr 'A-Z' 'a-z')"
176
- if ! printf '%s\n' "$cc" | grep -qx 'yes'; then
177
- echo "FAIL [contract-check]: contract surface changed without a 'Contract-Change: yes' trailer."
178
- echo " -> Route back to the architecture gate: update + re-lock contract.md in the product repo,"
179
- echo " or, if this epic is on a short lane (chore/spike) and has no architecture gate, move the"
180
- echo " surface change to a new epic on the classic route,"
181
- echo " re-run yad-spec, then implement with Contract-Change: yes. The surface is never widened"
182
- echo " from inside a code repo."
183
- exit 1
184
- fi
224
+ # No trailer is not yet a FAIL (issue #344): a slice that only QUOTES the locked contract word for word
225
+ # changes nothing, and demanding `Contract-Change: yes` for it made the trailer mean nothing. The quote
226
+ # pass below (after the helpers it needs) decides; anything it cannot prove is the FAIL it always was.
227
+ no_trailer=""
228
+ printf '%s\n' "$cc" | grep -qx 'yes' || no_trailer=1
185
229
 
186
230
  # --- shared link.md resolution (byte-identical in contract-check / lineage-check / epic-open /
187
231
  # --- reconcile-debt-check; the gates are deliberately standalone, so it is duplicated, not sourced) ---
@@ -252,7 +296,7 @@ record_path() {
252
296
  }
253
297
  product_for() {
254
298
  _link="specs/$1/link.md"
255
- 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"
256
300
  yad_tmp # here, in this shell: a $(…) below would set it, and its EXIT trap, in a subshell only
257
301
  product_rel="$(link_val product-repo "$_link")"
258
302
  _from="$_link"
@@ -305,6 +349,17 @@ SIBLINGS
305
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."
306
350
  product_rel="$_base_rel"
307
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
308
363
  # A Product this repo keeps, asked of the base first (see above). Both joins resolve_product may pick.
309
364
  case "$product_rel" in
310
365
  '') _cands="" ;;
@@ -334,7 +389,7 @@ CANDS
334
389
  case "$prod" in /*) _pc="$prod" ;; *) _pc="./$prod" ;; esac
335
390
  _phys="$(cd -P "$_pc" 2>/dev/null && pwd -P)" || _phys=""
336
391
  if [ -z "$_phys" ]; then
337
- 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}."
338
393
  return 0
339
394
  fi
340
395
  # Not inside this repo's own git folder (review 7). git never lists `.git/` as tracked, yet a PR
@@ -347,7 +402,7 @@ CANDS
347
402
  _p="$_phys"
348
403
  while :; do
349
404
  if [ "$_p" -ef "$_gd" ]; then
350
- 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}."
351
406
  return 0
352
407
  fi
353
408
  case "$_p" in /|'') break ;; esac
@@ -379,15 +434,18 @@ CANDS
379
434
  $_kept
380
435
  KEPT
381
436
  [ -n "$_kept_here" ] || return 0
382
- 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
383
439
  if [ "$(printf '%s' "$_kept_here" | grep -c .)" -gt 1 ]; then
384
- 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}."
385
441
  return 0
386
442
  fi
387
443
  _k="$(printf '%s' "$_kept_here" | head -1)"
388
444
  prod_note="${prod_note:+$prod_note
389
445
  }${_what} here; the Product this repo keeps at '${_k}' on ${BASE} holds ${_epic_of}, so that one is read."
390
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"
391
449
  [ "$_k" != . ] || _k=""
392
450
  base_product "$_k"
393
451
  return 0
@@ -399,12 +457,12 @@ KEPT
399
457
  tracked_verdict() {
400
458
  case "$1" in
401
459
  entry:*)
402
- 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}."
403
461
  return 0 ;;
404
462
  tree:*)
405
463
  _r="${1#*:}"
406
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
407
- 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}."
408
466
  return 0 ;;
409
467
  esac
410
468
  return 1
@@ -437,7 +495,7 @@ KEPT
437
495
  base_product() {
438
496
  _r="$1"; _e="${_r:+$_r/}epics"
439
497
  if [ "$(git cat-file -t "${BASE}:${_e}" 2>/dev/null)" != tree ]; then
440
- 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}."
441
499
  return 0
442
500
  fi
443
501
  # (awk reads to the end rather than stopping at the first hit: stopping left `tr` writing into a
@@ -466,7 +524,7 @@ base_product() {
466
524
  GIT_INDEX_FILE="${_arch_dir}.idx" git ls-files -z -- ':(glob)**/.gitattributes' |
467
525
  GIT_INDEX_FILE="${_arch_dir}.idx" xargs -0 git update-index --force-remove -- &&
468
526
  GIT_WORK_TREE="${_arch_dir}/${_e}" GIT_INDEX_FILE="${_arch_dir}.idx" git checkout-index -a -f; } >/dev/null 2>&1; then
469
- 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\")."
470
528
  return 0
471
529
  fi
472
530
  _arch_key="x$_r"
@@ -559,6 +617,205 @@ resolve_product() {
559
617
  esac
560
618
  }
561
619
 
620
+ # The `"hash": "sha256:<hex>"` of a contract-lock.json, hex only. Newline-tolerant, first match: the key
621
+ # and its value may legally sit on separate lines. Empty when there is none (`|| true`: under `pipefail`
622
+ # a no-match grep would fail the pipeline).
623
+ lock_hash() { tr '\n' ' ' < "$1" | grep -oE '"hash"[[:space:]]*:[[:space:]]*"sha256:[0-9a-f]+"' | head -1 | sed -E 's/.*sha256:([0-9a-f]+)"$/\1/' || true; }
624
+ # One string value of a lock file ($2 = its key), the same newline-tolerant way. Empty when absent.
625
+ lock_str() { tr '\n' ' ' < "$1" | grep -oE "\"$2\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"$/\1/' || true; }
626
+
627
+ # The lines of a contract.md's CONTRACT-SURFACE block, as yadflow hashes them (contractSurfaceHash in
628
+ # cli/epic-state.mjs): a CR before the newline dropped, every line once with its newline.
629
+ surface_lines() { awk '{ sub(/\r$/, "") } /CONTRACT-SURFACE:BEGIN/ { f = 1; next } /CONTRACT-SURFACE:END/ { f = 0; next } f' "$1"; }
630
+ sha256_hex() {
631
+ if command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
632
+ elif command -v shasum >/dev/null 2>&1; then shasum -a 256 | cut -d' ' -f1
633
+ else return 1; fi
634
+ }
635
+ # The physical path of a folder, or nothing when it cannot be entered.
636
+ phys_dir() { (cd "$1" 2>/dev/null && pwd -P) || true; }
637
+
638
+ # Issue #344: is story $1's changed slice an exact quote of its locked contract? Says why not, one line
639
+ # per reason, and returns 1. Sets `current` (the lock's hash) for the caller's note.
640
+ #
641
+ # A slice file is a quote when it is Markdown, holds exactly ONE `<!-- CONTRACT-QUOTE:BEGIN -->` …
642
+ # `<!-- CONTRACT-QUOTE:END -->` block whose non-blank lines are one UNBROKEN, IN-ORDER run of the locked
643
+ # surface's non-blank lines, and holds nothing else but blank lines and, as its first non-blank line, the
644
+ # optional title `# Contract slice — <story ID>` (review 2: two blocks, each a run, could be stitched
645
+ # into a meaning the lock never had, and a free title could say anything; review 1: notes outside a
646
+ # block were never read, so a new endpoint written there passed; and
647
+ # lines checked one by one could be reordered into a different meaning). Its content is read from the
648
+ # commit by its exact name (review 1: a newline in a name, written as `?` in the list, opened a
649
+ # different file on disk), so a name holding a newline is refused.
650
+ quote_story() {
651
+ _qs="$1"; _qbad=0; current=""
652
+ if ! story_ok "$_qs"; then
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
654
+ fi
655
+ _qp="specs/${_qs}/contracts" # a story ID holds no pattern character, so this pathspec is exact
656
+ yad_tmp
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; }
659
+ # Never a PASS by an empty list: the surface named this story, so its slice has changed files.
660
+ if [ ! -s "$_yad_tmp/q-files" ] && [ ! -s "$_yad_tmp/q-gone" ]; then
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
662
+ fi
663
+ if [ -s "$_yad_tmp/q-gone" ]; then
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
665
+ return 1
666
+ fi
667
+ # When the branch's own commits touch the slice, a "Rebase and merge" replays them one by one, and what
668
+ # that lands is not the merge this gate reads (reviews 5 and 6: mirror-then-undo commits, and commits
669
+ # hidden behind a merge). The quote proof is exact only when the branch already holds the base and has
670
+ # no merge commits: then every merge method lands the branch tip, which IS the merge read below.
671
+ # Otherwise the trailer is needed — or a rebase onto the base.
672
+ if [ -n "$(git log --full-history --no-merges --format=%H "$RANGE" -- "$_qp")" ]; then
673
+ if ! git merge-base --is-ancestor "$BASE" HEAD 2>/dev/null || [ -n "$(git rev-list --merges "$RANGE")" ]; then
674
+ echo " ${_qs}: this branch's own commits change the slice, and it is not rebased onto ${BASE} (or holds merge commits) — a quote can be proven only on a branch rebased onto ${BASE}. Rebase it, then push again."
675
+ return 1
676
+ fi
677
+ fi
678
+ _ql="specs/${_qs}/link.md"
679
+ # The link.md that LANDS (review 5): the base may have re-pinned it since the branch split off.
680
+ if ! git cat-file blob "${DIFF_TO}:${_ql}" > "$_yad_tmp/q-link.md" 2>/dev/null; then
681
+ echo " ${_qs}: ${_ql} is not there, so the slice is tied to no lock — re-run yad-spec."; return 1
682
+ fi
683
+ _qpin="$(printf '%s' "$(link_val contract-lock "$_yad_tmp/q-link.md")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
684
+ product_for "$_qs"
685
+ if [ -n "$prod_note" ]; then printf '%s\n' "$prod_note" | sed 's/^/note [contract-check]: /'; fi
686
+ if [ -n "$prod_fail" ]; then echo " ${_qs}: ${prod_fail}"; return 1; fi
687
+ _qepic="$(story_epic "$_qs")"
688
+ _qlock=""
689
+ [ -n "$prod" ] && _qlock="${prod}/epics/${_qepic}/.sdlc/contract-lock.json"
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."
706
+ return 1
707
+ fi
708
+ current="$(lock_hash "$_qlock")" || current=""
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
710
+ if [ -z "$_qpin" ]; then
711
+ echo " ${_qs}: ${_ql} names no contract-lock — re-run yad-spec, which copies it from the Product."; return 1
712
+ fi
713
+ if [ "$_qpin" != "$current" ]; then
714
+ echo " ${_qs}: ${_ql} pins ${_qpin:0:12}…, not the current lock ${current:0:12}… — re-run yad-spec."
715
+ return 1
716
+ fi
717
+ # Where the locked text lives. A change-epic that inherits its architecture carries a POINTER lock
718
+ # (`inheritedFrom` / `ref`, yad-change) and no contract.md of its own: the surface is the owner's. Read
719
+ # it there, as `yad doctor` does — only inside this Product's epics/, and only when the owner's lock
720
+ # still holds the hash this one copied. An epic WITH its own contract.md re-authored its architecture
721
+ # and left the pointer fields behind: its own surface is read (review 2). `yad doctor` reads it too, and
722
+ # also still checks the pointer and warns about the leftover fields; the gate needs only the surface
723
+ # the quote is compared with, so it does not.
724
+ _qc="${prod}/epics/${_qepic}/contract.md"
725
+ _qref="$(lock_str "$_qlock" ref)"
726
+ _qfrom="$(lock_str "$_qlock" inheritedFrom)"
727
+ if [ ! -f "$_qc" ] && { [ -n "$_qref" ] || [ -n "$_qfrom" ]; }; then
728
+ [ -n "$_qref" ] || _qref="../../${_qfrom}/.sdlc/contract-lock.json"
729
+ _qepics="$(phys_dir "${prod}/epics")"
730
+ case "$_qref" in /*) _qrefp="$_qref" ;; *) _qrefp="${prod}/epics/${_qepic}/.sdlc/${_qref}" ;; esac
731
+ _qowner_sdlc="$(phys_dir "$(dirname "$_qrefp")")"
732
+ [ -n "$_qepics" ] || _qowner_sdlc=""
733
+ case "$_qowner_sdlc" in
734
+ "$_qepics"/*/.sdlc) ;;
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 ;;
736
+ esac
737
+ _qowner_lock="${_qowner_sdlc}/$(basename "$_qref")"
738
+ if [ "$(basename "$_qref")" != "contract-lock.json" ] || [ ! -f "$_qowner_lock" ]; then
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
740
+ fi
741
+ if [ "$(lock_hash "$_qowner_lock")" != "$current" ]; then
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
743
+ fi
744
+ _qc="$(dirname "$_qowner_sdlc")/contract.md"
745
+ 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
747
+ surface_lines "$_qc" > "$_yad_tmp/surface"
748
+ _qh="$(sha256_hex < "$_yad_tmp/surface")" || _qh=""
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
750
+ if [ "$_qh" != "$current" ]; then
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)."
752
+ return 1
753
+ fi
754
+ while IFS= read -r -d '' _f; do
755
+ [ -n "$_f" ] || continue # never a name; an empty record is skipped rather than read
756
+ case "$_f" in
757
+ *$'\n'*) echo " ${_f//$'\n'/?}: a slice file name holding a newline is not read — rename it."; _qbad=1; continue ;;
758
+ esac
759
+ case "$_f" in
760
+ *.md) ;;
761
+ *) echo " ${_f}: only a Markdown slice can pass as a quote; any other file under contracts/ needs the trailer."; _qbad=1; continue ;;
762
+ esac
763
+ # The content as it lands (the merge into the base; with the rule above, also the branch tip), by its
764
+ # exact name — never a file on disk that a folded name might point at.
765
+ if ! git cat-file blob "${DIFF_TO}:${_f}" > "$_yad_tmp/q-file" 2>/dev/null; then
766
+ echo " ${_f}: the branch's own commits touch it, but it is not in what lands (added and removed again?) — that needs the trailer."; _qbad=1; continue
767
+ fi
768
+ # A zero byte ends a line for some awks (macOS), so text after it was never compared (review 2).
769
+ if ! tr -d '\000' < "$_yad_tmp/q-file" | cmp -s - "$_yad_tmp/q-file"; then
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
771
+ fi
772
+ _qv="$(awk -v title="# Contract slice — ${_qs}" -v bom="$(printf '\357\273\277')" '
773
+ function norm(x) { sub(/\r$/, "", x); sub(/[ \t]+$/, "", x); return x }
774
+ FILENAME == ARGV[1] { $0 = norm($0); if ($0 != "") { surf = surf "\n" $0; s[$0] = 1 } next }
775
+ { if (FNR == 1 && index($0, bom) == 1) $0 = substr($0, length(bom) + 1); $0 = norm($0) }
776
+ $0 == "<!-- CONTRACT-QUOTE:BEGIN -->" { if (inb) bad = "nested"; inb = 1; blocks++; seen = 1; q = ""; qfirst = ""; next }
777
+ $0 == "<!-- CONTRACT-QUOTE:END -->" {
778
+ if (!inb) { bad = "order"; next }
779
+ inb = 0
780
+ if (q == "") { if (res == "") res = "empty"; next }
781
+ if (res == "" && index(surf "\n", q "\n") == 0) res = "run " qfirst
782
+ next
783
+ }
784
+ inb {
785
+ if ($0 == "") next
786
+ if (!($0 in s) && miss == "") miss = $0
787
+ if (qfirst == "") qfirst = $0
788
+ q = q "\n" $0
789
+ next
790
+ }
791
+ $0 == "" { next }
792
+ $0 == title && !seen { seen = 1; next }
793
+ { seen = 1 }
794
+ outside == "" { outside = $0 }
795
+ END {
796
+ if (bad != "" || inb) { print "count"; exit }
797
+ if (blocks == 0) { print "none"; exit }
798
+ if (blocks > 1) { print "many"; exit }
799
+ if (outside != "") { print "outside " outside; exit }
800
+ if (miss != "") { print "miss " miss; exit }
801
+ if (res != "") { print res; exit }
802
+ print "ok"
803
+ }' "$_yad_tmp/surface" - < "$_yad_tmp/q-file")" || _qv="unreadable"
804
+ case "$_qv" in
805
+ ok) ;;
806
+ none) echo " ${_f}: has no CONTRACT-QUOTE block, so it cannot be told from a change."; _qbad=1 ;;
807
+ count) echo " ${_f}: every CONTRACT-QUOTE block must be closed, BEGIN before END, none inside another."; _qbad=1 ;;
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 ;;
809
+ empty) echo " ${_f}: a CONTRACT-QUOTE block quotes nothing — re-run yad-spec, which writes the slice again."; _qbad=1 ;;
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 ;;
811
+ miss*) echo " ${_f}: this line is not in the locked surface: ${_qv#miss?}"; _qbad=1 ;;
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 ;;
813
+ *) echo " ${_f}: could not be read — re-run yad-spec, which writes the slice again."; _qbad=1 ;;
814
+ esac
815
+ done < "$_yad_tmp/q-files"
816
+ return "$_qbad"
817
+ }
818
+
562
819
  # Fidelity check (best-effort): when the product repo is reachable, the story's link.md must pin the
563
820
  # CURRENT product lock — proof the contract was actually updated/re-locked upstream, not just flagged.
564
821
  #
@@ -570,21 +827,70 @@ resolve_product() {
570
827
  # (the same rule spec-link applies per commit).
571
828
  stories="$(printf '%s\n' "$surface" | sed -E 's#^specs/([^/]+)/contracts(/.*)?$#\1#' | sort -u)"
572
829
  rc=0
830
+
831
+ # --- issue #344: with no trailer, pass only a slice that is an exact quote of its locked contract ---
832
+ # yad-spec writes the lines it copies from the locked CONTRACT-SURFACE block between
833
+ # `<!-- CONTRACT-QUOTE:BEGIN -->` and `<!-- CONTRACT-QUOTE:END -->`. What makes a slice a quote — and
834
+ # every rule reviews 1 and 2 added to keep a changed surface from passing as one — is said once, above
835
+ # `quote_story`. Anything it cannot prove is the trailer's FAIL, as before #344.
836
+ if [ -n "$no_trailer" ]; then
837
+ quote_ok=1
838
+ while IFS= read -r story; do
839
+ [ -z "$story" ] && continue
840
+ if quote_story "$story"; then
841
+ echo "note [contract-check]: ${story}'s slice is an exact quote of the locked contract (${current:0:12}…)."
842
+ else
843
+ quote_ok=""
844
+ fi
845
+ done <<QSTORIES
846
+ $stories
847
+ QSTORIES
848
+ if [ -n "$quote_ok" ]; then
849
+ echo "PASS [contract-check]: every changed slice is an exact quote of its locked contract — no Contract-Change trailer needed."
850
+ exit 0
851
+ fi
852
+ echo "FAIL [contract-check]: contract surface changed without a 'Contract-Change: yes' trailer."
853
+ echo " -> If the slice only QUOTES the locked contract: one Markdown file per unbroken run of the surface,"
854
+ echo " holding one <!-- CONTRACT-QUOTE:BEGIN --> … <!-- CONTRACT-QUOTE:END --> block and nothing else but"
855
+ echo " blank lines and the title '# Contract slice — <story ID>' (re-run yad-spec); fix what is listed above."
856
+ echo " -> If it changes the surface: Route back to the architecture gate — update + re-lock contract.md"
857
+ echo " in the product repo, or, if this epic is on a short lane (chore/spike) and has no architecture"
858
+ echo " gate, move the surface change to a new epic on the classic route,"
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."
861
+ exit 1
862
+ fi
573
863
  while IFS= read -r story; do
574
864
  [ -z "$story" ] && continue
575
865
  # This story's own changed and deleted slice paths, matched as text (a folder that is not a story ID
576
866
  # may hold characters a pattern would read; the prefix goes in through the environment, because
577
- # `awk -v` turns a `\b` in a folder name into a backspace). A story whose every changed slice file is
578
- # DELETED only removes (only_removes); one whose slice is also GONE at HEAD (slice_gone) is a whole
867
+ # `awk -v` turns a `\b` in a folder name into a backspace). A story whose every touched slice file is
868
+ # gone from what lands only removes (only_removes); one whose slice folder is also GONE (slice_gone) is a whole
579
869
  # clean-up, the only kind that needs no link.md — deleting link.md with PART of a slice used to drop
580
870
  # a stale pin while the rest of the slice stayed (E117 review 3).
581
871
  story_surface="$(printf '%s\n' "$surface" | p="specs/${story}/contracts" awk 'BEGIN { p = ENVIRON["p"] } index($0, p) == 1 && (length($0) == length(p) || substr($0, length(p) + 1, 1) == "/")')"
582
- story_deleted="$(printf '%s\n' "$deleted" | p="specs/${story}/contracts" awk 'BEGIN { p = ENVIRON["p"] } index($0, p) == 1 && (length($0) == length(p) || substr($0, length(p) + 1, 1) == "/")')"
872
+ # Only removes: every slice path the story touches is gone from what lands (review 6: a file added and
873
+ # removed again on the branch is in the surface but in no delete list). A folded name (`?`) cannot be
874
+ # looked up exactly, so it never counts as gone.
583
875
  only_removes=""
584
- [ -n "$story_surface" ] && [ "$story_surface" = "$story_deleted" ] && only_removes=1
876
+ if [ -n "$story_surface" ]; then
877
+ only_removes=1
878
+ while IFS= read -r _p; do
879
+ case "$_p" in *'?'*) only_removes=""; break ;; esac
880
+ if git cat-file -e "${DIFF_TO}:${_p}" 2>/dev/null; then only_removes=""; break; fi
881
+ done <<STORYSURF
882
+ $story_surface
883
+ STORYSURF
884
+ fi
585
885
  slice_gone=""
586
- if [ -n "$only_removes" ] && ! git cat-file -e "HEAD:specs/${story}/contracts" 2>/dev/null; then slice_gone=1; fi
886
+ # Gone from what LANDS (the merge into the base, review 4): a file the base adds beside the deletion
887
+ # would otherwise be a slice left with no link.md.
888
+ if [ -n "$only_removes" ] && ! git cat-file -e "${DIFF_TO}:specs/${story}/contracts" 2>/dev/null; then slice_gone=1; fi
587
889
  link="specs/${story}/link.md"
890
+ # The link.md that LANDS (review 6, the twin of the quote pass): the base may have re-pinned or removed it.
891
+ yad_tmp
892
+ landed_link=""
893
+ if git cat-file blob "${DIFF_TO}:${link}" > "$_yad_tmp/t-link.md" 2>/dev/null; then landed_link="$_yad_tmp/t-link.md"; fi
588
894
  if ! story_ok "$story"; then
589
895
  if [ -n "$only_removes" ]; then
590
896
  echo "note [contract-check]: specs/${story}/contracts is not under a story ID, and this only removes it — allowed."
@@ -595,7 +901,7 @@ while IFS= read -r story; do
595
901
  rc=1
596
902
  continue
597
903
  fi
598
- if [ ! -f "$link" ]; then
904
+ if [ -z "$landed_link" ]; then
599
905
  # Removing a story's whole slice with its link.md is a clean-up, as before. Adding or changing a
600
906
  # slice without its link.md is not (E117 review 2): yad-spec writes the two together, and a PR could
601
907
  # delete link.md to drop a stale pin, or add a slice for an epic that exists nowhere. Nor is removing
@@ -609,7 +915,7 @@ while IFS= read -r story; do
609
915
  rc=1
610
916
  continue
611
917
  fi
612
- pinned="$(printf '%s' "$(link_val contract-lock "$link")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
918
+ pinned="$(printf '%s' "$(link_val contract-lock "$landed_link")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
613
919
  epic="$(story_epic "$story")" # story EP-<slug>-S0N -> epic EP-<slug>
614
920
  product_for "$story"
615
921
  if [ -n "$prod_note" ]; then printf '%s\n' "$prod_note" | sed 's/^/note [contract-check]: /'; fi
@@ -628,7 +934,7 @@ while IFS= read -r story; do
628
934
  # unparseable lock is a FAIL below — so a formatting choice must not become a gate failure.
629
935
  # `|| current=""` is load-bearing: under `pipefail` a no-match grep fails the whole pipeline, which
630
936
  # under `set -e` would abort the gate instead of reaching the unparseable-lock FAIL below.
631
- current="$(tr '\n' ' ' < "$lock" | grep -oE '"hash"[[:space:]]*:[[:space:]]*"sha256:[0-9a-f]+"' | head -1 | sed -E 's/.*sha256:([0-9a-f]+)"$/\1/')" || current=""
937
+ current="$(lock_hash "$lock")" || current=""
632
938
  # A lock we can READ but cannot PARSE proves nothing, and an empty `current` used to short-circuit
633
939
  # the comparison below straight into the "hash matches" note — the gate affirmatively reporting a
634
940
  # match it never made. Fail closed instead: a truncated, half-written or schema-changed lock is a
@@ -692,7 +998,7 @@ while IFS= read -r story; do
692
998
  echo "note [contract-check]: ${story}'s slice belongs to ${epic}, which the Product does not have, and this only removes it — allowed."
693
999
  continue
694
1000
  fi
695
- 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."
696
1002
  rc=1
697
1003
  continue
698
1004
  elif [ -z "$_base_rel" ] && [ -z "$only_removes" ] && { [ -z "$prod" ] || [ ! -d "$prod" ]; }; then