yadflow 4.9.0 → 4.11.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 (155) hide show
  1. package/CHANGELOG.md +184 -0
  2. package/README.md +15 -5
  3. package/bin/commands.mjs +11 -1
  4. package/bin/yad.mjs +203 -14
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1797 -73
  7. package/cli/agent-rules.mjs +64 -5
  8. package/cli/argv-flags.mjs +2 -2
  9. package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
  10. package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
  11. package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
  12. package/cli/brain/vendor/graphology-library.min.js +2 -0
  13. package/cli/brain/vendor/graphology.umd.min.js +2 -0
  14. package/cli/brain/vendor/sigma.min.js +1369 -0
  15. package/cli/brain/view/app.js +382 -0
  16. package/cli/brain/view/index.html +63 -0
  17. package/cli/brain/view/live.css +228 -0
  18. package/cli/brain/view/live.html +110 -0
  19. package/cli/brain/view/live.js +884 -0
  20. package/cli/brain/view/style.css +141 -0
  21. package/cli/brain-about.mjs +206 -0
  22. package/cli/brain-activity.mjs +285 -0
  23. package/cli/brain-skills.mjs +118 -0
  24. package/cli/brain-vendor.mjs +71 -0
  25. package/cli/brain-view.mjs +344 -0
  26. package/cli/brain.mjs +810 -0
  27. package/cli/ci-check.mjs +48 -4
  28. package/cli/codeowners-command.mjs +72 -6
  29. package/cli/commit.mjs +17 -3
  30. package/cli/docs.mjs +2 -0
  31. package/cli/doctor.mjs +151 -25
  32. package/cli/epic-state.mjs +186 -4
  33. package/cli/epic.mjs +26 -10
  34. package/cli/errors.mjs +2 -1
  35. package/cli/find-product.mjs +69 -15
  36. package/cli/fold.mjs +31 -6
  37. package/cli/foundation-publish.mjs +256 -0
  38. package/cli/gate.mjs +29 -3
  39. package/cli/git-read.mjs +38 -0
  40. package/cli/guard-stream.mjs +409 -0
  41. package/cli/guide.mjs +3 -1
  42. package/cli/hook.mjs +102 -9
  43. package/cli/issue-links.mjs +61 -0
  44. package/cli/issues-act.mjs +371 -0
  45. package/cli/issues-write.mjs +441 -0
  46. package/cli/issues.mjs +513 -0
  47. package/cli/lib.mjs +37 -2
  48. package/cli/lifecycle.mjs +7 -0
  49. package/cli/local-page.mjs +138 -0
  50. package/cli/machine.mjs +1 -1
  51. package/cli/manifest.mjs +59 -3
  52. package/cli/map/view/app.js +712 -0
  53. package/cli/map/view/index.html +50 -0
  54. package/cli/map/view/style.css +142 -0
  55. package/cli/map-view.mjs +186 -0
  56. package/cli/map.mjs +637 -0
  57. package/cli/members.mjs +9 -15
  58. package/cli/next.mjs +1 -1
  59. package/cli/openpr.mjs +26 -6
  60. package/cli/plan.mjs +127 -0
  61. package/cli/platform.mjs +159 -4
  62. package/cli/product-index.mjs +1 -1
  63. package/cli/protection.mjs +53 -3
  64. package/cli/reconcile.mjs +9 -3
  65. package/cli/report.mjs +9 -3
  66. package/cli/reports-dir.mjs +391 -0
  67. package/cli/reports.mjs +65 -0
  68. package/cli/run-checks.mjs +15 -4
  69. package/cli/scan.mjs +314 -0
  70. package/cli/setup.mjs +42 -8
  71. package/cli/standup.mjs +120 -78
  72. package/cli/status.mjs +6 -5
  73. package/cli/story-frames.mjs +17 -6
  74. package/cli/test-agents-file.mjs +985 -12
  75. package/cli/test-brain-activity.mjs +753 -0
  76. package/cli/test-brain-view.mjs +381 -0
  77. package/cli/test-brain.mjs +795 -0
  78. package/cli/test-build.mjs +25 -0
  79. package/cli/test-ci-check.mjs +469 -10
  80. package/cli/test-guide.mjs +218 -0
  81. package/cli/test-machine.mjs +59 -0
  82. package/cli/test-map.mjs +615 -0
  83. package/cli/test-node.mjs +15 -0
  84. package/cli/test-reports.mjs +382 -0
  85. package/cli/test-run-checks.mjs +21 -0
  86. package/cli/test-setup-agent.mjs +14 -0
  87. package/cli/test-story-frames.mjs +74 -4
  88. package/cli/test-worktree.mjs +24 -3
  89. package/cli/toolbox-connect.mjs +259 -0
  90. package/cli/toolbox.mjs +187 -12
  91. package/cli/update-commit.mjs +101 -9
  92. package/cli/usage.mjs +8 -4
  93. package/package.json +12 -4
  94. package/skills/sdlc/config.yaml +1 -1
  95. package/skills/sdlc/module-help.csv +3 -1
  96. package/skills/yad-analysis/SKILL.md +4 -0
  97. package/skills/yad-architecture/SKILL.md +22 -4
  98. package/skills/yad-backfill/SKILL.md +4 -0
  99. package/skills/yad-change/SKILL.md +7 -1
  100. package/skills/yad-change/references/triage.md +2 -0
  101. package/skills/yad-checks/SKILL.md +15 -7
  102. package/skills/yad-checks/references/check-gates.md +70 -35
  103. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  104. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  105. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  106. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  107. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  108. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  109. package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
  110. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  111. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  112. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  113. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  114. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  115. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
  116. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  117. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  118. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  119. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  120. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  121. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  122. package/skills/yad-commit/SKILL.md +3 -1
  123. package/skills/yad-connect-design/SKILL.md +42 -10
  124. package/skills/yad-connect-design/references/design-context.md +35 -5
  125. package/skills/yad-connect-design/references/design-registry.md +3 -3
  126. package/skills/yad-connect-learning/SKILL.md +12 -2
  127. package/skills/yad-connect-repos/SKILL.md +18 -0
  128. package/skills/yad-connect-testing/SKILL.md +22 -5
  129. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  130. package/skills/yad-discovery/SKILL.md +11 -0
  131. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  132. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  133. package/skills/yad-docs/templates/app/package.json +6 -1
  134. package/skills/yad-epic/SKILL.md +7 -0
  135. package/skills/yad-epic/references/state-schema.md +50 -1
  136. package/skills/yad-guide/SKILL.md +8 -4
  137. package/skills/yad-implement/SKILL.md +117 -4
  138. package/skills/yad-implement/references/implement-conventions.md +2 -1
  139. package/skills/yad-issues/SKILL.md +54 -0
  140. package/skills/yad-learn/SKILL.md +4 -0
  141. package/skills/yad-open-pr/SKILL.md +6 -0
  142. package/skills/yad-pr-template/SKILL.md +2 -1
  143. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  144. package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
  145. package/skills/yad-product-bridge/references/bridge.md +28 -0
  146. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  147. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  148. package/skills/yad-run/SKILL.md +5 -0
  149. package/skills/yad-scan/SKILL.md +51 -0
  150. package/skills/yad-spec/SKILL.md +32 -2
  151. package/skills/yad-stories/SKILL.md +22 -4
  152. package/skills/yad-stories/references/story-schema.md +1 -1
  153. package/skills/yad-test-cases/SKILL.md +18 -2
  154. package/skills/yad-ui/SKILL.md +43 -8
  155. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
