yadflow 4.6.0 → 4.8.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 (136) hide show
  1. package/CHANGELOG.md +259 -0
  2. package/README.md +46 -4
  3. package/bin/commands.mjs +9 -2
  4. package/bin/yad.mjs +309 -30
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/artifact-status.mjs +88 -20
  10. package/cli/build.mjs +1372 -0
  11. package/cli/checkpoint.mjs +2 -2
  12. package/cli/ci-check.mjs +492 -0
  13. package/cli/commit.mjs +1 -0
  14. package/cli/dial.mjs +21 -1
  15. package/cli/docs.mjs +7 -2
  16. package/cli/doctor.mjs +176 -33
  17. package/cli/epic-state.mjs +360 -12
  18. package/cli/errors.mjs +3 -0
  19. package/cli/find-product.mjs +36 -2
  20. package/cli/fold.mjs +9 -5
  21. package/cli/gate-local.mjs +9 -1
  22. package/cli/gate.mjs +364 -22
  23. package/cli/guide.mjs +549 -0
  24. package/cli/history.mjs +22 -2
  25. package/cli/hook.mjs +35 -4
  26. package/cli/index-command.mjs +2 -2
  27. package/cli/ledger.mjs +60 -0
  28. package/cli/lib.mjs +46 -0
  29. package/cli/lifecycle/defaults/2.json +124 -0
  30. package/cli/lifecycle/lifecycle.schema.json +5 -2
  31. package/cli/lifecycle.mjs +16 -3
  32. package/cli/manifest.mjs +75 -0
  33. package/cli/marked-block.mjs +48 -0
  34. package/cli/members.mjs +19 -5
  35. package/cli/migrate.mjs +17 -19
  36. package/cli/next.mjs +35 -12
  37. package/cli/openpr.mjs +81 -5
  38. package/cli/plan.mjs +326 -22
  39. package/cli/platform.mjs +21 -0
  40. package/cli/pr-list.mjs +5 -3
  41. package/cli/product-index.mjs +6 -3
  42. package/cli/product-token.mjs +186 -0
  43. package/cli/productcommit.mjs +33 -0
  44. package/cli/protection.mjs +50 -0
  45. package/cli/recommend.mjs +3 -1
  46. package/cli/reconcile.mjs +187 -26
  47. package/cli/repo-publish.mjs +2 -2
  48. package/cli/report.mjs +62 -14
  49. package/cli/run-checks.mjs +586 -0
  50. package/cli/setup.mjs +244 -25
  51. package/cli/ship-drift.mjs +49 -18
  52. package/cli/signing.mjs +377 -0
  53. package/cli/standup.mjs +1 -1
  54. package/cli/status.mjs +282 -0
  55. package/cli/test-agents-file.mjs +993 -0
  56. package/cli/test-build.mjs +1559 -0
  57. package/cli/test-ci-check.mjs +616 -0
  58. package/cli/test-guide.mjs +1267 -0
  59. package/cli/test-node.mjs +129 -0
  60. package/cli/test-run-checks.mjs +603 -0
  61. package/cli/test-setup-agent.mjs +352 -0
  62. package/cli/test-signing.mjs +524 -0
  63. package/cli/test-worktree.mjs +520 -0
  64. package/cli/thread.mjs +4 -0
  65. package/cli/tidy.mjs +2 -2
  66. package/cli/toolbox.mjs +37 -6
  67. package/cli/update-commit.mjs +313 -11
  68. package/cli/workspace.mjs +38 -10
  69. package/cli/worktree-record.mjs +53 -0
  70. package/cli/worktree.mjs +379 -0
  71. package/package.json +6 -4
  72. package/skills/sdlc/config.yaml +5 -5
  73. package/skills/sdlc/module-help.csv +2 -1
  74. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  75. package/skills/yad-change/SKILL.md +5 -1
  76. package/skills/yad-checks/SKILL.md +61 -12
  77. package/skills/yad-checks/references/check-gates.md +78 -14
  78. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  79. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  80. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  81. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  82. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  83. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  84. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  85. package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
  86. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  87. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  88. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  89. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  90. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  91. package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
  92. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
  93. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
  94. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  95. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  96. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  97. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  98. package/skills/yad-commit/SKILL.md +8 -5
  99. package/skills/yad-connect-repos/SKILL.md +5 -3
  100. package/skills/yad-connect-repos/references/code-context.md +2 -1
  101. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  102. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  103. package/skills/yad-docs/templates/app/package.json +2 -2
  104. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  105. package/skills/yad-engineer-review/SKILL.md +55 -25
  106. package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
  107. package/skills/yad-epic/SKILL.md +2 -1
  108. package/skills/yad-epic/references/state-schema.md +76 -17
  109. package/skills/yad-guide/SKILL.md +192 -0
  110. package/skills/yad-implement/SKILL.md +75 -13
  111. package/skills/yad-implement/references/implement-conventions.md +8 -1
  112. package/skills/yad-implement/templates/.gitmessage +3 -0
  113. package/skills/yad-open-pr/SKILL.md +21 -0
  114. package/skills/yad-pair-review/SKILL.md +14 -5
  115. package/skills/yad-pr-template/SKILL.md +6 -2
  116. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  117. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  118. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  119. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  120. package/skills/yad-product-bridge/SKILL.md +44 -12
  121. package/skills/yad-product-bridge/references/bridge.md +11 -5
  122. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  123. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  124. package/skills/yad-reconcile/SKILL.md +9 -3
  125. package/skills/yad-report/SKILL.md +15 -0
  126. package/skills/yad-review-companion/SKILL.md +5 -3
  127. package/skills/yad-review-gate/SKILL.md +16 -8
  128. package/skills/yad-review-gate/references/gating.md +26 -1
  129. package/skills/yad-run/SKILL.md +61 -33
  130. package/skills/yad-run/references/run-loop.md +44 -22
  131. package/skills/yad-spec/SKILL.md +137 -16
  132. package/skills/yad-spec/references/spec-handoff.md +50 -3
  133. package/skills/yad-status/SKILL.md +7 -0
  134. package/skills/yad-stories/references/story-schema.md +1 -1
  135. package/skills/yad-sync-repos/SKILL.md +2 -1
  136. package/skills/yad-ui/SKILL.md +2 -2
