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
@@ -330,8 +330,9 @@ signature-checked parent, so there is nothing to protect. This unblocks **self-h
330
330
  does not sign UI-created merge commits (the signature API returns 404) — without it every routine merge
331
331
  would red the branch. A merge that *does* introduce content of its own still requires a verified
332
332
  signature (fail-closed), so an evil merge pushed direct-to-default cannot smuggle in unverified changes.
333
- This matters for the push-on-default `yad-update-guard` (§9), which — unlike this PR-triggered gate —
334
- sees merge commits.
333
+ This matters for the push-on-default `yad-update-guard` (§9), and for this PR-triggered gate too: a
334
+ GitHub `pull_request` run and a GitLab merged-results pipeline check a merge the platform made, which is
335
+ unsigned and content-free (#433).
335
336
 
336
337
  Degradation is explicit, never silent: no GitHub/GitLab remote SKIPs the signature check (the badge is a
337
338
  platform concept — this keeps local runs and tests meaningful); an unreachable platform API **fails
@@ -367,6 +368,10 @@ from the event payload):
367
368
  - `--profile code` (default) → a Conventional-Commits subject `<type>: <description>`, no trailing
368
369
  period (`config.yaml build.pr_title_style: same_as_commit_subject` — one task = one PR, the title is
369
370
  the squash-merge subject).
371
+ - **A GitLab draft** (#451): in GitLab CI (`GITLAB_CI=true`) a leading `Draft:`, `[Draft]` or
372
+ `(Draft)` (any case, repeats too) is stripped before the title is judged, with a `note`. GitLab removes
373
+ it when the MR is marked ready, which starts no pipeline, so the draft-time result is the one that
374
+ stands. Outside GitLab CI (GitHub, `yad run checks`) the title is judged as written.
370
375
  - `--profile product` (old name `hub`, still accepted) → splits by the PR/MR **head branch** (passed via `--head`, injected by CI):
371
376
  - `review/EP-*` head (or no `--head` — stays strict) → a Shape artifact-review title
372
377
  `review: <artifact> (EP-<slug>)`, the shape `yad gate open` creates.
@@ -381,10 +386,13 @@ from the event payload):
381
386
  `--changed <file>` (computed from the diff against the base ref); without that list (a direct
382
387
  by-hand caller) the guard is inert and the branch split alone applies. A step owner file
383
388
  (`epics/<epic>/.sdlc/owners/<step>.json`, `foundation/.sdlc/owners/…`, written by `yad assign`,
384
- E47) is not a Shape artifact: a PR that changes only owner files passes on any branch. The
385
- workflow builds the list with `--no-renames` (and `core.quotePath=false`), so a rename INTO
386
- `owners/` still lists the artifact it removed. A path git still C-quotes (a `"`, `\`, tab or
387
- newline in its name) counts as an artifact change and never as an owner file. Both greps run with
389
+ E47) is not a Shape artifact, and neither is an epic's issue-links file
390
+ (`epics/<epic>/.sdlc/issue-links.json`, written by `yad issues link`) or the Foundation's
391
+ roadmap-items file (`foundation/.sdlc/roadmap-items.json`, written by `yad foundation publish`)
392
+ (#512): a PR that changes only these files passes on any branch. The workflow builds the list
393
+ with `--no-renames` (and `core.quotePath=false`), so a rename INTO `owners/` or onto one of those
394
+ records still lists the artifact it removed. A path git still C-quotes (a `"`, `\`, tab or newline in its name) counts as
395
+ an artifact change and never as an exempt file. Both greps run with
388
396
  `LC_ALL=C grep -a`, so a path with bytes that are not valid UTF-8 is never dropped from the list.
389
397
 
390
398
  ## 7. pr-template (`templates/checks/pr-template.sh`)
@@ -401,7 +409,7 @@ catches a free-form description that bypassed it:
401
409
  `## Impact & Risk`, `## Checklist`, filled `Risk level:`).