@@ -17,14 +17,62 @@
17
17
  # never touches the host root. The same goes for the gate jobs' own variables (`YAD_NODE_VERSION`,
18
18
  # `NX_BASE`, `NX_HEAD`): an included top-level `variables:` merges into the host's globals, where a
19
19
  # generic name like NX_BASE can collide with one the host already computes for its own Nx jobs.
20
- # Only `GIT_DEPTH` stays global — the gates need the full history and a host that sets its own wins.
20
+ # `GIT_DEPTH` is on the anchor too (#434): a top-level value made every host job clone the full history,
21
+ # and a host's own top-level GIT_DEPTH replaced it, leaving the gates a shallow clone.
22
+
23
+ #
24
+ # Gate scripts (#426): every job runs the BASE branch's copy of checks/, never the PR's own, so a PR that
25
+ # changes a gate script is still judged by the script already merged. A script the base does not have yet
26
+ # (the PR that first installs the gates, or a `yad update` that adds one) runs from the PR, with a note.
27
+ # The base's script runs with THIS file's call: keep every call one the previous release's script accepts.
28
+ # This file itself still comes from the PR: protect checks/ and the CI files with a CODEOWNERS rule and
29
+ # a required Code Owner review (docs/branch-protection.md, "Who may change the gates").
30
+ # The step the header names: the first line of every gate job's script (`!reference`, GitLab 13.9+), not a
31
+ # before_script, so a `default: before_script` of the host pipeline still runs. Every yad fragment defines
32
+ # this same key and the file included last wins, so keep every fragment on the same yadflow release.
33
+ .yad_base_checks:
34
+ script:
35
+ - |
36
+ YAD_BASE="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"; YAD_CHECKS="$(mktemp -d)/checks"; export YAD_CHECKS
37
+ (
38
+ set -euo pipefail
39
+ b="origin/${YAD_BASE}"; d="${YAD_CHECKS%/checks}"
40
+ rm -rf "$d"; mkdir -p "$YAD_CHECKS"
41
+ git rev-parse --verify --quiet "${b}^{commit}" > /dev/null || { echo "FAIL [base-checks]: ${b} is not in this checkout, so the gate scripts cannot be read from the base branch. Check the code out with its full history." >&2; exit 1; }
42
+ t="$(git ls-tree "$b" checks)"
43
+ case "$t" in
44
+ "") on_base=0 ;;
45
+ "040000 tree "*) git archive "$b" checks | tar -x -C "$d"; on_base=1 ;;
46
+ *) echo "FAIL [base-checks]: checks on ${b} is not a folder, so the gate scripts cannot be read from it. Make checks/ a plain folder on the base branch." >&2; exit 1 ;;
47
+ esac
48
+ git ls-tree -z HEAD checks/ > "$d/.pr"
49
+ n=0
50
+ while IFS= read -r -d '' e; do
51
+ m="${e%% *}"; p="${e#*$'\t'}"; o="${e#* * }"; o="${o%%$'\t'*}"; s="${p//[[:cntrl:]]/?}"
52
+ if [ -e "$d/$p" ] || [ -L "$d/$p" ]; then continue; fi
53
+ case "$m" in
54
+ 100644 | 100755) git cat-file blob "$o" > "$d/$p"; if [ "$m" = 100755 ]; then chmod +x "$d/$p"; fi ;;
55
+ *) printf 'note: %s in this PR is not a plain file, so it is not run (#426)\n' "$s"; continue ;;
56
+ esac
57
+ n=$((n + 1))
58
+ if [ "$on_base" = 1 ]; then printf 'note: %s is not on %s yet, so the copy from this PR runs (#426)\n' "$s" "$YAD_BASE"; fi
59
+ done < "$d/.pr"
60
+ rm -f "$d/.pr"
61
+ if [ "$n" = 1 ]; then w="1 file"; else w="$n files"; fi
62
+ if [ "$on_base" = 0 ]; then printf 'note: %s has no checks/ folder yet, so the gate scripts from this PR run: %s (#426)\n' "$YAD_BASE" "$w"; fi
63
+ )
21
64
 