@@ -26,7 +26,7 @@ import { c, log, ok, info, fail, hand, exists, readJSON, readJSONStrict, pushWit
26
26
  import { PROJECT_FILES , productConfigPath } from './manifest.mjs';
27
27
  import { loadProduct } from './gate.mjs';
28
28
  import { platformLogin } from './platform.mjs';
29
- import { productGit, resolveDefaultBranch, guardDefaultBranch } from './productcommit.mjs';
29
+ import { productGit, resolveDefaultBranch, guardDefaultBranch, branchToCommitOn } from './productcommit.mjs';
30
30
  import { readShips, writeRetroShip } from './ledger.mjs';
31
31
  import { readFrontmatter, declaredRepos } from './epic-state.mjs';
32
32
 
@@ -314,8 +314,8 @@ export async function runCheckpoint(root, opts = {}) {
314
314
 
315
315
  const { productConfig } = loadProduct(root);
316
316
  const git = productGit(root);
317
- const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
318
317
  const defaultBranch = resolveDefaultBranch(git, productConfig);
318
+ const branch = branchToCommitOn(root, git, defaultBranch);
319
319
 
320
320
  // Default-branch guard (invariant 2) — shared with `yad tidy up`.
321
321
  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint', root })) return;
@@ -0,0 +1,492 @@
1
+ // `yad ci check` (E160b) — will yad's checks really hold a merge? Read-only: for the Product and each code repo
2
+ // the Product registers, it reads yad's workflow files on disk and the platform's rules on the default
3
+ // branch (protection, the checks required before a merge, force pushes, deletion). Every finding is `ok`,
4
+ // `gap` (with the fix), `suggest`, or `unknown` (a read that failed: never counted as ok).
5
+ //
6
+ // The platform's settings are the person's (a human-only act): the agent hands over the exact page and the
7
+ // clicks, then runs this again to confirm by reading. yad's own files are the agent's to fix, with the
8
+ // command each gap names.
9
+ //
10
+ // The rules it reads, and how (cli/protection.mjs `readCiSettings`):
11
+ // GitHub — a required check is named after its job. The checks required = those in the branch's active
12
+ // rulesets plus classic branch protection's. Classic protection is readable by admins only, so a
13
+ // job seen in neither is "not known" unless both were read. Who may bypass a ruleset is not read.
14
+ // GitLab — "Pipelines must succeed" covers every job in the pipeline, so yad's jobs must be IN it: the
15
+ // root `.gitlab-ci.yml` must include each of yad's fragments (the `files` row reads that). A
16
+ // skipped pipeline must not count as passed. A group's protected-branch rule is not in the
17
+ // project's list and wins over it, so a project entry saying "no" proves nothing in a group's
18
+ // project; in a person's own namespace there is no group rule, and the entry is the whole answer.
19
+ // "Require signed commits" is never suggested on the Product: CI's ledger commits are unsigned (#432), so it
20
+ // would stop every gate. On the Product it is a gap when it is on; on a code repo it is a suggestion.
21
+ import fs from 'node:fs';
22
+ import path from 'node:path';
23
+ import { c, log, ok, warn, fail, info, hand, run, exists, readJSON, isPlainObject, forTerminal, asArg } from './lib.mjs';
24
+ import { REQUIRED_CHECKS, REPO_WIRING, PRODUCT_WIRING, PROJECT_FILES, PRODUCT_LINK, productConfigPath, isVerifiedLedger } from './manifest.mjs';
25
+ import { readCiSettings, protectionLine } from './protection.mjs';
26
+ import { repoActions, productActions } from './plan.mjs';
27
+ import { judgeRepo, runnable } from './workspace.mjs';
28
+ import { isSolo } from './gate.mjs';
29
+
30
+ // yad's CI files: the workflows (or GitLab fragments), the gate scripts they run, and the record that tells a
31
+ // code repo's CI where the Product is — not the pull request template beside them, nor the agent guard
32
+ // (which only a session runs).
33
+ const CI_FILES = new Set([...Object.values(REPO_WIRING), ...Object.values(PRODUCT_WIRING)]
34
+ .flat().map((w) => w.dest).filter((d) => /^(\.github\/workflows\/|\.gitlab\/ci\/|checks\/)/.test(d)));
35
+ CI_FILES.add(PRODUCT_LINK);
36
+ const isCiItem = (item) => CI_FILES.has(item);
37
+ // A list of files, short: the first three, then how many more.
38
+ const few = (items) => (items.length > 3 ? `${items.slice(0, 3).join(', ')} and ${items.length - 3} more` : items.join(', '));
39
+
40
+ // Three answers: true, false, or null (not known). A rule list read in full proves a rule is absent; a full
41
+ // page proves nothing past it. Classic protection proven absent ('none') holds nothing.
42
+ const inRules = (s, pred) => (s.rules === null ? null : s.rules.some(pred) ? true : s.rulesFull ? null : false);
43
+ const inClassic = (s, read) => (s.classic === 'none' ? false : s.classic === null ? null : read(s.classic));
44
+ const either = (a, b) => (a === true || b === true ? true : a === false && b === false ? false : null);
45
+ const bool = (v) => (typeof v === 'boolean' ? v : null);
46
+
47
+ // The checks this repo should require on GitHub: the Product's (with its verified-commits workflow when the
48
+ // file is there), or a code repo's.
49
+ function githubJobs(root, t) {
50
+ if (t.kind === 'code') return [...REQUIRED_CHECKS.github.code];
51
+ const verified = exists(path.join(root, '.github/workflows/yad-verified-commits.yml'));
52
+ return [...REQUIRED_CHECKS.github.product, ...(verified ? REQUIRED_CHECKS.github.productVerified : [])];
53
+ }
54
+
55
+ // GitLab runs a fragment in the merge request pipeline only when the project's CI file includes it: the path
56
+ // the project sets (`ci_config_path`), or `.gitlab-ci.yml` at the top of the git repo when that setting is
57
+ // empty. Read as text, as it is on disk here, with comments taken off, and only its TOP-LEVEL `include:`
58
+ // (a line at column 0): a single value (`include: '<path>'`), or the block under it — each list item that
59
+ // is a local path (`- local: '<path>'`, `- '<path>'`), or a `local:` map. The same path anywhere else (a child
60
+ // pipeline's `trigger: include:`, `rules: changes:`, a script) is not an include; an `include:` (or an item of
61
+ // it) written in [ ] or { } — YAML's flow style — is not read (unknown), and an item that names
62
+ // another project, a URL, a template or a component is not this repo's fragment: each reads as missing — a
63
+ // gap, never a false ok. An item with its own `rules:` runs only when they match: `gated`, not known. A CI
64
+ // file kept in another project or at a URL, or a setting that was not read, cannot be followed: `unreadable`.
65
+ const bare = (v) => v.trim().replace(/^(['"])(.*)\1$/, '$2').replace(/^\//, '');
66
+ export function topIncludes(text) {
67
+ const lines = text.split('\n').map((l) => l.replace(/(^|\s)#.*$/, '').replace(/\s+$/, ''));
68
+ const at = lines.findIndex((l) => /^include:/.test(l));
69
+ const included = new Set();
70
+ const gated = new Set();
71
+ if (at < 0) return { included, gated };
72
+ // Two top-level `include:` keys: GitLab's YAML reader keeps only the last, a merge accident yad does not
73
+ // untangle — not known.
74
+ if (lines.filter((l) => /^include:/.test(l)).length > 1) return { included, gated, twice: true };
75
+ const inline = lines[at].slice('include:'.length).trim();
76
+ // A single value on the key's own line. A list or map in flow style (`[a, b]`, `{local: a}`) is not read:
77
+ // not known, with no rewrite to get wrong.
78
+ if (inline) {
79
+ if (inline.startsWith('[') || inline.startsWith('{')) return { included, gated, flow: true };
80
+ included.add(bare(inline));
81
+ return { included, gated };
82
+ }
83
+ const block = [];
84
+ // The block: indented lines, or list items at column 0 (YAML allows a list level with its key).
85
+ for (const l of lines.slice(at + 1)) { if (l && !/^\s/.test(l) && !/^-/.test(l)) break; if (l) block.push(l); }
86
+ // Split into items: a line starting `-` at the block's own depth begins one; a block with none is one map.
87
+ const depth = Math.min(...block.map((l) => l.match(/^\s*/)[0].length));
88
+ const items = [];
89
+ for (const l of block) {
90
+ if (l.match(/^\s*/)[0].length === depth && /^\s*-(\s|$)/.test(l)) items.push([l.replace(/^\s*-\s?/, ' '.repeat(depth + 2))]);
91
+ else if (items.length) items[items.length - 1].push(l);
92
+ else items.push([l]);
93
+ }
94
+ // Flow style anywhere in the block (`[a, b]` or `{local: a}` on the next line, or as a list item): not read.
95
+ // An item's value starts on its first line that is not blank (a `-` may stand alone on its own line).
96
+ const first = (item) => item.map((l) => l.trim()).find(Boolean) ?? '';
97
+ if (items.some((item) => /^[[{]/.test(first(item)))) return { included, gated, flow: true };
98
+ for (const item of items) {
99
+ const text = item.join('\n');
100
+ if (/^\s*(project|remote|template|component|file):/m.test(text)) continue;
101
+ const filled = item.filter((l) => l.trim());
102
+ const local = text.match(/^\s*local:\s*(.+)$/m)?.[1] ?? (filled.length === 1 && !/:/.test(filled[0]) ? filled[0] : null);
103
+ if (!local) continue;
104
+ (/^\s*rules:/m.test(text) ? gated : included).add(bare(local));
105
+ }
106
+ return { included, gated };
107
+ }
108
+ function missingIncludes(dir, fragments, ciPath) {
109
+ // Not read: GitLab may read another file than the one here.
110
+ if (ciPath === undefined) return { unreadable: 'which CI file GitLab reads is not known (the project\'s settings were not read)', missing: fragments };
111
+ const custom = typeof ciPath === 'string' && ciPath.trim() && ciPath.trim() !== '.gitlab-ci.yml' ? ciPath.trim() : null;
112
+ if (custom && (/@|:\/\//.test(custom) || path.isAbsolute(custom) || custom.split(/[\\/]/).includes('..'))) return { unreadable: `GitLab reads the CI file ${custom}, which yad cannot read here`, missing: fragments };
113
+ const top = run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
114
+ const file = custom || '.gitlab-ci.yml';
115
+ let text;
116
+ try { text = fs.readFileSync(path.join(top.ok ? top.stdout.trim() : dir, file), 'utf8'); } catch { return { noRoot: true, file, missing: fragments, gated: [] }; }
117
+ const { included, gated, twice, flow } = topIncludes(text);
118
+ if (twice) return { unreadable: `${file} has two top-level \`include:\` keys (GitLab reads only the last), which yad does not untangle`, missing: fragments };
119
+ if (flow) return { unreadable: `${file} writes its top-level \`include:\` (or an item of it) in [ ] or { } — YAML's flow style, which yad does not read`, missing: fragments };
120
+ return { noRoot: false, file, missing: fragments.filter((f) => !included.has(f) && !gated.has(f)), gated: fragments.filter((f) => !included.has(f) && gated.has(f)) };
121
+ }
122
+
123
+ // yad's CI files, from the same plan `yad check` makes. Nothing is written. The files are read on disk here:
124
+ // CI reads them from the branch, so they must be committed too.
125
+ function filesRow(add, root, t, s) {
126
+ let actions;
127
+ let dir = root;
128
+ if (t.kind === 'product') {
129
+ // A verified ledger with no platform set: yad wired none of the Product's CI, though a platform is there.
130
+ if (!t.wired && t.wantsVerified && s.protection.platform) {
131
+ add('files', 'gap', `the Product's ledger is set to verified, but .sdlc/product.json names no platform, so yad wired none of its CI files`, {
132
+ actor: 'agent', steps: [`Set "platform": "${s.protection.platform}" in the Product's .sdlc/product.json (through a pull request), then run \`yad check --fix\`.`],
133
+ });
134
+ return;
135
+ }
136
+ if (!t.wired) {
137
+ add('files', 'ok', t.wantsVerified
138
+ ? 'the Product\'s ledger is set to verified, but with no platform set it is kept locally, so yad runs no CI on it'
139
+ : 'the Product keeps its ledger locally, so yad runs no CI on it');
140
+ return;
141
+ }
142
+ actions = productActions(root);
143
+ } else {
144
+ const judged = judgeRepo(root, t.entry);
145
+ if (!runnable(judged)) {
146
+ // A clone yad can make is offered; an entry yad refuses (no path, outside the workspace…) says why.
147
+ if (judged.state === 'refused') add('files', 'unknown', `its workflow files were not read: ${forTerminal(judged.reason)}`);
148
+ else add('files', 'unknown', 'this repo is not cloned here, so its workflow files were not read', { actor: 'agent', commands: [`yad repo clone ${asArg(t.name)}`] });
149
+ return;
150
+ }
151
+ dir = path.resolve(root, t.entry.path);
152
+ // yad wires a repo's CI by the platform its entry names; one told only from the git URL got none.
153
+ const seen = s.protection.platform;
154
+ // No platform named and none in the URL: yad wired only the gate scripts, with no workflow to run them.
155
+ if (!t.target.platform && !seen) {
156
+ add('files', 'unknown', 'no platform is set for this repo, so yad wires only gate scripts here and no workflow runs them (the platform row says more)');
157
+ return;
158
+ }
159
+ if (!t.target.platform && seen) {
160
+ add('files', 'gap', `this repo's entry in .sdlc/repos.json names no platform, so yad wired none of its ${seen === 'gitlab' ? 'GitLab' : 'GitHub'} CI files`, {
161
+ actor: 'agent',
162
+ steps: [`Add "platform": "${seen}" to its entry in the Product's .sdlc/repos.json (through a pull request on the Product), then run \`yad check --fix\`.`],
163
+ });
164
+ return;
165
+ }
166
+ actions = repoActions(root, t.entry);
167
+ }
168
+ const ci = actions.filter((a) => isCiItem(a.item));
169
+ const of = (...states) => ci.filter((a) => states.includes(a.status)).map((a) => forTerminal(a.item));
170
+ const missing = of('missing', 'new');
171
+ const outdated = of('outdated');
172
+ const modified = of('modified');
173
+ const other = ci.filter((a) => !['ok', 'missing', 'new', 'outdated', 'modified'].includes(a.status)).map((a) => forTerminal(a.item));
174
+ const commit = 'Commit and push them through a pull request (or `yad check --fix --open-pr`).';
175
+ if (missing.length) add('files', 'gap', `yad's CI files are missing: ${few(missing)}`, { actor: 'agent', commands: ['yad check --fix'], steps: [commit] });
176
+ if (outdated.length) add('files', 'gap', `yad's CI files are older than this yadflow: ${few(outdated)}`, { actor: 'agent', commands: ['yad update'], steps: [commit] });
177
+ if (modified.length) {
178
+ add('files', 'gap', `yad's CI files were edited by hand: ${few(modified)}`, {
179
+ actor: 'agent',
180
+ steps: ['Ask the person first: `yad update --overwrite-local` puts yad\'s copy back and saves the edit beside it.', 'If yad\'s own file is wrong, report it with `yad report` — do not edit it.'],
181
+ });
182
+ }
183
+ if (other.length) add('files', 'gap', `yad's CI files need attention: ${few(other)}`, { actor: 'agent', commands: ['yad check'] });
184
+ // GitLab: the fragments are on disk; the root pipeline must include them, or no yad job runs.
185
+ let noInclude = false;
186
+ if (t.target.platform === 'gitlab') {
187
+ const fragments = ci.filter((a) => a.item.startsWith('.gitlab/ci/') && !missing.includes(forTerminal(a.item))).map((a) => a.item);
188
+ // The setting counts only as GitLab gave it: absent (not read, or left out of the answer) is not "empty".
189
+ const ciPath = s.project && Object.hasOwn(s.project, 'ci_config_path') ? (s.project.ci_config_path ?? '') : undefined;
190
+ const inc = fragments.length ? missingIncludes(dir, fragments, ciPath) : { missing: [] };
191
+ if (inc.unreadable) {
192
+ noInclude = true;
193
+ add('files', 'unknown', `${forTerminal(inc.unreadable)}, so whether it includes yad's jobs is not known here`, {
194
+ actor: 'agent', steps: ['Check that the pipeline of a merge request runs yad\'s jobs (their names start with yad-).'],
195
+ });
196
+ } else if (inc.gated.length && !inc.missing.length) {
197
+ noInclude = true;
198
+ add('files', 'unknown', `${forTerminal(inc.file)} includes ${few(inc.gated.map(forTerminal))} only under its own \`rules:\`, so whether GitLab runs those jobs depends on a condition yad does not read`, {
199
+ actor: 'agent', steps: ['Include yad\'s files with no `rules:` of their own, or check that the pipeline of every merge request runs yad\'s jobs.'],
200
+ });
201
+ } else if (inc.missing.length) {
202
+ noInclude = true;
203
+ const file = forTerminal(inc.file);
204
+ add('files', 'gap', inc.noRoot
205
+ ? `there is no ${file}, so GitLab runs none of yad's jobs`
206
+ : `${file} does not include ${few(inc.missing.map(forTerminal))}, so GitLab does not run those jobs (as ${file} is on disk here)`, {
207
+ actor: 'agent',
208
+ steps: [inc.noRoot
209
+ ? `Create ${file}, through a pull request, with a top-level \`include:\` key and these lines under it, each indented two spaces:`
210
+ : `In ${file}, through a pull request: under its top-level \`include:\` (add the key if there is none), add these lines as list items, at the same indent as any items already there. If \`include:\` is not a list yet, first make it one without changing what it includes: move its value, exactly as written (quotes and braces too), to the first list item — a value on the key's own line goes on the next line after \`- \` (\`include: 'a.yml'\` becomes \`include:\` then \` - 'a.yml'\`); a map spread over several lines gets \`- \` before its first line, and every other line of it moves two more spaces in.`,
211
+ ...inc.missing.map((f) => `- local: '${forTerminal(f)}'`),
212
+ 'If it is included another way (a nested or remote include), yad cannot see it: check the pipeline of a merge request runs yad\'s jobs.'],
213
+ });
214
+ }
215
+ }
216
+ if (!missing.length && !outdated.length && !modified.length && !other.length && !noInclude) {
217
+ add('files', 'ok', ci.length ? `yad's ${ci.length} CI files are current on disk here (CI reads them from the branch: commit them)` : 'yad has no CI files for this repo');
218
+ }
219
+ }
220
+
221
+ // Every row a repo would have, for a run that could not read the platform: each is `unknown` with the reason.
222
+ function rowIds(t, platform, solo) {
223
+ return [
224
+ 'protected',
225
+ ...(t.ciRuns ? ['required-checks'] : []),
226
+ ...(platform === 'gitlab' && t.ciRuns ? ['skipped-pipelines'] : []),
227
+ ...(platform === 'gitlab' && !(t.kind === 'product' && t.ciRuns) ? ['direct-push'] : []),
228
+ 'force-push', 'deletion',
229
+ ...(!solo ? ['stale-approvals'] : []),
230
+ ...(platform === 'gitlab' ? ['discussions'] : []),
231
+ ...(t.kind === 'code' || t.ciRuns ? ['signed-commits'] : []),
232
+ ];
233
+ }
234
+
235
+ // The platform's rows for one repo.
236
+ function platformRows(add, root, t, s, { solo }) {
237
+ const p = s.protection;
238
+ if (!p.known) {
239
+ // No platform at all: nothing holds a merge there — never a quiet ok.
240
+ if (p.kind === 'no-platform' && !t.target.platform) {
241
+ add('platform', 'unknown', 'no platform (GitHub or GitLab) is set, and none can be told from the git URL: nothing on a platform holds a merge here', {
242
+ actor: 'agent', steps: [t.kind === 'product' ? 'Ask the person which platform the Product is on, then set "platform" and "git_url" in its .sdlc/product.json through a pull request (or keep the Product local, with no merge to hold).' : 'Set "platform" and "git_url" for this repo in the Product\'s .sdlc/repos.json, through a pull request.'],
243
+ });
244
+ return;
245
+ }
246
+ // The hint is doctor's, which names itself; here the command to run again is this one.
247
+ const hint = protectionLine(p, { name: t.name, solo }).hint?.replaceAll('`yad doctor`', '`yad ci check`');
248
+ const why = forTerminal(p.why || 'the platform could not be read');
249
+ for (const id of rowIds(t, p.platform, solo)) add(id, 'unknown', why, id === 'protected' && hint ? { actor: 'person', steps: [hint] } : null);
250
+ return;
251
+ }
252
+ const branch = forTerminal(p.branch);
253
+ const web = `https://${p.host}/${forTerminal(p.repo)}`;
254
+ const gh = p.platform === 'github';
255
+ const rulesPage = gh ? `${web}/settings/rules` : `${web}/-/settings/repository`;
256
+ const mrPage = `${web}/-/settings/merge_requests`;
257
+ const settings = (url, steps) => ({ actor: 'person', where: 'settings', url, steps: [...steps, 'Then run `yad ci check` again.'] });
258
+ // A verified Product's gate bot pushes the ledger commit straight to the default branch.
259
+ const bot = t.kind === 'product' && t.ciRuns;
260
+ const protectSteps = gh
261
+ ? [`Open ${rulesPage} → New ruleset → New branch ruleset: target the default branch (${branch}), set Enforcement to Active, and turn on the rules the other rows name ("Require a pull request before merging", "Require status checks to pass", "Block force pushes", "Restrict deletions").`,
262
+ ...(bot ? ['Add the owner of the gate-sync token (a GitHub App, or the person whose token SDLC_GATE_TOKEN is) to the ruleset\'s bypass list, or the ledger never advances — see "The gate bot must be able to push" in docs/branch-protection.md.'] : [])]
263
+ : [`Open ${rulesPage} → Protected branches → protect ${branch}: "Allowed to merge" Developers + Maintainers; "Allowed to push and merge" ${bot ? 'the role the gate token (SDLC_GATE_TOKEN) has, and no wider — the gate bot pushes the ledger there' : 'No one'}; "Allowed to force push" off.`];
264
+
265
+ // Protected, and the approvals the mode asks for. A protection GitHub's own answers disagree about is not known.
266
+ if (p.protected === false) add('protected', 'gap', `${branch} is not protected: anyone with write access can push to it`, settings(rulesPage, protectSteps));
267
+ else if (p.protected !== true) add('protected', 'unknown', `whether ${branch} is protected is not known: ${forTerminal(p.protectedWhy || 'the platform\'s answers disagree')}`, settings(rulesPage, protectSteps));
268
+ else if (p.approvals === null) add('protected', 'unknown', `${branch} is protected; the approval rules were not read: ${forTerminal(p.approvalsWhy || 'no answer')}`);
269
+ else if (solo && p.approvals > 0) add('protected', 'gap', `${branch} needs ${p.approvals} approval(s) before a merge: in solo mode that blocks your own merge`, settings(gh ? rulesPage : mrPage, ['Set the required approvals to 0 (solo mode).']));
270
+ else if (!solo && p.approvals === 0) {
271
+ add('protected', 'gap', `${branch} is protected, but no approval is needed before a merge`, settings(gh ? rulesPage : mrPage, gh
272
+ ? ['In the branch ruleset, turn on "Require a pull request before merging" with 1 or more approvals.']
273
+ : ['Merge request approvals → an approval rule with 1 or more approvals (GitLab Premium; on Free an approval never blocks a merge).']));
274
+ } else add('protected', 'ok', solo ? `${branch} is protected (solo mode: no approval needed)` : `${branch} is protected; ${p.atLeast ? 'at least ' : ''}${p.approvals} approval(s) needed before a merge`);
275
+
276
+ if (gh) githubRows(add, root, t, s, { branch, web, rulesPage, settings, solo, protectSteps });
277
+ else gitlabRows(add, t, s, { branch, rulesPage, mrPage, settings, solo });
278
+ }
279
+
280
+ function githubRows(add, root, t, s, { branch, web, rulesPage, settings, solo, protectSteps }) {
281
+ const noClassic = 'classic branch protection is readable by a repo admin only';
282
+ // Classic protection holds admins only when "Do not allow bypassing the above settings" is on.
283
+ const adminsFree = isPlainObject(s.classic) && s.classic.enforce_admins?.enabled === false;
284
+ const why = [s.rules === null ? 'the branch\'s rules were not read' : s.rulesFull ? 'the branch has 100 or more rules and only the first 100 were read' : null, s.classic === null ? noClassic : null].filter(Boolean).join('; ');
285
+
286
+ if (t.ciRuns) {
287
+ const jobs = githubJobs(root, t);
288
+ const required = new Set();
289
+ for (const r of s.rules || []) {
290
+ if (r?.type !== 'required_status_checks') continue;
291
+ for (const x of Array.isArray(r.parameters?.required_status_checks) ? r.parameters.required_status_checks : []) if (typeof x?.context === 'string') required.add(x.context);
292
+ }
293
+ if (isPlainObject(s.classic)) {
294
+ const rs = s.classic.required_status_checks;
295
+ for (const x of Array.isArray(rs?.contexts) ? rs.contexts : []) if (typeof x === 'string') required.add(x);
296
+ for (const x of Array.isArray(rs?.checks) ? rs.checks : []) if (typeof x?.context === 'string') required.add(x.context);
297
+ }
298
+ const missing = jobs.filter((j) => !required.has(j));
299
+ const steps = [`In the branch ruleset, turn on "Require status checks to pass" and add: ${missing.join(', ')}.`, 'GitHub offers a check only after it has run once: open one pull request first.',
300
+ ...(t.kind === 'product' ? protectSteps.slice(1) : [])];
301
+ // Who may bypass: a ruleset's bypass list is not read; classic protection says whether admins are held.
302
+ if (!missing.length) add('required-checks', 'ok', `all ${jobs.length} of yad's checks must pass before a merge (who is on a ruleset's bypass list is not read${adminsFree ? '; classic protection lets admins bypass them' : ''})`);
303
+ else if (why) add('required-checks', 'unknown', `not seen as required: ${missing.join(', ')} (${why})`, settings(rulesPage, steps));
304
+ else add('required-checks', 'gap', `not required before a merge: ${missing.join(', ')} — a pull request can merge with these failing`, settings(rulesPage, steps));
305
+ }
306
+
307
+ const row = (id, ruleType, classicKey, okText, gapText, unknownText, step) => {
308
+ const byRules = inRules(s, (r) => r?.type === ruleType);
309
+ const blocked = either(byRules, inClassic(s, (cl) => (typeof cl[classicKey]?.enabled === 'boolean' ? !cl[classicKey].enabled : null)));
310
+ // Admins pass classic protection's block only when no ruleset blocks it too.
311
+ if (blocked === true) add(id, 'ok', `${okText} (who is on a ruleset's bypass list is not read${adminsFree && byRules !== true ? '; classic protection lets admins bypass it' : ''})`);
312
+ else if (blocked === false) add(id, 'gap', gapText, settings(rulesPage, [step]));
313
+ else add(id, 'unknown', `${unknownText} (${why})`, settings(rulesPage, [step]));
314
+ };
315
+ row('force-push', 'non_fast_forward', 'allow_force_pushes', `force pushes to ${branch} are blocked`, `${branch} allows a force push: history on it can be rewritten`, `not known whether ${branch} allows a force push`, 'In the branch ruleset, turn on "Block force pushes".');
316
+ row('deletion', 'deletion', 'allow_deletions', `${branch} cannot be deleted`, `${branch} can be deleted`, `not known whether ${branch} can be deleted`, 'In the branch ruleset, turn on "Restrict deletions".');
317
+
318
+ if (!solo) {
319
+ const stale = either(inRules(s, (r) => r?.type === 'pull_request' && r.parameters?.dismiss_stale_reviews_on_push === true),
320
+ inClassic(s, (cl) => (isPlainObject(cl.required_pull_request_reviews) ? cl.required_pull_request_reviews.dismiss_stale_reviews === true : false)));
321
+ const step = 'In the branch ruleset\'s pull request rule, turn on "Dismiss stale pull request approvals when new commits are pushed".';
322
+ if (stale === true) add('stale-approvals', 'ok', 'an approval is dismissed when new commits are pushed');
323
+ else add('stale-approvals', 'suggest', stale === false ? 'an approval stays after new commits are pushed' : `not known whether an approval is dismissed on a new push (${why})`, settings(rulesPage, [step]));
324
+ }
325
+
326
+ signedRow(add, t, either(inRules(s, (r) => r?.type === 'required_signatures'), inClassic(s, (cl) => bool(cl.required_signatures?.enabled))), {
327
+ url: rulesPage, settings, why, on: 'In the branch ruleset, turn on "Require signed commits".',
328
+ off: `In the branch ruleset (${rulesPage}) and in classic branch protection (${web}/settings/branches), turn off "Require signed commits".`,
329
+ });
330
+ }
331
+
332
+ function gitlabRows(add, t, s, { branch, rulesPage, mrPage, settings, solo }) {
333
+ const pr = s.project;
334
+ const p = s.protection;
335
+ const unread = 'the project\'s settings were not read';
336
+ if (t.ciRuns) {
337
+ const v = bool(pr?.only_allow_merge_if_pipeline_succeeds);
338
+ const step = 'Merge checks → turn on "Pipelines must succeed".';
339
+ // Which jobs the pipeline runs is the `files` row's (the root .gitlab-ci.yml must include yad's).
340
+ if (v === true) add('required-checks', 'ok', 'a merge needs a passing pipeline (the files row says whether yad\'s jobs are in it)');
341
+ else if (v === false) add('required-checks', 'gap', '"Pipelines must succeed" is off: a merge request can merge with yad\'s checks failing', settings(mrPage, [step]));
342
+ else add('required-checks', 'unknown', `not known whether "Pipelines must succeed" is on (${unread})`, settings(mrPage, [step]));
343
+ const skipped = bool(pr?.allow_merge_on_skipped_pipeline);
344
+ const skipStep = 'Merge checks → turn off "Skipped pipelines are considered successful".';
345
+ if (skipped === false) add('skipped-pipelines', 'ok', 'a skipped pipeline does not count as passed');
346
+ else if (skipped === true) add('skipped-pipelines', 'gap', 'a skipped pipeline counts as passed, so a merge can skip yad\'s checks', settings(mrPage, [skipStep]));
347
+ else add('skipped-pipelines', 'unknown', `not known whether a skipped pipeline counts as passed (${unread})`, settings(mrPage, [skipStep]));
348
+ }
349
+
350
+ // The project's protected-branch entries for this branch. In a person's own namespace they are the whole
351
+ // answer; in a group's project a group rule (not in this list) can say otherwise, so "no" proves nothing.
352
+ const ownNamespace = pr?.namespace?.kind === 'user';
353
+ const entries = s.matched;
354
+ // A full page proves nothing past it: a rule on the next page could allow more. Gaps on it still count.
355
+ const listed = entries !== null && !s.matchedFull;
356
+ const groupWhy = ownNamespace ? null : 'a group\'s protected-branch rule, which this project\'s list does not show, can allow it';
357
+ const protectFirst = `Protected branches → protect ${branch}`;
358
+
359
+ // Force push: allowed when any matching rule allows it; blocked only when every rule is read and blocks it.
360
+ const fpStep = p.protected === false ? `${protectFirst}, with "Allowed to force push" off.` : `Protected branches → ${branch}: turn off "Allowed to force push".`;
361
+ if (p.protected === false) add('force-push', 'gap', `${branch} is not protected, so a force push is allowed`, settings(rulesPage, [fpStep]));
362
+ else if (!listed) add('force-push', 'unknown', `not known whether a force push is allowed (${entries === null ? 'the protected branches were not read' : 'the project has 100 or more protected branches and only the first 100 were read'})`, settings(rulesPage, [fpStep]));
363
+ else if (entries.length && entries.every((m) => m?.allow_force_push === true)) add('force-push', 'gap', `${branch} allows a force push: history on it can be rewritten`, settings(rulesPage, [fpStep]));
364
+ // Several rules that disagree: yad does not decide which one GitLab applies.
365
+ else if (entries.some((m) => m?.allow_force_push === true)) add('force-push', 'unknown', `not known whether a force push is allowed: the rules that match ${branch} disagree, and yad does not decide which one GitLab applies`, settings(rulesPage, [fpStep]));
366
+ else if (entries.length && entries.every((m) => m?.allow_force_push === false) && ownNamespace) add('force-push', 'ok', `force pushes to ${branch} are blocked`);
367
+ else add('force-push', 'unknown', `not known whether a force push is allowed (${entries.length ? groupWhy : `${branch} is protected by a rule this project's list does not show, such as a group's`})`, settings(rulesPage, [fpStep]));
368
+
369
+ // Direct push: a protected branch still lets "Allowed to push and merge" push past every merge check. The
370
+ // most permissive matching rule wins. A verified Product's gate token must push there, so it is not asked.
371
+ if (!(t.kind === 'product' && t.ciRuns)) {
372
+ const pushStep = `${p.protected === false ? `${protectFirst}, with "Allowed to push and merge" No one.` : `Protected branches → ${branch}: set "Allowed to push and merge" to No one.`} (Then \`yad update --push\` cannot push there: use \`yad update --open-pr\`.)`;
373
+ // The most permissive matching rule wins, so one entry on the first page that lets someone push proves it.
374
+ const levels = entries ? entries.flatMap((m) => (Array.isArray(m?.push_access_levels) ? m.push_access_levels : [])) : [];
375
+ const someone = levels.some((l) => (typeof l?.access_level === 'number' && l.access_level > 0) || l?.user_id || l?.group_id || l?.deploy_key_id);
376
+ const noOne = listed && entries.length && entries.every((m) => Array.isArray(m?.push_access_levels) && m.push_access_levels.length && m.push_access_levels.every((l) => l?.access_level === 0 && !l.user_id && !l.group_id && !l.deploy_key_id));
377
+ const status = solo ? 'suggest' : 'gap';
378
+ if (p.protected === false) add('direct-push', status, `${branch} is not protected: anyone with write access can push to it, past every merge check`, settings(rulesPage, [pushStep]));
379
+ else if (someone) add('direct-push', status, `"Allowed to push and merge" on ${branch} lets someone push straight to it, past every merge check`, settings(rulesPage, [pushStep]));
380
+ else if (noOne && ownNamespace) add('direct-push', 'ok', `no one can push straight to ${branch}: every change comes through a merge request`);
381
+ else add('direct-push', 'unknown', `not known who can push straight to ${branch} (${entries === null ? 'the protected branches were not read' : !listed ? 'the project has 100 or more protected branches and only the first 100 were read' : entries.length ? groupWhy : 'it is protected by a rule this project\'s list does not show, such as a group\'s'})`, settings(rulesPage, [pushStep]));
382
+ }
383
+
384
+ // GitLab never deletes a project's default branch; a protected branch is deleted only by a Maintainer, by hand.
385
+ if (p.platformDefault && p.branch === p.platformDefault) add('deletion', 'ok', `${branch} is the project's default branch, which GitLab does not let anyone delete`);
386
+ else if (p.protected === true) add('deletion', 'ok', `${branch} is protected: only a Maintainer can delete it, by hand in GitLab`);
387
+ else add('deletion', 'gap', `${branch} is not protected, so it can be deleted`, settings(rulesPage, [`${protectFirst}.`]));
388
+
389
+ if (!solo) {
390
+ const reset = bool(s.approvals?.reset_approvals_on_push);
391
+ const step = 'Merge request approvals → turn on "Remove all approvals when commits are added to the source branch".';
392
+ if (reset === true) add('stale-approvals', 'ok', 'approvals are removed when new commits are added');
393
+ else add('stale-approvals', 'suggest', reset === false ? 'approvals stay when new commits are added' : 'not known whether approvals are removed on a new push (the approval settings need GitLab Premium, or could not be read)', settings(mrPage, [step]));
394
+ }
395
+ const disc = bool(pr?.only_allow_merge_if_all_discussions_are_resolved);
396
+ const discStep = 'Merge checks → turn on "All threads must be resolved".';
397
+ if (disc === true) add('discussions', 'ok', 'every thread must be resolved before a merge');
398
+ else add('discussions', 'suggest', disc === false ? 'a merge request can merge with open threads' : `not known whether threads must be resolved (${unread})`, settings(mrPage, [discStep]));
399
+
400
+ const signed = s.pushRule === 'none' ? false : s.pushRule === null ? null : bool(s.pushRule.reject_unsigned_commits) ?? false;
401
+ signedRow(add, t, signed, {
402
+ url: rulesPage, settings, why: 'the push rules need GitLab Premium, or could not be read',
403
+ on: 'Push rules → turn on "Reject unsigned commits".', off: 'Push rules → turn off "Reject unsigned commits".',
404
+ });
405
+ }
406
+
407
+ // "Require signed commits": a gap when it is on for the Product (CI's ledger commits are unsigned), a
408
+ // suggestion for a code repo. A Product that runs no yad CI writes no bot commits, so it is not asked.
409
+ function signedRow(add, t, on, { url, settings, why, on: turnOn, off: turnOff }) {
410
+ if (t.kind === 'product') {
411
+ if (!t.ciRuns) return;
412
+ if (on === true) add('signed-commits', 'gap', '"Require signed commits" is on: yad\'s CI writes the ledger in unsigned commits, so every gate would stop', settings(url, [turnOff]));
413
+ else if (on === false) add('signed-commits', 'ok', '"Require signed commits" is off, as the Product needs (yad\'s CI writes the ledger in unsigned commits)');
414
+ else add('signed-commits', 'unknown', `not known whether "Require signed commits" is on (${why}): it must be off on the Product`, settings(url, [turnOff]));
415
+ return;
416
+ }
417
+ if (on === true) add('signed-commits', 'ok', 'commits must be signed');
418
+ else add('signed-commits', 'suggest', on === false ? 'unsigned commits are accepted' : `not known whether commits must be signed (${why})`, settings(url, [turnOn]));
419
+ }
420
+
421
+ // The repos to check: one by name, or the Product and every registered repo.
422
+ export function ciTargets(root, { repo = null } = {}) {
423
+ const productConfig = readJSON(productConfigPath(root), null);
424
+ const config = isPlainObject(productConfig) ? productConfig : {};
425
+ const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
426
+ const entries = (Array.isArray(registry?.repos) ? registry.repos : []).filter((r) => isPlainObject(r) && typeof r.name === 'string' && r.name);
427
+ const origin = (cwd) => run('git', ['remote', 'get-url', 'origin'], { cwd }).stdout || null;
428
+ const branchOf = (x) => (typeof x.default_branch === 'string' && x.default_branch ? x.default_branch : null);
429
+ const code = (entry) => {
430
+ const onDisk = typeof entry.path === 'string' && entry.path && runnable(judgeRepo(root, entry));
431
+ return {
432
+ name: entry.name, kind: 'code', entry, ciRuns: true,
433
+ target: { platform: entry.platform || null, gitUrl: (typeof entry.git_url === 'string' && entry.git_url) || (onDisk ? origin(path.resolve(root, entry.path)) : null), branch: branchOf(entry) },
434
+ };
435
+ };
436
+ if (repo !== null) {
437
+ const hit = entries.find((e) => e.name === repo);
438
+ return hit ? { targets: [code(hit)] } : { unknownRepo: repo, names: entries.map((e) => e.name) };
439
+ }
440
+ const wired = isVerifiedLedger(config);
441
+ const product = {
442
+ name: 'Product', kind: 'product', wired, ciRuns: wired,
443
+ // The verified ledger asked for, by its name or its older spellings, whether or not a platform is set.
444
+ wantsVerified: config.ledger === 'verified' || (typeof config.ledger !== 'string' && (config.bridge_enabled === true || config.bridge === true)),
445
+ target: { platform: config.platform || null, gitUrl: config.git_url || origin(root), branch: branchOf(config) },
446
+ };
447
+ return { targets: [product, ...entries.map(code)] };
448
+ }
449
+
450
+ export function ciCheck(root, { repo = null, runner, env } = {}) {
451
+ const picked = ciTargets(root, { repo });
452
+ if (picked.unknownRepo !== undefined) return picked;
453
+ const productConfig = readJSON(productConfigPath(root), null);
454
+ const solo = isSolo(isPlainObject(productConfig) ? productConfig : null);
455
+ const opts = { ...(runner ? { runner } : {}), ...(env ? { env } : {}), authCache: new Map() };
456
+ const repos = picked.targets.map((t) => {
457
+ const findings = [];
458
+ const add = (id, status, message, fix = null) => findings.push({ id, status, message, ...(fix ? { fix } : {}) });
459
+ const settings = readCiSettings(t.target, opts);
460
+ filesRow(add, root, t, settings);
461
+ platformRows(add, root, t, settings, { solo });
462
+ return { name: t.name, kind: t.kind, findings };
463
+ });
464
+ const all = repos.flatMap((r) => r.findings);
465
+ const count = (st) => all.filter((f) => f.status === st).length;
466
+ return { repos, summary: { gaps: count('gap'), suggestions: count('suggest'), unknown: count('unknown'), complete: count('unknown') === 0 } };
467
+ }
468
+
469
+ export function runCiCheck(root, { repo = null, json = false, runner, env } = {}) {
470
+ const r = ciCheck(root, { repo, runner, env });
471
+ if (r.unknownRepo !== undefined) return r;
472
+ if (!json) {
473
+ log(c.bold('\nyad ci check'));
474
+ const mark = { ok, gap: fail, suggest: warn, unknown: info };
475
+ for (const repoResult of r.repos) {
476
+ log(c.bold(`\n${forTerminal(repoResult.name)}`));
477
+ for (const f of repoResult.findings) {
478
+ mark[f.status](`${f.id}: ${f.status === 'unknown' ? 'not known — ' : ''}${f.message}`);
479
+ if (f.fix?.url) log(c.dim(` ${f.fix.url}`));
480
+ for (const cmd of f.fix?.commands || []) hand(cmd);
481
+ for (const s of f.fix?.steps || []) log(c.dim(` ${s}`));
482
+ }
483
+ }
484
+ const { gaps, unknown } = r.summary;
485
+ log('');
486
+ if (gaps) log(c.bold(`${gaps} thing(s) to fix. A platform setting is the person's to change; yad's own files take the command shown. Then run \`yad ci check\` again.`));
487
+ else if (unknown) log(c.bold(`${unknown} item(s) not read — not cleared.`));
488
+ else ok('yad\'s checks will hold a merge on every repo checked');
489
+ }
490
+ if (r.summary.gaps) process.exitCode = 1;
491
+ return r;
492
+ }
package/cli/commit.mjs CHANGED
@@ -109,6 +109,7 @@ export async function runCommit(root, opts = {}) {
109
109
  type: opts.type, subject: opts.message, task,
110
110
  contractChange: !!opts.contractChange, ai: opts.ai || 'none',
111
111
  override: opts.manual ? String(opts.reason) : null,
112
+ body: typeof opts.body === 'string' ? opts.body : '',
112
113
  });
113
114
  } catch (e) { fail(e.message); process.exitCode = 1; return; }
114
115
 
package/cli/dial.mjs CHANGED
@@ -16,7 +16,7 @@ import path from 'node:path';
16
16
 
17
17
  import { c, fail, hand, info, ok, readJSONStrict, warn, writeJSON, emitJSON } from './lib.mjs';
18
18
  import {
19
- effectiveAdvance, epicRel, epicRoot, epicStories, isGateStep, killSwitchOn, loadAutomation, loadLedger, planKill,
19
+ ACTION_DIALS, effectiveAction, effectiveAdvance, epicRel, epicRoot, epicStories, isGateStep, killSwitchOn, loadAutomation, loadLedger, planKill,
20
20
  planLaneDial, planShapeDial, serializeAutomation, stepDef,
21
21
  } from './epic-state.mjs';
22
22
  import { epicFiles, PROJECT_FILES } from './manifest.mjs';
@@ -77,6 +77,7 @@ function dialShape(root, { step, to, json, bail, automation }) {
77
77
  if (!plan.ok) return bail(plan.message, plan.hint);
78
78
  const after = to ? plan.automation : automation;
79
79
  if (to && plan.changed) writeJSON(path.join(root, PROJECT_FILES.automationConfig), serializeAutomation(plan.automation));
80
+ if (ACTION_DIALS.includes(step)) return actionAnswer({ step, to, json, plan, automation, after });
80
81
  const eff = effectiveAdvance({ id: step }, { ...after, error: automation.error });
81
82
  if (json) {
82
83
  return emitJSON({
@@ -96,6 +97,25 @@ function dialShape(root, { step, to, json, bail, automation }) {
96
97
  if (to && plan.changed) hand(`commit ${PROJECT_FILES.automationConfig} (reverse with \`yad dial ${step} --to ${to === 'auto' ? 'human' : 'auto'}\`)`);
97
98
  }
98
99
 
100
+ // An action's dial (#356): `open-pr` lets the yad-run skill open a task's PR/MR once its checks pass,
101
+ // without asking. The answer has the same keys as a step's, with `scope: 'action'`.
102
+ function actionAnswer({ step, to, json, plan, automation, after }) {
103
+ const eff = effectiveAction({ ...after, error: automation.error }, step);
104
+ if (json) {
105
+ return emitJSON({
106
+ ok: true, scope: 'action', step, set: eff.set, advance: eff.advance, why: eff.why,
107
+ changed: !!to && plan.changed, kill: automation.kill, trust: null, ...errorKey(automation),
108
+ });
109
+ }
110
+ const label = c.bold(step);
111
+ if (!to) ok(`${label} — advance: ${eff.set}${eff.why === 'kill' ? ' (held at human)' : ''}`);
112
+ else if (plan.changed) ok(`${label} set to advance: ${to} for this project`);
113
+ else ok(`${label} was already advance: ${to} — nothing changed`);
114
+ if (eff.set === 'auto') info('a task\'s PR/MR is opened without asking once its checks pass (`yad open-pr --via auto`); the merge is always a person\'s');
115
+ if (killSwitchOn(automation)) warn(heldLine(automation));
116
+ if (to && plan.changed) hand(`commit ${PROJECT_FILES.automationConfig} (reverse with \`yad dial ${step} --to ${to === 'auto' ? 'human' : 'auto'}\`)`);
117
+ }
118
+
99
119
  function dialLane(root, { epic, story, repo, step, to, json, bail, automation }) {
100
120
  if (!story || !repo) return bail(`usage: yad dial ${epic} <story> --repo <name> ${step} [--to auto|human]`);
101
121
  const epicDir = epicRoot(root, epic);
package/cli/docs.mjs CHANGED
@@ -173,7 +173,12 @@ export function pagesWorkflow(platform) {
173
173
  # Edit the skill, not this file.
174
174
  pages:
175
175
  stage: deploy
176
- image: node:20
176
+ # Set the YAD_RUNNER_TAGS / YAD_NODE_VERSION CI/CD variables to route this job to a tag-locked runner or
177
+ # change its Node line; a shell-executor runner ignores \`image:\` and needs Node on its host.
178
+ tags: [$YAD_RUNNER_TAGS]
179
+ image: node:\${YAD_NODE_VERSION}
180
+ variables:
181
+ YAD_NODE_VERSION: "22"
177
182
  rules:
178
183
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
179
184
  script:
@@ -208,7 +213,7 @@ jobs:
208
213
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
209
214
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
210
215
  with:
211
- node-version: 20
216
+ node-version: 22
212
217
  - name: Build the overview + per-epic sites into ./public
213
218
  run: |
214
219
  ${BUILD_PUBLIC.map((l) => ` ${l}`).join('\n')}