402
410
  - **Anti-bypass guard** (same as pr-title): a non-review head that changes Shape artifacts
403
411
  (`epics/**` or `foundation/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
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).
412
+ must go through a `review/EP-*` PR, and the message says how, as in pr-title. Step owner files and the issue-links and roadmap-items records alone do not count (E47, #512).
405
413
 
406
414
  **GitLab truncates the description this gate reads.** `$CI_MERGE_REQUEST_DESCRIPTION` stops at **2700
407
415
  characters**, so a long but perfectly valid MR can lose a required section *before the gate sees it* —
@@ -643,9 +651,9 @@ someone who has worked in any of them meets the ask, and the output never says w
643
651
  `FILES`, `LEVEL`, `DIR <dir> <level> <state>`, `WHO <login|-> <name>`, `HISTNONE` — the history was read
644
652
  and held nobody — and `HISTUNKNOWN <why>`) for `checks/risk-route.sh`, which joins it with the PR
645
653
  body. One awk program serves both the warnings and the count. Its twin is `changeLevel` in
646
- `cli/riskmap.mjs`, and a parity test compares the two. **Known limits:** like every check here, the
647
- script runs from the PR's own checkout, so a PR can edit the script itself; that is harmless only because nothing
648
- blocks on the count — the Build count stays reported, and branch protection holds the merge (E72). And, as for the warnings, a path holding a newline is
654
+ `cli/riskmap.mjs`, and a parity test compares the two. **Known limits:** CI runs the base branch's copy of the
655
+ script (#426), but the workflow that calls it comes from the PR, so the count is only as safe as the code owner
656
+ review of the gate files; that is enough only because nothing blocks on the count — the Build count stays reported, and branch protection holds the merge (E72). And, as for the warnings, a path holding a newline is
649
657
  split in two here but kept whole by `changeLevel`, so the bash count can read its second half as a file
650
658
  at the root; the error can only raise the count, never lower it. (The E67 history is free of that class:
651
659
  it reads no file names at all.) If git itself fails, each step of the
@@ -656,43 +664,64 @@ count says "not counted"; the E65 warnings half is not guarded the same way, so
656
664
 
657
665
  The gates run identically under either CI; the config just invokes the scripts with the PR/MR base.
658
666
 
667
+ - **The base branch's scripts (#426).** CI never runs the PR's own `checks/`. Each gate job first copies
668
+ `checks/` from `origin/<base>` into a temp folder outside the work tree (`git archive`), and every call
669
+ is `bash "$YAD_CHECKS/<gate>.sh"` (`node "$YAD_CHECKS/member-check.mjs"`) with the PR's tree as the
670
+ working folder — so a PR that edits a gate script is still judged by the merged one. A script the base
671
+ does not have yet runs from the PR, with a `note:` line: one per file, or one line when the base has no
672
+ `checks/` at all (the PR that installs the gates). A link in the PR's `checks/` is never followed. An
673
+ `origin/<base>` that is not in the checkout FAILs the job (`FAIL [base-checks]`) — it never falls back
674
+ to the PR's copies. GitHub runs this as a step named "Gate scripts from the base branch (#426)" in each
675
+ job, exporting `YAD_CHECKS` through `$GITHUB_ENV`; GitLab as the first line of every gate job's `script:`
676
+ (`!reference [.yad_base_checks, script]`, GitLab 13.9 or later) — not a `before_script`, which would replace the host
677
+ pipeline's `default: before_script` for these jobs (registry auth, proxies). The step's text is the same everywhere, and a test holds it. The base's script runs with
678
+ the new file's call, so a call may only use what the previous release's script accepts (a test holds
679
+ that list too). The CI file itself still comes from the PR: the CODEOWNERS lines in
680
+ `docs/branch-protection.md` ("Who may change the gates") cover it.
681
+ - **No token left in the checkout (#426).** Every `actions/checkout` sets `persist-credentials: false`, so
682
+ code a job runs (the team's tests) finds no `GITHUB_TOKEN` in `.git/config`. No gate needs one there:
683
+ `product-checkout.sh` clones with its own token, and the base was fetched by `fetch-depth: 0`.
684
+
659
685
  - **GitHub Actions** — `templates/github/yad-checks.yml` → `.github/workflows/yad-checks.yml`. The
660
686
  jobs run on `pull_request` with `fetch-depth: 0`, passing `origin/${{ github.base_ref }}` as base
661
687
  (verified-commits also gets a read-only `GH_TOKEN` for the Verified-badge lookup). The trigger sets
662
- `types: [opened, synchronize, reopened, edited]` — the extra `edited` so a title/body correction
663
- re-runs the pattern gates without a close/reopen (a plain re-run replays the frozen original payload).
664
- The commit-range jobs carry `if: github.event.action != 'edited'` so a bare body/title edit only
665
- re-runs `pr-title`/`pr-template`, not the whole suite. The pattern jobs
688
+ `types: [opened, synchronize, reopened]` — never `edited` (#425): a job skipped by `if:` counts as
689
+ passed, so a run started by an edit of the PR text would turn a failed gate green. The two jobs that read
690
+ the PR text, `pr-title` and `pr-template`, live in `templates/github/yad-pr-text.yml` →
691
+ `.github/workflows/yad-pr-text.yml`, which adds `edited`, so a title/body correction re-runs them
692
+ without a close/reopen (a plain re-run replays the frozen original payload). The pattern jobs
666
693
  read the title/body from the event payload: `pr-title` takes `${{ github.event.pull_request.title }}`
667
694
  and `pr-template` writes `${{ github.event.pull_request.body }}` to a temp file. All `--profile code`.
668
695
  The Phase 6 thread gates (`lineage-check`, `epic-open`, `reconcile-debt`) and the advisory `risk-map`
669
- check run as their own jobs with `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base. The build/test/lint checkout also
670
- uses `filter: blob:none`; its installer follows `package.json#packageManager`, and `NX_BASE` /
696
+ check run as their own jobs with `fetch-depth: 0`, the same `origin/${{ github.base_ref }}` base. The build/test/lint checkout takes the
697
+ full history with no `filter: blob:none` (#426): a blob-less clone leaves out the base's `checks/`
698
+ when the PR changed them, and with no token kept the base-copy step could not fetch them. Its installer follows `package.json#packageManager`, and `NX_BASE` /
671
699
  `NX_HEAD` carry the exact base/head SHAs so Nx affected commands evaluate the PR rather than a
672
700
  stale default. `YAD_NODE_VERSION` is read from GitHub repository variables with `22` as the default.
673
701
  Dependencies are cached with `actions/cache` (npm's `~/.npm`, pnpm's store, and the Corepack home
674
702
  holding the pinned manager, keyed on the lockfiles and package.json) rather than setup-node's
675
703
  npm-only `cache:`, which must name the manager before package.json has been read.
676
- - **Pinned actions, read-only token.** Every `uses:` in the GitHub templates names a commit SHA, with
677
- the version after it in a comment (`actions/checkout@<sha> # v4.4.0`). A tag such as `@v4` can be
678
- moved to other code; a SHA cannot. Each workflow also sets a top-level `permissions:` block that is
679
- read-only, so no job gets write access unless it asks for it. If your own Dependabot bumps a SHA in
680
- an installed copy that `.sdlc/managed.json` records, `yad check` then reports that file as
681
- `modified`, and `yad update` keeps your copy rather than overwriting it — so that file stops
682
- receiving template changes. (`--overwrite-local` replaces it after saving `<file>.yad-orig`; a copy
683
- with no record reads as `outdated`, and a plain `yad update` replaces it, saving `<file>.yad-orig`
684
- first.) To stay on the template, leave the pins to yadflow releases.
704
+ - **Pinned actions, read-only token.** Every `uses:` in the GitHub templates names a commit SHA, with the
705
+ version after it in a comment (`actions/checkout@<sha> # v7.0.1`). A tag such as `@v4` can be moved to
706
+ other code; a SHA cannot. Each workflow also sets a top-level `permissions:` block that is read-only, so
707
+ no job gets write access unless it asks for it. These actions run on Node 24, so a self-hosted runner,
708
+ or GitHub Enterprise Server, needs Actions runner 2.327.1 or newer (GitHub's own runners already have
709
+ it). If your own Dependabot bumps a SHA in an installed copy that `.sdlc/managed.json` records, `yad
710
+ check` then reports that file as `modified`, and `yad update` keeps your copy rather than overwriting it
711
+ — so that file stops receiving template changes. (`--overwrite-local` replaces it after saving
712
+ `<file>.yad-orig`; a copy with no record reads as `outdated`, and a plain `yad update` replaces it,
713
+ saving `<file>.yad-orig` first.) To stay on the template, leave the pins to yadflow releases.
685
714
  - **GitLab CI** — `templates/gitlab/yad-checks.gitlab-ci.yml` → `.gitlab/ci/yad-checks.yml`, pulled in
686
715
  by the root `.gitlab-ci.yml`'s `include:`. The jobs run on `merge_request_event` with `GIT_DEPTH: 0`,
687
716
  passing `origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME`; the pattern jobs read `$CI_MERGE_REQUEST_TITLE`
688
717
  and `$CI_MERGE_REQUEST_DESCRIPTION`. The quality job uses the same package-manager-aware installer;
689
718
  `NX_BASE=$CI_MERGE_REQUEST_DIFF_BASE_SHA` and `NX_HEAD=$CI_COMMIT_SHA` provide the equivalent Nx
690
719
  range. Its `node:${YAD_NODE_VERSION}` image defaults to `22` and a project/group CI/CD variable may
691
- override it without editing the managed fragment. Those three variables sit on the `.sdlc_mr_only`
692
- anchor, not the fragment's top-level `variables:` — an included top-level block merges into the host
693
- pipeline's globals, where `NX_BASE`/`NX_HEAD` could collide with a host's own Nx setup. The retained greenfield standalone template
694
- (`templates/gitlab/.gitlab-ci.yml`) carries the same Node default, exact Nx range, and dependency
695
- installer and test-worker-cap semantics. All `--profile code`.
720
+ override it without editing the managed fragment. Those three variables and `GIT_DEPTH` sit on the
721
+ `.sdlc_mr_only` anchor, not a top-level `variables:` — an included top-level block merges into the host
722
+ pipeline's globals, where `NX_BASE`/`NX_HEAD` could collide with a host's own Nx setup, and where
723
+ `GIT_DEPTH: 0` made every host job clone the full history while a host's own `GIT_DEPTH` replaced it
724
+ (#434). No yad GitLab fragment has a top-level `variables:`. All `--profile code`.
696
725
 
697
726
  ### Checking the Product out in CI (E120)
698
727
 
@@ -717,9 +746,11 @@ itself, then confirms by reading (`yad doctor`) once they say it is done (E158).
717
746
  3. Add it to the **code repo** as the `YAD_PRODUCT_TOKEN` secret (GitHub: Settings → Secrets and
718
747
  variables → Actions; GitLab: Settings → CI/CD → Variables, **masked**).
719
748
 
720
- **Who can read the token.** The workflow runs on the PR's own copy of `checks/product-checkout.sh`, so
721
- anyone who can push a branch to the code repo can read `YAD_PRODUCT_TOKEN` — edit the script, open a
722
- PR. (A PR from a fork gets no secret, and defers.) So give it **read** access to the Product repository
749
+ **Who can read the token.** The workflow runs the base branch's copy of `checks/product-checkout.sh`
750
+ (#426), so editing the script in a PR does not reach it. But a PR's workflow runs before any review:
751
+ anyone who can push a branch can add or change a workflow that prints `YAD_PRODUCT_TOKEN`, whatever
752
+ CODEOWNERS says — a code owner guards the merge, not the run (`docs/branch-protection.md`, "Who may
753
+ change the gates"). (A PR from a fork gets no secret, and defers.) So give it **read** access to the Product repository
723
754
  and nothing else. On GitLab, a variable marked **protected** is not handed to pipelines of unprotected
724
755
  branches, so merge requests from feature branches would defer: leave it unprotected, masked, and
725
756
  read-only.
@@ -789,7 +820,9 @@ The Product is itself a repo on a platform (recorded in `.sdlc/product.json` by
789
820
  `yad-connect-repos action: detect-product`). `wire repo: product` targets `{project-root}` and uses the same
790
821
  merge-not-clobber logic, with a **Product-flavored gate set** appropriate to a "thinking" repo (it has no
791
822
  `specs/` or `package.json` build). **What yadflow wires today** (`PRODUCT_WIRING`): `commit-message`,
792
- `pr-title`, `pr-template` and `ledger-guard` in `yad-product-checks`, `verified-commits` in its own workflow,
823
+ `ledger-guard` and `member-check` in `yad-product-checks`, `pr-title` and `pr-template` in
824
+ `yad-product-pr-text` on GitHub (the only Product file that re-runs on an edit of the PR text, #425; on GitLab they
825
+ are jobs in `yad-product-checks`), `verified-commits` in its own workflow,
793
826
  and the `yad-update-guard`. On GitHub the `ledger-guard` job is given **no** `GH_TOKEN` on purpose: its
794
827
  bot exemption checks the author text and the Verified badge, and the badge proves only that the
795
828
  *committer* signed, so any contributor who signs could claim the bot's name. Without a token the badge
@@ -830,7 +863,9 @@ title + the code task template), so a PR that changes the Product's own workflow
830
863
  `yad check --fix` installs the same `checks/*.sh` scripts plus a standalone Product workflow
831
864
  (`templates/github/yad-product-checks.yml` → `.github/workflows/yad-product-checks.yml`, or the GitLab fragment
832
865
  `templates/gitlab/yad-product-checks.gitlab-ci.yml` → `.gitlab/ci/yad-product-checks.yml` + its one include
833
- line). Code repos run the same three with `--profile code` inside the main `yad-checks` workflow.
866
+ line), and on GitHub `templates/github/yad-product-pr-text.yml` → `.github/workflows/yad-product-pr-text.yml`
867
+ for `pr-title` and `pr-template`. Code repos run the same three with `--profile code`: `commit-message` in
868
+ the main `yad-checks` workflow, the other two in `yad-pr-text` (GitHub) or `yad-checks` (GitLab).
834
869
 
835
870
  ## The agent guardrail (`templates/hooks/ledger-guard.mjs` + `yad hook ledger-guard`)
836
871
 
@@ -9,6 +9,13 @@ readonly YAD_CHECKS_DIR
9
9
  # shellcheck source-path=SCRIPTDIR
10
10
  # shellcheck source=package-manager.sh
11
11
  source "$YAD_CHECKS_DIR/package-manager.sh"
12
+
13
+ # The base branch, as the other gates take it: the first argument, or SDLC_BASE (#496).
14
+ if yad_unity_skip "${1:-${SDLC_BASE:-}}"; then
15
+ echo "SKIP [build/test/lint]: a Unity project (ProjectSettings/ProjectVersion.txt and Assets/): not built by yad. Build and test it with Unity's own CI, such as GameCI."
16
+ exit 0
17
+ fi
18
+
12
19
  # Two assignments on purpose: nested inside another $(...), a failing yad_package_manager_spec would
13
20
  # be swallowed, and the gate would fall back to lockfile detection and PASS on a package.json it
14
21
  # had just rejected. Each step fails the gate on its own under `set -e`.
@@ -8,6 +8,12 @@ readonly YAD_CHECKS_DIR
8
8
  # shellcheck source=package-manager.sh
9
9
  source "$YAD_CHECKS_DIR/package-manager.sh"
10
10
 
11
+ # The base branch, as the other gates take it: the first argument, or SDLC_BASE (#496).
12
+ if yad_unity_skip "${1:-${SDLC_BASE:-}}"; then
13
+ echo "SKIP [install-deps]: a Unity project (ProjectSettings/ProjectVersion.txt and Assets/): no Node packages to install."
14
+ exit 0
15
+ fi
16
+
11
17
  package_manager_spec="$(yad_package_manager_spec)"
12
18
  package_manager="$(yad_detect_package_manager "$package_manager_spec")"
13
19
 
@@ -22,8 +22,9 @@
22
22
  // case or Unicode twin of `.sdlc/members/` — a macOS or Windows checkout would read either as a member
23
23
  // file this gate never judged (E131 review 1–2; the E115 and E121 lessons).
24
24
  //
25
- // LIMIT: like every Product gate, this file and the workflow that runs it come from the PR's own checkout,
26
- // so a PR can change the gate it is judged by; branch protection on the default branch is the backstop.
25
+ // LIMIT: CI runs the base branch's copy of this file (#426), but the workflow that runs it comes from the
26
+ // PR, so a PR that changes the workflow can change the gate it is judged by; a required code owner review
27
+ // of the gate files (docs/branch-protection.md, "Who may change the gates") is the backstop.
27
28
  //
28
29
  // A Node script, not bash: it reads JSON and hashes, and both CI images already have Node (E113's hooks are
29
30
  // Node for the same reason). Usage: node checks/member-check.mjs <base-ref>
@@ -76,6 +76,48 @@ yad_validate_exact_package_manager_spec() {
76
76
  '
77
77
  }
78
78
 
79
+ # #496 — a Unity project builds and tests with Unity's own CI (GameCI, for example), and has no package.json, so
80
+ # the Node gate is skipped for it. A Unity project here is what `yad commit` reads as one: the file
81
+ # ProjectSettings/ProjectVersion.txt and the folder Assets/ at the root, neither a link, and no package.json.
82
+ # The base branch must have no package.json either: otherwise a change that deletes package.json and adds those
83
+ # two paths would skip the build of a Node repo. CI passes the base. With none (an edited CI file, or a local run),
84
+ # the base is worked out as the other gates do it (origin/HEAD, then origin/main); in CI, a base that cannot be
85
+ # worked out refuses the skip. Only a local run with no remote at all decides from its own files. Returns 0 to skip.
86
+ yad_unity_skip() {
87
+ local base="${1:-}" head c
88
+ [ ! -e "$YAD_PACKAGE_JSON" ] && [ ! -L "$YAD_PACKAGE_JSON" ] || return 1
89
+ [ -f ProjectSettings/ProjectVersion.txt ] && [ ! -L ProjectSettings/ProjectVersion.txt ] && [ ! -L ProjectSettings ] || return 1
90
+ [ -d Assets ] && [ ! -L Assets ] || return 1
91
+ if [ -z "$base" ]; then
92
+ head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || head=""
93
+ for c in "$head" origin/main; do
94
+ if [ -n "$c" ] && git rev-parse --verify --quiet "${c}^{commit}" >/dev/null 2>&1; then base="$c"; break; fi
95
+ done
96
+ if [ -z "$base" ] && [ -n "${CI:-}" ]; then
97
+ echo "note [unity]: no base branch was given or found, so the Unity project is not skipped. Pass the base branch to this script." >&2
98
+ return 1
99
+ fi
100
+ fi
101
+ if [ -n "$base" ]; then
102
+ if ! git rev-parse --verify --quiet "${base}^{commit}" >/dev/null 2>&1; then
103
+ echo "note [unity]: the base branch ${base} could not be read, so the Unity project is not skipped." >&2
104
+ return 1
105
+ fi
106
+ # The tree entry, not the file's contents: a partial clone may hold the tree without the file, and a read
107
+ # that fails must not look like "no package.json". A link or a submodule named package.json counts too.
108
+ local entry
109
+ if ! entry="$(git ls-tree "$base" -- package.json 2>/dev/null)"; then
110
+ echo "note [unity]: the base branch ${base} could not be read, so the Unity project is not skipped." >&2
111
+ return 1
112
+ fi
113
+ if [ -n "$entry" ]; then
114
+ echo "note [unity]: ${base} has a package.json, so removing it here does not skip the Node gate." >&2
115
+ return 1
116
+ fi
117
+ fi
118
+ return 0
119
+ }
120
+
79
121
  yad_package_manager_spec() {
80
122
  if [ ! -f "$YAD_PACKAGE_JSON" ]; then
81
123
  echo "FAIL [package-manager]: package.json is missing." >&2
@@ -7,8 +7,8 @@
7
7
  # It also COUNTS (E66): a change touching a `high` directory adds the high step, +1 approver, printed as
8
8
  # a `COUNT [risk-map]:` line. The count reads the map on the BASE branch, never this change's copy, so a
9
9
  # change cannot lower its own count by editing the map. It is reported, never enforced: a Build merge is
10
- # held by the platform's branch protection, and this script runs from the PR's own checkout, so a PR could
11
- # edit it — harmless only because nothing blocks on it (E72). It cannot apply the capacity cap either: the
10
+ # held by the platform's branch protection. CI runs the base branch's copy of this script (#426), but the
11
+ # workflow that calls it comes from the PR — harmless only because nothing blocks on the count (E72). It cannot apply the capacity cap either: the
12
12
  # cap needs the Product's count of active people, which a code repo's CI does not have; `yad open-pr`
13
13
  # shows the capped count. A `guessed` level counts as a `confirmed` one;
14
14
  # an `unset` line and an uncovered directory add nothing. The change's files for the count include
@@ -135,7 +135,7 @@ signature_verified() {
135
135
  gitlab)
136
136
  # In CI use the documented API directly; locally fall back to the user's own glab.
137
137
  if [ -n "${CI_API_V4_URL:-}" ] && [ -n "${CI_PROJECT_ID:-}" ]; then
138
- body="$(curl -fsS --header "PRIVATE-TOKEN: ${GITLAB_TOKEN:-${SDLC_API_TOKEN:-}}" \
138
+ body="$(curl -fsS --max-time 15 --header "PRIVATE-TOKEN: ${GITLAB_TOKEN:-${SDLC_API_TOKEN:-}}" \
139
139
  "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/repository/commits/${sha}/signature" 2>/dev/null || true)"
140
140
  else
141
141
  body="$(glab api "projects/:id/repository/commits/${sha}/signature" 2>/dev/null || true)"
@@ -167,8 +167,8 @@ while IFS= read -r sha; do
167
167
  # A merge commit (2+ parents) whose content is all in its parents may go unsigned — see
168
168
  # merge_introduces_no_content. Every other commit, merges with content of their own included, needs
169
169
  # the signature: a platform merge commit is Verified, so a locally-forged merge pushed
170
- # direct-to-default cannot dodge the check. This matters for the push-on-default yad-update-guard,
171
- # which (unlike the PR-triggered gates) sees merge commits.
170
+ # direct-to-default cannot dodge the check. The PR-triggered gates see one too: a GitHub pull_request run
171
+ # and a GitLab merged-results pipeline check a merge the platform made, unsigned and content-free (#433).
172
172
  is_merge=0
173
173
  [ "$(git log -1 --format=%P "$sha" | wc -w | tr -d '[:space:]')" -ge 2 ] && is_merge=1
174
174