22
65
  .sdlc_mr_only:
66
+ # A newer push to the same merge request may cancel this job's older run (#428). GitLab does it only when
67
+ # the project's "Auto-cancel redundant pipelines" setting is on and no job in the older
68
+ # pipeline that is not interruptible has started; the gates re-read the whole MR range, so nothing is missed.
69
+ interruptible: true
23
70
  image: node:${YAD_NODE_VERSION}
24
71
  variables:
25
72
  # A project/group CI/CD variable overrides a YAML value, so YAD_NODE_VERSION can be changed in
26
73
  # project settings without editing the managed fragment (a current 22 or 24 line; Node 25+ has no Corepack).
27
74
  YAD_NODE_VERSION: "22"
75
+ GIT_DEPTH: "0" # full history so the gates can diff against the target branch (on the yad jobs only, #434)
28
76
  NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
29
77
  NX_HEAD: $CI_COMMIT_SHA
30
78
  # Runner selection. These jobs need a docker/dind executor; on instances whose runners are all
@@ -35,26 +83,27 @@
35
83
  # instead strand it `pending` — if so, set the variable to a real tag. Single value only:
36
84
  # `tags: [$VAR]` is one tag equal to the whole variable, not a comma-split.
37
85
  tags: [$YAD_RUNNER_TAGS]
86
+ # A stuck job stops here, not at the 1-hour project default (#424). build-test-lint sets its own.
87
+ timeout: 10 minutes
38
88
  rules:
39
89
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
40
90
 
41
- variables:
42
- GIT_DEPTH: "0" # full history so the gates can diff against the target branch
43
-
44
91
  yad-spec-link:
45
92
  extends: .sdlc_mr_only
46
93
  needs: []
47
94
  script:
48
- - bash checks/spec-link.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
95
+ - !reference [.yad_base_checks, script]
96
+ - bash "$YAD_CHECKS/spec-link.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
49
97
 
50
98
  yad-contract-check:
51
99
  extends: .sdlc_mr_only
52
100
  needs: []
53
101
  script:
102
+ - !reference [.yad_base_checks, script]
54
103
  # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
55
104
  # variable is set (masked); without it the gate defers, with a WARNING unless the MR comes from a fork (#345).
56
- - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
57
- - bash checks/contract-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
105
+ - bash "$YAD_CHECKS/product-checkout.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
106
+ - bash "$YAD_CHECKS/contract-check.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
58
107
 
59
108
  # E65/E66 — the risk map (.sdlc/risk-map: a risk level per directory, no names). Warnings, and the
60
109
  # approver count read from the base branch's map. It never fails the pipeline (the count is reported,
@@ -63,16 +112,20 @@ yad-risk-map:
63
112
  extends: .sdlc_mr_only
64
113
  needs: []
65
114
  script:
66
- - bash checks/risk-map-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
115
+ - !reference [.yad_base_checks, script]
116
+ - bash "$YAD_CHECKS/risk-map-check.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
67
117
 
68
118
  yad-build-test-lint:
69
119
  extends: .sdlc_mr_only
120
+ timeout: 30 minutes # it runs the team's own build and tests
70
121
  needs: []
71
122
  variables:
72
123
  YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
73
124
  script:
74
- - bash checks/install-deps.sh
75
- - bash checks/build-test-lint.sh
125
+ - !reference [.yad_base_checks, script]
126
+ # The base branch lets a Unity project skip these two, and stops a change from skipping them by deleting package.json (#496).
127
+ - bash "$YAD_CHECKS/install-deps.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
128
+ - bash "$YAD_CHECKS/build-test-lint.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
76
129
 
77
130
  # Phase 6 — feature-thread gates (lineage / seal / hotfix-debt). Build on spec-link's story->epic
78
131
  # resolution; degrade to a note when the product repo is not reachable from CI.
@@ -80,48 +133,54 @@ yad-lineage-check:
80
133
  extends: .sdlc_mr_only
81
134
  needs: []
82
135
  script:
136
+ - !reference [.yad_base_checks, script]
83
137
  # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
84
138
  # variable is set (masked); without it the gate defers, with a WARNING unless the MR comes from a fork (#345).
