yadflow 4.6.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -24,7 +24,7 @@ product_config() {
24
24
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
25
25
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
26
26
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
27
- 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
27
+ 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
28
28
  return 1
29
29
  fi
30
30
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -61,7 +61,7 @@ resolve_base() {
61
61
  BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
62
62
  [ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [backfill]: no base given — diffing against '${BASE}'."
63
63
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
64
- echo "FAIL [backfill]: base ref '${BASE}' not found — fetch full history / check the base branch."
64
+ echo "FAIL [backfill]: 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
  # What this branch changes is what MERGING it into BASE would change (#363 reviews 1, 3 and 4). A diff
@@ -76,7 +76,7 @@ fi
76
76
  # closed. No merge base at all (a shallow clone, unrelated history) fails closed too.
77
77
  _mbs="$(git merge-base --all "$BASE" HEAD 2>/dev/null)" || _mbs=""
78
78
  if [ -z "$_mbs" ]; then
79
- echo "FAIL [backfill]: '${BASE}' and HEAD share no history — fetch full history (a shallow clone has no merge base) or check the base branch."
79
+ echo "FAIL [backfill]: '${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."
80
80
  exit 1
81
81
  fi
82
82
  _mb_count="$(printf '%s\n' "$_mbs" | wc -l | tr -d ' ')"
@@ -92,7 +92,7 @@ elif [ "$_mt" = 1 ]; then
92
92
  echo "FAIL [backfill]: 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."
93
93
  exit 1
94
94
  elif [ "$_mt" != 129 ]; then
95
- echo "FAIL [backfill]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — fetch the full history of both, then run again."
95
+ echo "FAIL [backfill]: 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."
96
96
  exit 1
97
97
  elif [ "$_mb_count" != 1 ]; then
98
98
  echo "FAIL [backfill]: '${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."
@@ -103,8 +103,8 @@ else
103
103
  # the rename into the merge unseen (review 4). Rename detection itself has limits the real merge does
104
104
  # not share (review 5: `diff.renameLimit`), so it is not used: a path the base REMOVED — deleted or
105
105
  # moved away — that the branch MODIFIES fails closed. Both deleting it is a clean merge, and passes.
106
- _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [backfill]: git could not list what ${BASE} removed since the branch split off."; exit 1; }
107
- _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 [backfill]: git could not list what this branch changes."; exit 1; }
106
+ _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [backfill]: 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; }
107
+ _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 [backfill]: 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; }
108
108
  # A here-string, not a pipe: `grep -q` stops at the first match, and a large list written into a pipe
109
109
  # it has left would end in SIGPIPE — read as "no match" under pipefail (review 5).
110
110
  if [ -n "$_gone" ] && [ -n "$_mine" ] && grep -Fxq -f <(printf '%s\n' "$_mine") <<<"$_gone"; then
@@ -140,7 +140,7 @@ FOLD='function fold(x) { x = tolower(x)
140
140
  # `tr '\n\0' '?\n'`: one record per line, and a newline inside a path becomes `?` — split on newlines
141
141
  # alone, a file named `notes<newline>100644 blob 0<TAB>src/Billing/y` added a record nobody made (review 2).
142
142
  base_tree="$(git ls-tree -r -z --full-tree "$BASE" | tr '\n\0' '?\n')" || {
143
- echo "FAIL [backfill]: git could not read the tree of '${BASE}' — the gate cannot tell which features are being backfilled."
143
+ echo "FAIL [backfill]: git could not read the tree of '${BASE}', so the gate cannot tell which features are being backfilled — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
144
144
  exit 1
145
145
  }
146
146
  # One line each: `S <oid> <path>` a spec to read, `U - <path>` a link where a spec goes, `A - <path>` a
@@ -173,7 +173,7 @@ bf="$(printf '%s\n' "$specs" | sed -n 's/^[SU] [^ ]* //p' | awk "$FOLD"'{ split(
173
173
  # empty.
174
174
  tagged() { printf '%s\n' "$2" | awk -v t="$1" 'length($0) { print t "\t" $0 }'; }
175
175
  head_tree="$(git ls-tree -r -z --full-tree HEAD | tr '\n\0' '?\n')" || {
176
- echo "FAIL [backfill]: git could not read the tree at HEAD — the gate cannot check src/ for links."
176
+ echo "FAIL [backfill]: git could not read the tree at HEAD, so the gate cannot check src/ for links — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
177
177
  exit 1
178
178
  }
179
179
  if [ -n "$bf" ] || [ -n "$blind" ]; then
@@ -218,7 +218,7 @@ fi
218
218
  changed="$(git diff --no-renames --raw -z "$DIFF_FROM" "$DIFF_TO" | while IFS= read -r -d '' h && IFS= read -r -d '' p; do
219
219
  printf '%s\t%s\n' "$h" "${p//$'\n'/?}"
220
220
  done)" || {