85
- - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
86
- - bash checks/lineage-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
139
+ - bash "$YAD_CHECKS/product-checkout.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
140
+ - bash "$YAD_CHECKS/lineage-check.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
87
141
 
88
142
  yad-epic-open:
89
143
  extends: .sdlc_mr_only
90
144
  needs: []
91
145
  script:
146
+ - !reference [.yad_base_checks, script]
92
147
  # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
93
148
  # variable is set (masked); without it the gate defers, with a WARNING unless the MR comes from a fork (#345).
94
- - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
95
- - bash checks/epic-open.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
149
+ - bash "$YAD_CHECKS/product-checkout.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
150
+ - bash "$YAD_CHECKS/epic-open.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
96
151
 
97
152
  yad-reconcile-debt:
98
153
  extends: .sdlc_mr_only
99
154
  needs: []
100
155
  script:
156
+ - !reference [.yad_base_checks, script]
101
157
  # E120: check the Product out where .sdlc/product-link.json says, when the YAD_PRODUCT_TOKEN CI/CD
102
158
  # variable is set (masked); without it the gate defers, with a WARNING unless the MR comes from a fork (#345).
103
- - bash checks/product-checkout.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
104
- - bash checks/reconcile-debt-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
159
+ - bash "$YAD_CHECKS/product-checkout.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
160
+ - bash "$YAD_CHECKS/reconcile-debt-check.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
105
161
 
106
162
  # Pattern gates: commit subject + MR title + MR body all follow the convention (profile: code).
107
163
  yad-commit-message:
108
164
  extends: .sdlc_mr_only
109
165
  needs: []
110
166
  script:
111
- - bash checks/commit-message.sh --profile code "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
167
+ - !reference [.yad_base_checks, script]
168
+ - bash "$YAD_CHECKS/commit-message.sh" --profile code "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
112
169
 
113
170
  yad-pr-title:
114
171
  extends: .sdlc_mr_only
115
172
  needs: []
116
173
  script:
117
- - bash checks/pr-title.sh --profile code "$CI_MERGE_REQUEST_TITLE"
174
+ - !reference [.yad_base_checks, script]
175
+ - bash "$YAD_CHECKS/pr-title.sh" --profile code "$CI_MERGE_REQUEST_TITLE"
118
176
 
119
177
  yad-pr-template:
120
178
  extends: .sdlc_mr_only
121
179
  needs: []
122
180
  script:
181
+ - !reference [.yad_base_checks, script]
123
182
  - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
124
- - bash checks/pr-template.sh --profile code "$body"
183
+ - bash "$YAD_CHECKS/pr-template.sh" --profile code "$body"
125
184
 
126
185
  # No unverified commits: a platform-Verified signature on every commit (write access decides who authors).
127
186
  # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot
@@ -130,4 +189,5 @@ yad-verified-commits:
130
189
  extends: .sdlc_mr_only
131
190
  needs: []
132
191
  script:
133
- - bash checks/verified-commits.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
192
+ - !reference [.yad_base_checks, script]
193
+ - bash "$YAD_CHECKS/verified-commits.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
@@ -16,46 +16,94 @@
16
16
  # the Product's own jobs, and if the root already sets a top-level `image:`, GitLab rejects the whole
17
17
  # config ("image is defined in top-level and 'default:' entry"). The anchor scopes them to these jobs.
18
18
 
19
+ #
20
+ # Gate scripts (#426): every job runs the BASE branch's copy of checks/, never the PR's own, so a PR that
21
+ # changes a gate script is still judged by the script already merged. A script the base does not have yet
22
+ # (the PR that first installs the gates, or a `yad update` that adds one) runs from the PR, with a note.
23
+ # The base's script runs with THIS file's call: keep every call one the previous release's script accepts.
24
+ # This file itself still comes from the PR: protect checks/ and the CI files with a CODEOWNERS rule and
25
+ # a required Code Owner review (docs/branch-protection.md, "Who may change the gates").
26
+ # The step the header names: the first line of every gate job's script (`!reference`, GitLab 13.9+), not a
27
+ # before_script, so a `default: before_script` of the host pipeline still runs. Every yad fragment defines
28
+ # this same key and the file included last wins, so keep every fragment on the same yadflow release.
29
+ .yad_base_checks:
30
+ script:
31
+ - |
32
+ YAD_BASE="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"; YAD_CHECKS="$(mktemp -d)/checks"; export YAD_CHECKS
33
+ (
34
+ set -euo pipefail
35
+ b="origin/${YAD_BASE}"; d="${YAD_CHECKS%/checks}"
36
+ rm -rf "$d"; mkdir -p "$YAD_CHECKS"
37
+ git rev-parse --verify --quiet "${b}^{commit}" > /dev/null || { echo "FAIL [base-checks]: ${b} is not in this checkout, so the gate scripts cannot be read from the base branch. Check the code out with its full history." >&2; exit 1; }
38
+ t="$(git ls-tree "$b" checks)"
39
+ case "$t" in
40
+ "") on_base=0 ;;
41
+ "040000 tree "*) git archive "$b" checks | tar -x -C "$d"; on_base=1 ;;
42
+ *) echo "FAIL [base-checks]: checks on ${b} is not a folder, so the gate scripts cannot be read from it. Make checks/ a plain folder on the base branch." >&2; exit 1 ;;
43
+ esac
44
+ git ls-tree -z HEAD checks/ > "$d/.pr"
45
+ n=0
46
+ while IFS= read -r -d '' e; do
47
+ m="${e%% *}"; p="${e#*$'\t'}"; o="${e#* * }"; o="${o%%$'\t'*}"; s="${p//[[:cntrl:]]/?}"
48
+ if [ -e "$d/$p" ] || [ -L "$d/$p" ]; then continue; fi
49
+ case "$m" in
50
+ 100644 | 100755) git cat-file blob "$o" > "$d/$p"; if [ "$m" = 100755 ]; then chmod +x "$d/$p"; fi ;;
51
+ *) printf 'note: %s in this PR is not a plain file, so it is not run (#426)\n' "$s"; continue ;;
52
+ esac
53
+ n=$((n + 1))
54
+ if [ "$on_base" = 1 ]; then printf 'note: %s is not on %s yet, so the copy from this PR runs (#426)\n' "$s" "$YAD_BASE"; fi
55
+ done < "$d/.pr"
56
+ rm -f "$d/.pr"
57
+ if [ "$n" = 1 ]; then w="1 file"; else w="$n files"; fi
58
+ if [ "$on_base" = 0 ]; then printf 'note: %s has no checks/ folder yet, so the gate scripts from this PR run: %s (#426)\n' "$YAD_BASE" "$w"; fi
59
+ )
60
+
19
61
  .yad_product_mr_only:
62
+ # A newer push to the same merge request may cancel this job's older run (#428). GitLab does it only when
63
+ # the project's "Auto-cancel redundant pipelines" setting is on and no job in the older
64
+ # pipeline that is not interruptible has started; the gates re-read the whole MR range, so nothing is missed.
65
+ interruptible: true
20
66
  image: node:${YAD_NODE_VERSION}
21
67
  variables:
22
68
  # A project/group CI/CD variable overrides this YAML value, so the Node line can be changed in project
23
69
  # settings without editing the managed fragment (a current 22 or 24 line). A shell-executor runner
24
70
  # ignores `image:` — Node must then be on the runner host's PATH, and this value has no effect.
25
71
  YAD_NODE_VERSION: "22"
72
+ GIT_DEPTH: "0" # full history so the commit gate can diff against the target branch (on the yad jobs only, #434)
26
73
  # Runner selection: set the YAD_RUNNER_TAGS CI/CD variable (e.g. `dind_runner`) to route these jobs on
27
74
  # instances whose runners are tag-locked (run_untagged: false) — it lives in project Settings → CI/CD →
28
75
  # Variables, so it survives every `yad` sync. When unset, current GitLab (>=15) runs the jobs untagged;
29
76
  # older versions may strand them — set a real tag if so. Single value only: `tags: [$VAR]` is one tag.
30
77
  tags: [$YAD_RUNNER_TAGS]
78
+ timeout: 10 minutes # a stuck job stops here, not at the project default (#424)
31
79
  rules:
32
80
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
33
81
 
34
- variables:
35
- GIT_DEPTH: "0" # full history so the commit gate can diff against the target branch
36
-
37
82
  yad-product-commit-message:
38
83
  extends: .yad_product_mr_only
39
84
  needs: []
40
85
  script:
41
- - bash checks/commit-message.sh --profile product "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
86
+ - !reference [.yad_base_checks, script]
87
+ - bash "$YAD_CHECKS/commit-message.sh" --profile product "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
42
88
 
43
- # GIT_DEPTH: 0 (above) gives the changed paths, so the gate can reject an artifact change (epics/**)
89
+ # GIT_DEPTH: 0 (on .yad_product_mr_only) gives the changed paths, so the gate can reject an artifact change (epics/**)
44
90
  # riding a non-review source branch past the Shape review with a plain code title/template.
45
91
  yad-product-pr-title:
46
92
  extends: .yad_product_mr_only
47
93
  needs: []
48
94
  script:
95
+ - !reference [.yad_base_checks, script]
49
96
  - changed="$(mktemp)"; git -c core.quotePath=false diff --no-renames --name-only "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > "$changed"
50
- - bash checks/pr-title.sh --profile product --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$CI_MERGE_REQUEST_TITLE"
97
+ - bash "$YAD_CHECKS/pr-title.sh" --profile product --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$CI_MERGE_REQUEST_TITLE"
51
98
 
52
99
  yad-product-pr-template:
53
100
  extends: .yad_product_mr_only
54
101
  needs: []
55
102
  script:
103
+ - !reference [.yad_base_checks, script]
56
104
  - changed="$(mktemp)"; git -c core.quotePath=false diff --no-renames --name-only "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD" > "$changed"
57
105
  - body="$(mktemp)"; printf '%s' "$CI_MERGE_REQUEST_DESCRIPTION" > "$body"
58
- - bash checks/pr-template.sh --profile product --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
106
+ - bash "$YAD_CHECKS/pr-template.sh" --profile product --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" --changed "$changed" "$body"
59
107
 
60
108
  # The gate ledger is CI-owned: reject non-bot commits to .sdlc/{state,approvals,comments,product-prs,hub-prs}.json
61
109
  # or reviews/*.md (.sdlc/contract-lock.json is artifact-side and allowed). The one other exception is a
@@ -64,7 +112,8 @@ yad-product-ledger-guard:
64
112
  extends: .yad_product_mr_only