221
- echo "FAIL [backfill]: git could not list what this branch changes in '${BASE}'."
221
+ echo "FAIL [backfill]: git could not list what this branch changes in '${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."
222
222
  exit 1
223
223
  }
224
224
  # The spellings of each src/<feature> folder, on the base and at HEAD: `<top>/<feature>`, once each.
@@ -257,6 +257,9 @@ again. Unbound, that command names `yad-architecture` for a contract-surface cha
257
257
  ## Hard rules
258
258
 
259
259
  - **Never mutate a locked artifact.** A change is a new threaded epic, not an edit to a shipped one.
260
+ The one exception is BEFORE Build begins — no story has a Build lane and nothing has shipped: then
261
+ reopen the approved step with `yad gate reopen <epic> <step> --reason "<why>"` (#322) instead of
262
+ threading a change epic; every gate from that step is approved again.
260
263
  - **A change MUST thread to a real parent.** Validate the parent + thread first; STOP on a broken lineage.
261
264
  - **Inherit by reference, never copy.** `yad epic new --parent` carries inherited steps as `satisfied` with
262
265
  `inherited: true` + a `boundHash`; the pointer-lock carries the owner's hash verbatim. The gate never
@@ -38,6 +38,8 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
38
38
  Product lives is a repo fact once `yad check --fix --push` has merged `.sdlc/product-link.json` into
39
39
  the code repo (E120): the gates read it from the base first, and `checks/product-checkout.sh` clones
40
40
  the Product there in CI when the `YAD_PRODUCT_TOKEN` secret is set (see `references/check-gates.md`).
41
+ A missing token on a PR that is not from a fork is a `WARNING` in CI, and a token that expires within
42
+ 30 days is warned about there too (#345); `yad doctor` reports where each code repo's CI gets it.
41
43
  3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
42
44
  CI installs and runs through the package manager declared by the repo's standard
43
45
  `package.json#packageManager` field (`npm` and `pnpm` are supported; any other manager stays on
@@ -80,7 +82,7 @@ from CI. `product-repo` is read from the base, a Product this repo tracks is rea
80
82
  `epic:` must be the story ID's prefix — the PR cannot choose what is gated (E117, E118). See `references/check-gates.md` and `skills/yad-change`.
81
83
 
82
84
  The gates are **CI-agnostic bash** in `checks/`; thin pipeline configs invoke them on GitHub Actions
83
- and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill or let CI run them;
85
+ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill (`yad run checks`) or let CI run them;
84
86
  **nothing auto-advances**. The gates are blocking in CI (all but the advisory risk-map check), but the human still owns the merge (Step E).
85
87
 
86
88
  ## Conventions
@@ -192,12 +194,34 @@ Copy from this skill's `templates/`:
192
194
  - The legacy standalone `templates/gitlab/.gitlab-ci.yml` is retained only for a clean greenfield repo
193
195
  that prefers a single self-contained file; the include path above is the default.
194
196
  - **Tag-locked runners** (`run_untagged: false`, common on self-hosted): the fragment's jobs run a
195
- docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them — the
196
- `default:` block emits `tags: [$YAD_RUNNER_TAGS]`. When unset, current GitLab (≥15) drops the
197
+ docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them — every
198
+ GitLab fragment's jobs carry `tags: [$YAD_RUNNER_TAGS]`. When unset, current GitLab (≥15) drops the
197
199
  empty-expanded tag so the jobs run untagged (gitlab.com shared runners); older versions may
198
200
  strand them `pending`, in which case set the variable to a real tag. The variable lives in
199
201
  project settings, so it survives every `yad` sync. Single value only — `tags: [$VAR]` is one tag
200
- equal to the whole variable, not a comma-split.
202
+ equal to the whole variable, not a comma-split. Leave **Protect variable** unticked on both
203
+ variables below: a protected variable reaches only pipelines on protected branches, so the MR
204
+ gates would run without it — untagged and on the default Node line.
205
+ - **The Node line** (#364): every GitLab job runs `image: node:${YAD_NODE_VERSION}`, `22` by default.
206
+ Set a `YAD_NODE_VERSION` CI/CD variable (a current `20`, `22` or `24` line) to change it — a
207
+ project variable wins over the fragment's value, so the fragment itself is never edited.
208
+ - **Shell-executor runners** ignore `image:`. The jobs then run on the runner host as they are, so
209
+ the host needs `bash`, `git`, `curl` (the signature gates read the GitLab API with it; without it
210
+ every commit reads as unverified) and Node (any current 20, 22 or 24 line — for example from nvm)
211
+ on the runner user's `PATH`, plus whatever the repo's own build needs (Corepack, pnpm, …) for
212
+ `build-test-lint`. `YAD_NODE_VERSION` has no effect there. Point `YAD_RUNNER_TAGS` at that
213
+ runner's tag.
214
+ - **Do not hand-edit the fragments to fit a runner.** They are managed bytes: `yad check` reports a
215
+ hand-edited one as `modified`, and a plain `yad update` leaves it alone — so it never receives a
216
+ fix again. Both runner settings above are CI/CD variables, so no edit is needed: move the
217
+ customisation into them, then run `yad update --overwrite-local` to restore the fragment (it keeps
218
+ a `.yad-orig` copy of the edited one first). `yad doctor` warns when a wired
219
+ fragment has no `tags:` (`YAD-CI-001`) or still runs a fixed `node:<n>` image (`YAD-CI-002`, an
220
+ install from before the variable — `yad update` replaces it).
221
+ - **Product jobs of your own** (`yad-product-checks.yml`): before #364 this fragment set its image
222
+ and tag in a top-level `default:`, which GitLab applies to every job in the pipeline — the
223
+ Product's own jobs too. They now sit on the yad jobs only. A job of yours that had no `image:` or
224
+ `tags:` and relied on that block needs its own after `yad update`.
201
225
 
202
226
  - Ensure `<repo>/package.json` defines `lint`, `build`, `test` scripts (see `references/check-gates.md`
203
227
  for the canonical scripts). **Only ADD a missing script; never overwrite an existing one.**
@@ -270,7 +294,12 @@ it. Branch protection is what makes the CI gates hold a merge at all: point the
270
294
  `docs/branch-protection.md`.
271
295
 
272
296
  ### Step 3 — `run` (run the gates now)
273
- From inside the repo, run each gate against `base` and report PASS/FAIL per gate:
297
+ From inside the repo, run `yad run checks` (add `--body <file>` holding the PR/MR description, and
298
+ `--title` unless the branch has exactly one commit). It runs every installed gate as CI does — the
299
+ Product's default branch where CI checks it out, every gate even after one fails — and prints a summary;
300
+ report PASS, FAIL or skipped per gate from it (`--json` lists each gate's FAIL lines). A skipped
301
+ pr-title or pr-template is not a pass. It runs `npm ci` (which replaces `node_modules`) and the build;
302
+ add `--no-build` when that is not wanted. One gate by hand:
274
303
  ```
275
304
  bash checks/spec-link.sh "<base>"
276
305
  bash checks/contract-check.sh "<base>"
@@ -4,6 +4,9 @@ The gates are the production-safety core of Build (Phase 3 build plan §C). They
4
4
  deliberately small, separate, and CI-agnostic: plain bash in `checks/`, invoked by whatever CI the
5
5
  repo uses. Each reads conventions established by earlier steps — it invents nothing.
6
6
 
7
+ For people, `docs/GATES.md` in the yadflow repo lists every gate's rules, exemptions and failure
8
+ messages, with what to change for each. When a gate's rule or message changes, update that page too.
9
+
7
10
  ## What each gate reads (the convention map)
8
11
 
9
12
  | Gate | Reads | Source step |
@@ -75,6 +78,18 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
75
78
  A maintenance commit that *does* carry a `Task:` trailer is resolved like any other: a malformed id
76
79
  or a missing `specs/<story>/link.md` **FAILS**. Otherwise the trailer is decorative on exempt
77
80
  commits and an unlinked `chore:` is indistinguishable from one naming a story that never existed.
81
+ - **SHA exemption** (shared with lineage-check, epic-open and reconcile-debt — one byte-identical block).
82
+ A commit listed in `.sdlc/gate-exempt` (or `SDLC_GATE_EXEMPT`; one full hex SHA per line — 40
83
+ characters, 64 in a SHA-256 repo, `#` comments; a short SHA is refused, as a tag of that name would stand in for it) **PASSes** before anything else is judged,
84
+ so it skips every check of the four gates, not only the trailer's. `SDLC_GATE_EXEMPT` comes from the
85
+ pipeline config, which a PR may edit; it still names a file on the base, so it cannot list the PR's
86
+ own commits, and guarding the pipeline itself is branch protection's job. It is for history already on a shared
87
+ branch whose trailer cannot be reworded — otherwise every later range that holds it, a release PR
88
+ above all, fails again. The list is read **from the base**, never from the PR, so a PR cannot waive
89
+ its own commits. An entry exempts nothing, and is said as a note, when it is a branch or tag name, a
90
+ short SHA, a SHA of the wrong length for this repo (64 characters in a SHA-1 repo, 40 in a SHA-256
91
+ one — git would look it up as a ref name), an annotated tag's or a tree's SHA, or a SHA that names no
92
+ object here.
78
93
  - For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
79
94
  - The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
80
95
  `EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
@@ -360,7 +375,9 @@ from the event payload):
360
375
  pass — it has no EP artifact to review.
361
376
  - **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
362
377
  changes Shape artifacts (any path under `epics/**` or `foundation/**`) **FAILS** — those changes must go through
363
- a `review/EP-*` PR and the artifact-review workflow. CI passes the PR's changed paths via
378
+ a `review/EP-*` PR and the artifact-review workflow. The message says how: move them to a
379
+ `review/<epic>/<artifact>` branch (`review/EP-foundation/foundation` for the Foundation) and run
380
+ `yad open-pr` from it, or drop them from the PR. CI passes the PR's changed paths via
364
381
  `--changed <file>` (computed from the diff against the base ref); without that list (a direct
365
382
  by-hand caller) the guard is inert and the branch split alone applies. A step owner file
366
383
  (`epics/<epic>/.sdlc/owners/<step>.json`, `foundation/.sdlc/owners/…`, written by `yad assign`,
@@ -384,18 +401,36 @@ catches a free-form description that bypassed it:
384
401
  `## Impact & Risk`, `## Checklist`, filled `Risk level:`).
385
402
  - **Anti-bypass guard** (same as pr-title): a non-review head that changes Shape artifacts
386
403
  (`epics/**` or `foundation/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
387
- must go through a `review/EP-*` PR. Step owner files alone do not count (E47).
404
+ must go through a `review/EP-*` PR, and the message says how, as in pr-title. Step owner files alone do not count (E47).
388
405
 
389
406
  **GitLab truncates the description this gate reads.** `$CI_MERGE_REQUEST_DESCRIPTION` stops at **2700
390
407
  characters**, so a long but perfectly valid MR can lose a required section *before the gate sees it* —
391
408
  the author then reads "does not use the template" while looking at a description that visibly contains
392
- it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated). Two mitigations,
393
- both shipped:
409
+ it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated). Three mitigations,
410
+ all shipped:
411
+
412
+ - **the gate reads the whole description (#343).** In GitLab CI, when GitLab says it cut the description
413
+ (`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED`) or the text it was handed has reached 2700 characters, the
414
+ gate reads it again in full from the merge request API
415
+ (`$CI_API_V4_URL/projects/$CI_MERGE_REQUEST_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID`) and checks
416
+ that instead. The token is the `GITLAB_TOKEN` (or `SDLC_API_TOKEN`) CI/CD variable — the same
417
+ `read_api` token `yad-verified-commits` already needs — or, without one, the job's own `CI_JOB_TOKEN`,
418
+ which GitLab's job-token access list allows on a single merge request (an older GitLab may not). It goes to `curl` in a header file, never on
419
+ its command line, and only to that GitLab's own API; `node` decodes the answer. If the full text
420
+ cannot be read (no token that works, no `curl` or `node`, no answer), the cut body is checked as
421
+ before and the note below also says why and to set `GITLAB_TOKEN`. A fork's pipeline runs in the fork
422
+ and cannot read the target project's merge request; its note says so, and only the order of the
423
+ sections helps there. The API answers with the description as it is now, so a job re-run after the
424
+ author edits a long description checks the edit (a short one is read from the pipeline's variable);
394
425
 
395
426
  - the GitLab MR templates (`yad-pr-template` `templates/gitlab/…` and `templates/product/gitlab/…`) carry
396
427
  the constraint as a comment and keep every required section early, so a truncated body still passes;
397
- - when a required section is missing **and** the body it read is ≥ 2700 characters, the gate prints a
398
- `NOTE` naming the truncation and the fix — reorder the required sections above the cutoff and push
428
+ - when a required section is missing **and** the body it read was cut (GitLab's flag, or ≥ 2700
429
+ characters) and the full text could not be read, the gate prints a `NOTE` naming the truncation, why
430
+ the full text was not read and, only where a token change can help, what to change (no variable and a
431
+ refusal: set `GITLAB_TOKEN`, or in a fork, that a fork cannot read the target's MR; a variable that is
432
+ set: 401 renew or replace it, 403 give it `read_api`, 404 its user cannot see the project; a timeout, a
433
+ 5xx or an odd answer: the reason alone), and the fix — reorder the required sections above the cutoff and push
399
434
  the long narrative to the end. Never delete a section: reordering is always allowed.
400
435
 
401
436
  ## 8. Phase 6 — feature-thread gates (`lineage-check.sh`, `epic-open.sh`, `reconcile-debt-check.sh`)
@@ -406,7 +441,10 @@ resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md
406
441
  → the Product epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
407
442
  commits **with no `Task:` trailer** are exempt — like spec-link, the exemption waives the requirement
408
443
  for an owning epic, never the validity of one that is claimed, so a maintenance subject cannot buy a
409
- pass past the sealed-epic / orphan-thread / frozen-thread checks. When the **Product is not reachable** from CI (the usual case for a code-repo
444
+ pass past the sealed-epic / orphan-thread / frozen-thread checks. The one deliberate exception is the
445
+ SHA exemption (§1): a commit listed in the base's `.sdlc/gate-exempt` skips all three gates, those checks
446
+ included, before anything else is judged — a reviewed waiver of one named commit, which no subject line
447
+ can buy. When the **Product is not reachable** from CI (the usual case for a code-repo
410
448
  PR), each degrades to a **PASS-with-note** — the Product-side check (`yad doctor` / `yad reconcile`) covers
411
449
  that path, and spec-link still proves the story link.
412
450
 
@@ -686,10 +724,13 @@ What it does in each case:
686
724
 
687
725
  | Case | Result |
688
726
  | --- | --- |
689
- | No record on the base, no `YAD_PRODUCT_TOKEN` (every PR from a fork), or no `git_url` in the record | A note; nothing is cloned, and the gates defer as before. |
690
- | The record's `path` is outside the repo, `.`, absolute, or under `.git` | **FAIL** — CI can only check a second repo out inside the workspace. |
727
+ | No record on the base, no `git_url` in the record (or one written with a JSON escape, a quote or a backslash, which it cannot read: write it without escapes), or no `YAD_PRODUCT_TOKEN` on a PR from a fork (a fork is never given secrets) or outside CI | A note; nothing is cloned, and the gates defer as before. |
728
+ | No `YAD_PRODUCT_TOKEN` on a PR/MR that is **not** from a fork, while the base record names the Product (#345) | A `WARNING [product-checkout]` line (and a `::warning` annotation on GitHub); nothing is cloned and the gates defer — the job does not fail. On GitHub the workflow passes `YAD_PR_FORK` (head repo ≠ this repo); on GitLab the pipeline is a fork's when it runs outside the MR's target project (`CI_PROJECT_ID` ≠ `CI_MERGE_REQUEST_PROJECT_ID`) — a fork's MR pipeline a maintainer runs in the target project gets its variables, and warns. A Dependabot PR is told to add the token as a Dependabot secret too. |
729
+ | A token whose expiry the Product host reports within 30 days (#345) | A `WARNING` naming the date; the clone goes on. More than 30 days: a note with the date. |
730
+ | The host rejects the token on its API (HTTP 401) | If the clone then fails: **FAIL**, saying the token has expired or been revoked. If the clone works: a `WARNING`. |
731
+ | The record's `path` is outside the repo, `.`, absolute, or under `.git` | **FAIL** — CI can only check a second repo out inside the workspace. Change `path` in its own PR and merge that first (the record is read from the base; `yad check --fix` keeps a `path` that is set). An empty `path` is one `yad check --fix --push` from the Product writes, for each code repo cloned on that machine on its default branch. A path of only spaces fails too, and so does one written with a JSON escape, a quote or a backslash, which the gate cannot read: change that one. |
691
732
  | A folder on the way to `path` is a symlink (one the PR tracks, say) | **FAIL** — git would clone through it, to wherever it points. |
692
- | The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. |
733
+ | The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. Untrack the files if they do not belong in the repo (`git rm -r --cached --`, and add the folder to `.gitignore`), or change `path` in its own PR and merge that first. |
693
734
  | The folder is already there | Left as it is. |
694
735
  | The clone fails with a token set | **FAIL**, naming the URL and branch — a broken setup must not read like a deferral. |
695
736
 
@@ -697,6 +738,18 @@ The token is handed to git through its environment (`GIT_CONFIG_COUNT`, git 2.31
697
738
  never on a command line or in a URL; on GitHub the encoded form is masked too. An `ssh` `git_url`
698
739
  (`git@host:org/repo.git`) is cloned as the same repo over `https`.
699
740
 
741
+ **The token's expiry (#345).** Before the clone, the script makes one call to the Product host's API with
742
+ the token, handed to `curl` in a header file (`-H @file`), never on its command line, and only to the
743
+ Product's own host — or, for GitHub's cloud, its API host (`api.github.com`, `api.<sub>.ghe.com`). The API is chosen by that host first — `github.com` and `*.ghe.com` are GitHub, a host
744
+ with `gitlab` in its name is GitLab — and only for any other host by the CI it runs in. GitHub:
745
+ `rate_limit`, whose `github-authentication-token-expiration` response header carries a personal access
746
+ token's expiry. GitLab: `/api/v4/personal_access_tokens/self`, whose `expires_at` is the token's. A
747
+ token with only `read_repository` — the least it needs to clone — may not call GitLab's API at all
748
+ (HTTP 403); the note then points at `yad doctor`, which warns about the Product's **project** access
749
+ tokens that expire soon (not group or personal ones). A token with no expiry, an app token or no `curl` gives a note too, never a failure — only the clone
750
+ decides that. `yad doctor` checks where the token is SET (see
751
+ `docs/CLI.md`); it never sees the token itself.
752
+
700
753
  ## Sync with existing CI (merge, never clobber)
701
754
 
702
755
  `wire` is **additive**: it brings the SDLC gates into a repo that may already have CI, without ever
@@ -956,6 +1009,12 @@ names can actually close:
956
1009
 
957
1010
  ## Running by hand (Phase 3 is manual)
958
1011
 
1012
+ `yad run checks` runs every installed gate in one go, the way CI runs them: this repo's own `checks/`,
1013
+ against `origin/<default branch>`, with the Product's default branch written where
1014
+ `.sdlc/product-link.json` says while the four Product-reading gates run, and removed after (a folder
1015
+ already there is read as it is and kept: a run removes only what it wrote). Signatures are checked with git there; the platform's
1016
+ Verified badge is judged in CI. To run one gate on its own:
1017
+
959
1018
  From inside the code repo, against the PR/MR base (e.g. `master`). For the gates that take one, the
960
1019
  base argument is optional — omit it and the gate resolves the trunk in the order above (configured
961
1020
  `default_branch`, else `origin/HEAD`, else `origin/main`), printing the base it chose; pass it (or
@@ -18,10 +18,29 @@ package_manager="$(yad_detect_package_manager "$package_manager_spec")"
18
18
  run_with_words="$(yad_package_manager_command "$package_manager_spec" "$package_manager")"
19
19
  read -r -a run_with <<< "$run_with_words"
20
20
 
21
+ # One step of the gate. A failing step used to end the job under `set -e` with only the tool's own
22
+ # output; this names the step, the command to run by hand, and the missing-script case (#351).
23
+ run_step() {
24
+ local step="$1" has=0
25
+ shift
26
+ # Checked before it runs: npm prints nothing for a missing script, and runs an empty one as a pass,
27
+ # so an empty "test" would read as green. Exit 3 is "none"; a package.json node cannot read is left
28
+ # to the run itself, which reports it.
29
+ YAD_STEP="$step" node --input-type=module -e 'import fs from "node:fs"; const p=JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); const s=p.scripts?.[process.env.YAD_STEP]; process.exit(typeof s === "string" && s.trim() ? 0 : 3)' 2>/dev/null || has=$?
30
+ if [ "$has" = 3 ]; then
31
+ echo "FAIL [build/test/lint]: package.json has no \"${step}\" script, or an empty one — add one; the gate runs lint, build and test, in that order."
32
+ exit 1
33
+ fi
34
+ if ! "${run_with[@]}" run --silent "$step" "$@"; then
35
+ echo "FAIL [build/test/lint]: '${run_with_words} run ${step}' failed — the output above says why. Run it on your machine, fix what it reports, and push again."
36
+ exit 1
37
+ fi
38
+ }
39
+
21
40
  echo "[build/test/lint] lint…"
22
- "${run_with[@]}" run --silent lint
41
+ run_step lint
23
42
  echo "[build/test/lint] build…"
24
- "${run_with[@]}" run --silent build
43
+ run_step build
25
44
 
26
45
  # Worker cap: when YAD_TEST_MAX_WORKERS is set AND the repo's test script is jest/vitest (the
27
46
  # runners that accept --maxWorkers), forward it to bound CI test concurrency. For any other runner
@@ -39,6 +58,6 @@ fi
39
58
  echo "[build/test/lint] test…"
40
59
  # Intentional word-splitting: $extra is empty, `-- --maxWorkers=N` (npm), or `--maxWorkers=N` (pnpm).
41
60
  # shellcheck disable=SC2086
42
- "${run_with[@]}" run --silent test $extra
61
+ run_step test $extra
43
62
 
44
63
  echo "PASS [build/test/lint]: lint, build, and tests all green."
@@ -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"