65
113
  needs: []
66
114
  script:
67
- - bash checks/ledger-guard.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
115
+ - !reference [.yad_base_checks, script]
116
+ - bash "$YAD_CHECKS/ledger-guard.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
68
117
 
69
118
  # E131: a member file (.sdlc/members/) is changed only by the MR's own author. GitLab's predefined
70
119
  # variables do not name the MR author, so the check reads it from the API with GITLAB_TOKEN or SDLC_API_TOKEN
@@ -73,4 +122,5 @@ yad-product-member-check:
73
122
  extends: .yad_product_mr_only
74
123
  needs: []
75
124
  script:
76
- - node checks/member-check.mjs "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
125
+ - !reference [.yad_base_checks, script]
126
+ - node "$YAD_CHECKS/member-check.mjs" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
@@ -19,6 +19,7 @@
19
19
 
20
20
  .yad_update_guard_base: &yad_update_guard_base
21
21
  tags: [$YAD_RUNNER_TAGS]
22
+ timeout: 10 minutes # a stuck job stops here, not at the project default (#424)
22
23
  image: node:${YAD_NODE_VERSION}
23
24
  variables:
24
25
  GIT_DEPTH: "0" # full history so the gates can diff the pushed range
@@ -10,13 +10,60 @@
10
10
  # read the commit-signature API. The Product's SDLC_GATE_TOKEN (from the gate-sync wiring) also works:
11
11
  # set GITLAB_TOKEN: $SDLC_GATE_TOKEN in the job if you prefer one token.
12
12
  # Job name is yad-product-prefixed so it can coexist with the code-repo fragment in one pipeline.
13
+ #
14
+ # Gate scripts (#426): every job runs the BASE branch's copy of checks/, never the PR's own, so a PR that
15
+ # changes a gate script is still judged by the script already merged. A script the base does not have yet
16
+ # (the PR that first installs the gates, or a `yad update` that adds one) runs from the PR, with a note.
17
+ # The base's script runs with THIS file's call: keep every call one the previous release's script accepts.
18
+ # This file itself still comes from the PR: protect checks/ and the CI files with a CODEOWNERS rule and
19
+ # a required Code Owner review (docs/branch-protection.md, "Who may change the gates").
20
+ # The step the header names: the first line of every gate job's script (`!reference`, GitLab 13.9+), not a
21
+ # before_script, so a `default: before_script` of the host pipeline still runs. Every yad fragment defines
22
+ # this same key and the file included last wins, so keep every fragment on the same yadflow release.
23
+ .yad_base_checks:
24
+ script:
25
+ - |
26
+ YAD_BASE="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"; YAD_CHECKS="$(mktemp -d)/checks"; export YAD_CHECKS
27
+ (
28
+ set -euo pipefail
29
+ b="origin/${YAD_BASE}"; d="${YAD_CHECKS%/checks}"
30
+ rm -rf "$d"; mkdir -p "$YAD_CHECKS"
31
+ git rev-parse --verify --quiet "${b}^{commit}" > /dev/null || { echo "FAIL [base-checks]: ${b} is not in this checkout, so the gate scripts cannot be read from the base branch. Check the code out with its full history." >&2; exit 1; }
32
+ t="$(git ls-tree "$b" checks)"
33
+ case "$t" in
34
+ "") on_base=0 ;;
35
+ "040000 tree "*) git archive "$b" checks | tar -x -C "$d"; on_base=1 ;;
36
+ *) echo "FAIL [base-checks]: checks on ${b} is not a folder, so the gate scripts cannot be read from it. Make checks/ a plain folder on the base branch." >&2; exit 1 ;;
37
+ esac
38
+ git ls-tree -z HEAD checks/ > "$d/.pr"
39
+ n=0
40
+ while IFS= read -r -d '' e; do
41
+ m="${e%% *}"; p="${e#*$'\t'}"; o="${e#* * }"; o="${o%%$'\t'*}"; s="${p//[[:cntrl:]]/?}"
42
+ if [ -e "$d/$p" ] || [ -L "$d/$p" ]; then continue; fi
43
+ case "$m" in
44
+ 100644 | 100755) git cat-file blob "$o" > "$d/$p"; if [ "$m" = 100755 ]; then chmod +x "$d/$p"; fi ;;
45
+ *) printf 'note: %s in this PR is not a plain file, so it is not run (#426)\n' "$s"; continue ;;
46
+ esac
47
+ n=$((n + 1))
48
+ if [ "$on_base" = 1 ]; then printf 'note: %s is not on %s yet, so the copy from this PR runs (#426)\n' "$s" "$YAD_BASE"; fi
49
+ done < "$d/.pr"
50
+ rm -f "$d/.pr"
51
+ if [ "$n" = 1 ]; then w="1 file"; else w="$n files"; fi
52
+ if [ "$on_base" = 0 ]; then printf 'note: %s has no checks/ folder yet, so the gate scripts from this PR run: %s (#426)\n' "$YAD_BASE" "$w"; fi
53
+ )
54
+
13
55
  yad-product-verified-commits:
56
+ # A newer push to the same merge request may cancel this job's older run (#428). GitLab does it only when
57
+ # the project's "Auto-cancel redundant pipelines" setting is on and no job in the older
58
+ # pipeline that is not interruptible has started; the gates re-read the whole MR range, so nothing is missed.
59
+ interruptible: true
14
60
  needs: []
15
61
  # Runner selection: set the YAD_RUNNER_TAGS CI/CD variable (e.g. `dind_runner`) to route this
16
62
  # docker job on instances whose runners are tag-locked (run_untagged: false) — it lives in
17
63
  # project Settings → CI/CD → Variables, so it survives every `yad` sync. When unset, current
18
64
  # GitLab (>=15) runs the job untagged; older versions may strand it — set a real tag if so.
19
65
  tags: [$YAD_RUNNER_TAGS]
66
+ timeout: 10 minutes # a stuck job stops here, not at the project default (#424)
20
67
  image: node:${YAD_NODE_VERSION}
21
68
  variables:
22
69
  GIT_DEPTH: "0" # full history so the gate can diff against the target branch
@@ -27,4 +74,5 @@ yad-product-verified-commits:
27
74
  rules:
28
75
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
29
76
  script:
30
- - bash checks/verified-commits.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
77
+ - !reference [.yad_base_checks, script]
78
+ - bash "$YAD_CHECKS/verified-commits.sh" "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
@@ -84,33 +84,67 @@ function runYad(yad, args, options) {
84
84
  }
85
85
  // ---- end yad-resolve ---------------------------------------------------------------------------------
86
86
 
87
+ // Read all of stdin. Asking `process.stdin.isTTY` makes Node open stdin as a stream, and on a pipe that
88
+ // switches fd 0 to non-blocking: a read then throws EAGAIN ("no data yet") whenever the payload arrives a
89
+ // moment after the hook starts. `fs.readFileSync(0)` gave up there, the hook read no payload, and it
90
+ // allowed — the macOS CI failures on #459 (a deny allowed) and #460 (no Cursor verdict: with no payload
91
+ // the hook could not tell it was Cursor). So this reads in a loop and, on EAGAIN, waits 5 ms and tries
92
+ // again, for up to `limitMs`; after that the error goes to the caller, which fails open. Keep the loop:
93
+ // the non-blocking mode is also what gives the limit — a blocking read would hang for ever on a parent
94
+ // that never closes stdin. A read of 0 bytes (or Windows' EOF error) is the end.
95
+ function readStdin(limitMs = 5000) {
96
+ const chunks = [];
97
+ const buf = Buffer.alloc(64 * 1024);
98
+ const nap = new Int32Array(new SharedArrayBuffer(4));
99
+ const until = Date.now() + limitMs;
100
+ for (;;) {
101
+ let n;
102
+ try { n = fs.readSync(0, buf, 0, buf.length, null); } catch (e) {
103
+ if (e?.code === 'EAGAIN' && Date.now() < until) { Atomics.wait(nap, 0, 0, 5); continue; }
104
+ if (e?.code === 'EOF') break;
105
+ throw e;
106
+ }
107
+ if (n === 0) break;
108
+ chunks.push(Buffer.from(buf.subarray(0, n)));
109
+ }
110
+ return Buffer.concat(chunks).toString('utf8');
111
+ }
112
+
87
113
  // The payload is read here, so the protocol can be chosen even when `yad` cannot be reached.
88
114
  let input = '';
89
- try { input = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8'); } catch { input = ''; }
115
+ try { input = process.stdin.isTTY ? '' : readStdin(); } catch { input = ''; }
90
116
  let payload = null;
91
117
  try { payload = JSON.parse(input); } catch { payload = null; }
92
118
  const cursor = payload?.hook_event_name === 'beforeShellExecution' || typeof payload?.cursor_version === 'string';
93
119
  const ALLOW = '{"permission":"allow"}';
120
+ // Exit with `code` once `text` is written. stdout to a pipe is asynchronous on macOS, so a `process.exit`
121
+ // straight after `process.stdout.write` can lose the verdict — and Cursor reads an empty answer as a block.
122
+ // The promise never resolves: `await finish(…)` also stops the code below it.
123
+ const finish = (code, text = '') => new Promise(() => {
124
+ if (!text) process.exit(code);
125
+ process.stdout.write(text, () => process.exit(code));
126
+ });
94
127
  const allow = (why) => {
95
128
  if (why) process.stderr.write(` • yad hook: ${why} — allowing\n`);
96
- if (cursor) process.stdout.write(`${ALLOW}\n`);
97
- process.exit(0);
129
+ return finish(0, cursor ? `${ALLOW}\n` : '');
98
130
  };
99
131
 
100
132
  const yad = resolveYad();
101
- if (!yad) allow(`no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} (install yadflow to re-arm the agent guard)`);
133
+ if (!yad) await allow(`no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} (install yadflow to re-arm the agent guard)`);
102
134
 
103
135
  const r = runYad(yad, ['hook', 'agent-guard', '--format', cursor ? 'cursor' : 'exit'], { input, stdio: ['pipe', 'pipe', 'inherit'], encoding: 'utf8' });
104
136
  if (cursor) {
105
137
  // The verdict is the last non-empty line that names a permission (see ledger-guard-cursor.mjs for why).
106
138
  const lines = String(r.stdout || '').split(/\r?\n/).filter((l) => l.trim());
107
139
  const verdict = lines.length ? lines[lines.length - 1] : '';
108
- if (verdict.includes('"permission"')) { process.stdout.write(`${verdict}\n`); process.exit(0); }
109
- allow(r.status === 0 ? '' : `\`yad hook agent-guard\` ${r.error ? r.error.message : `exited ${r.status ?? r.signal}`} (run \`yad doctor\` to check the install)`);
140
+ if (verdict.includes('"permission"')) await finish(0, `${verdict}\n`);
141
+ await allow(r.status === 0 ? '' : `\`yad hook agent-guard\` ${r.error ? r.error.message : `exited ${r.status ?? r.signal}`} (run \`yad doctor\` to check the install)`);
110
142
  }
111
143
  // Only an explicit deny (2) blocks: a yad that cannot run, or one older than this hook (it refuses the
112
144
  // unknown action with another code), must not read as a refusal.
113
- if (r.stdout) process.stdout.write(r.stdout);
114
- if (r.status === 2) process.exit(2);
115
- if (r.status !== 0) allow(`\`yad hook agent-guard\` ${r.error ? r.error.message : `exited ${r.status ?? r.signal}`} (run \`yad doctor\` to check the install)`);
116
- process.exit(0);
145
+ if (r.status === 2) await finish(2, r.stdout || '');
146
+ if (r.status !== 0) {
147
+ process.stderr.write(` • yad hook: \`yad hook agent-guard\` ${r.error ? r.error.message : `exited ${r.status ?? r.signal}`} (run \`yad doctor\` to check the install) — allowing\n`);
148
+ await finish(0, r.stdout || '');
149
+ }
150
+ await finish(0, r.stdout || '');
@@ -24,7 +24,14 @@ import path from 'node:path';
24
24
  import { fileURLToPath } from 'node:url';
25
25
 
26
26
  const ALLOW = '{"permission":"allow"}';
27
- const allow = () => { process.stdout.write(`${ALLOW}\n`); process.exit(0); };
27
+ // Exit with `code` once `text` is written. stdout to a pipe is asynchronous on macOS, so a `process.exit`
28
+ // straight after `process.stdout.write` can lose the verdict — and Cursor reads an empty answer as a block.
29
+ // The promise never resolves: `await finish(…)` also stops the code below it.
30
+ const finish = (code, text = '') => new Promise(() => {
31
+ if (!text) process.exit(code);
32
+ process.stdout.write(text, () => process.exit(code));
33
+ });
34
+ const allow = () => finish(0, `${ALLOW}\n`);
28
35
 
29
36
  // ---- yad-resolve (the same block in every hooks/*.mjs; a test keeps the copies identical) ----------
30
37
  // The Product root is this script's grandparent — `<product>/hooks/<script>.mjs` — found from the
@@ -93,7 +100,7 @@ function runYad(yad, args, options) {
93
100
  const yad = resolveYad();
94
101
  if (!yad) {
95
102
  process.stderr.write(` • yad hook: no \`yad\` on PATH and none installed in ${PRODUCT_ROOT} — allowing (install yadflow to re-arm the ledger guard)\n`);
96
- allow();
103
+ await allow();
97
104
  }
98
105
 
99
106
  // stdout is CAPTURED (the JSON verdict); stdin (the tool-call payload) and stderr (Cursor's log) are
@@ -107,7 +114,7 @@ const r = runYad(yad, ['hook', 'ledger-guard', '--format', 'cursor'], { stdio: [
107
114
  // care what order the JSON's properties are in.
108
115
  const lines = String(r.stdout || '').split(/\r?\n/).filter((l) => l.trim());
109
116
  const verdict = lines.length ? lines[lines.length - 1] : '';
110
- if (verdict.includes('"permission"')) { process.stdout.write(`${verdict}\n`); process.exit(0); }
117
+ if (verdict.includes('"permission"')) await finish(0, `${verdict}\n`);
111
118
 
112
119
  // EXIT 2 IS A DENY, even with nothing on stdout — and this branch is reached in a real, ordinary case.
113
120
  // The Product's own `node_modules/yadflow` comes BEFORE `PATH`, so a project pinned to a yadflow older
@@ -115,16 +122,15 @@ if (verdict.includes('"permission"')) { process.stdout.write(`${verdict}\n`); pr
115
122
  // The message is FIXED: the reason the older `yad` printed has already gone to stderr, where Cursor
116
123
  // logs it.
117
124
  if (r.status === 2) {
118
- process.stdout.write(`${JSON.stringify({
125
+ await finish(0, `${JSON.stringify({
119
126
  permission: 'deny',
120
127
  user_message: 'yad: this edit touches CI-owned gate state.',
121
128
  agent_message: 'This edit touches CI-owned gate state, which CI is the sole writer of. Do not edit the ledger by hand: use `yad gate open` for the transition, and commit only the artifact. The installed yadflow is older than this hook, so the full reason is in the hook log rather than here — `yad doctor` will name the version gap.',
122
129
  })}\n`);
123
- process.exit(0);
124
130
  }
125
131
 
126
132
  if (r.status !== 0) {
127
133
  const why = r.error ? r.error.message : `exited ${r.status ?? r.signal}`;
128
134
  process.stderr.write(` • yad hook: \`yad hook ledger-guard\` ${why} — allowing (run \`yad doctor\` to check the install)\n`);
129
135
  }
130
- allow();
136
+ await allow();