@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.10

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 (44) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +218 -53
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/templates/release-auto.yml +16 -3
  14. package/tools/colab +884 -98
  15. package/tools/lib/adopt.js +1 -1
  16. package/tools/lib/audit-cache.js +277 -0
  17. package/tools/lib/batch-stats.js +66 -43
  18. package/tools/lib/ci-cure.js +10 -1
  19. package/tools/lib/claim-comments.js +3 -2
  20. package/tools/lib/codec/decision.d.ts +7 -0
  21. package/tools/lib/codec/decision.js +54 -0
  22. package/tools/lib/codec/hold.d.ts +8 -1
  23. package/tools/lib/codec/hold.js +42 -8
  24. package/tools/lib/codec/release.js +6 -3
  25. package/tools/lib/codec/samples.json +45 -0
  26. package/tools/lib/config-set.js +4 -3
  27. package/tools/lib/cure-diff.js +27 -1
  28. package/tools/lib/decision-record.js +42 -0
  29. package/tools/lib/docs-only.js +47 -0
  30. package/tools/lib/git.js +57 -8
  31. package/tools/lib/grant-policy.js +133 -0
  32. package/tools/lib/instruction-file.js +75 -0
  33. package/tools/lib/instruction-gate.js +179 -0
  34. package/tools/lib/landed-prs.js +58 -0
  35. package/tools/lib/migration-grant.js +29 -5
  36. package/tools/lib/owner-policy.js +110 -0
  37. package/tools/lib/release-cut.js +127 -10
  38. package/tools/lib/release-finalize.js +66 -5
  39. package/tools/lib/ship-batch.js +188 -14
  40. package/tools/lib/ship-handoff.js +212 -0
  41. package/tools/lib/stamp.js +6 -2
  42. package/tools/lib/template-trunk.js +80 -0
  43. package/tools/lib/tree-green.js +21 -4
  44. package/tools/lib/workflow-triggers.js +57 -0
@@ -0,0 +1,212 @@
1
+ 'use strict';
2
+ /**
3
+ * #578 — `colab ship --branch <br> --handoff <comment-url>`: land a branch whose claim lives on
4
+ * ANOTHER machine, from the hand-off its executor already recorded, without `--force`.
5
+ *
6
+ * The problem. `colab ship` takes the issue set to close from THIS machine's claim registry only.
7
+ * A branch built and wrapped on machine A and landed from machine B has its claim in A's registry,
8
+ * so on B ship reads zero claims and refuses (#153 / #324). The only way to write a record on B was
9
+ * `colab claim --force` — a human-only takeover — so an agent lander had no sanctioned path, and
10
+ * every remote-built branch waited for a person even when it had passed review and merged clean.
11
+ *
12
+ * The door. The executor has already said, on the tracker, which branch it handed off and at which
13
+ * head. That comment, checked against git and against the executor's own live claim, is the
14
+ * evidence ship would otherwise get from a local claim. Nothing on B's registry is written and
15
+ * nothing of A's is taken over: A keeps its claim, worktree and branch until it confirms the land
16
+ * (its own `colab worktree rm`, which releases the claim as usual).
17
+ *
18
+ * What a hand-off must prove, in order — the first failure is the verdict:
19
+ * 1. the URL is an issue-comment URL (`…/issues/<N>#issuecomment-<id>`);
20
+ * 2. the comment was read from THIS repo (fetched through `{owner}/{repo}`, so an off-repo id is a
21
+ * 404) and its own html_url names the same issue the URL does;
22
+ * 3. that issue is one the branch NAME carries (its trailing number run, CONVENTIONS.md §4) — the
23
+ * issue set is exactly that run, so git corroborates every `Closes #N` (#87) by construction;
24
+ * 4. the body names the branch, as a whole token;
25
+ * 5. the branch exists on the remote, and this machine holds no diverging copy of its own;
26
+ * 6. the body names a sha that is a prefix of the remote branch's CURRENT head — a branch that
27
+ * moved after its hand-off was not handed off at that head, and lands only after a new one.
28
+ * ONE movement is not "moved" (#579): base-sync merges stacked on the handed-off head. The
29
+ * stale-base gate (#395) sends every behind-trunk branch through B0's sync, and the sync moves
30
+ * the head; without this a remote-built branch that fell behind could land only after its
31
+ * executor — whose session has usually ended — posted again. A sync merge is accepted only
32
+ * when it adds nothing of its own (syncMergeChain, below): two parents, the second already on
33
+ * the base, and a tree equal to git's own clean merge of the two. Any other commit after the
34
+ * handed-off sha — a fix-up, a rebase, a hand-resolved conflict — is still `head-moved`;
35
+ * 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
36
+ * the hand-off's author before the hand-off — the claim really does live elsewhere, and the
37
+ * party handing off is the party holding it.
38
+ *
39
+ * Pure: every input is already read. tools/colab does the IO (`gh api`, `git fetch`, issue views).
40
+ */
41
+
42
+ const { branchIssueNumbers } = require('./branch-name');
43
+
44
+ /** `https://github.com/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE). */
45
+ function parseHandoffUrl(url) {
46
+ const m = String(url || '').trim().match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)\/?#issuecomment-(\d+)$/);
47
+ if (!m) return null;
48
+ return { owner: m[1], repo: m[2], issue: Number(m[3]), commentId: m[4] };
49
+ }
50
+
51
+ function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
52
+
53
+ /** Does `body` name `branch` as a whole token (not as a prefix of a longer branch name)? */
54
+ function namesBranch(body, branch) {
55
+ if (!branch) return false;
56
+ return new RegExp(`(^|[^A-Za-z0-9._/-])${escapeRe(branch)}(?![A-Za-z0-9._/-])`).test(String(body || ''));
57
+ }
58
+
59
+ /** Every 7–40 hex token in `body`, lower-cased — the candidate head shas a hand-off names. */
60
+ function namedShas(body) {
61
+ return [...String(body || '').matchAll(/(?<![0-9A-Za-z])([0-9a-fA-F]{7,40})(?![0-9A-Za-z])/g)]
62
+ .map((m) => m[1].toLowerCase());
63
+ }
64
+
65
+ /**
66
+ * The verdict. Inputs:
67
+ * url — the --handoff value
68
+ * comment — { body, login, createdAt, htmlUrl } as read from THIS repo, or null (unreadable)
69
+ * branch — the branch being shipped
70
+ * refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
71
+ * claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
72
+ * or null for an issue whose comments could not be read
73
+ * syncChain — (#579) the first-parent ancestors of the remote head reached through pure
74
+ * base-sync merges only, nearest first (syncMergeChain's output); [] or absent = none
75
+ * Returns { ok: true, issues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
76
+ * `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
77
+ * unless the head was synced, in which case `syncMerges` counts the merges between them.
78
+ */
79
+ function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain }) {
80
+ const no = (reason, detail) => ({ ok: false, reason, detail });
81
+ const u = parseHandoffUrl(url);
82
+ if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
83
+ if (!comment) return no('unreadable', `comment ${u.commentId} could not be read from this repo — it must be a comment on one of this repo's issues`);
84
+ const got = parseHandoffUrl(comment.htmlUrl);
85
+ if (!got || got.commentId !== u.commentId || got.issue !== u.issue ||
86
+ got.owner.toLowerCase() !== u.owner.toLowerCase() || got.repo.toLowerCase() !== u.repo.toLowerCase()) {
87
+ return no('mismatch', `the URL says ${u.owner}/${u.repo}#${u.issue}, but comment ${u.commentId} is ${comment.htmlUrl || 'somewhere else'}`);
88
+ }
89
+ const issues = branchIssueNumbers(branch);
90
+ if (!issues.length) return no('branch-names-no-issue', `${branch} carries no trailing issue number, so a hand-off has no issue set to close — ship it with --adopt if it genuinely has none`);
91
+ if (!issues.includes(u.issue)) return no('not-this-branch', `the hand-off is on #${u.issue}, which ${branch} does not carry (${issues.map((n) => '#' + n).join(' ')})`);
92
+ if (!namesBranch(comment.body, branch)) return no('branch-not-named', `the hand-off comment does not name the branch ${branch}`);
93
+ if (!refs || !refs.remoteSha) return no('no-remote-branch', `${branch} is not on the remote — a hand-off lands a pushed branch only`);
94
+ // Ship merges the local ref when one exists (shipRefFor), so it must BE the remote head: a stale
95
+ // copy a DWIM checkout made earlier would land a sha the hand-off never named.
96
+ if (refs.localSha && refs.localSha !== refs.remoteSha) {
97
+ return no('local-diverges', refs.localFromRemote
98
+ ? `this machine's ${branch} (${refs.localSha.slice(0, 8)}, created from the remote by an earlier checkout) is behind or apart from the remote's (${refs.remoteSha.slice(0, 8)}) — reset it to the remote's (git branch -f ${branch} <remote>/${branch}, from a checkout not on it) and re-run`
99
+ : `this machine has its own ${branch} (${refs.localSha.slice(0, 8)}) that differs from the remote's (${refs.remoteSha.slice(0, 8)}) — not a remote-built branch here`);
100
+ }
101
+ const head = String(refs.remoteSha).toLowerCase();
102
+ const shas = namedShas(comment.body);
103
+ // #579: the head itself first, then each sha a pure base-sync merge sits on, nearest first.
104
+ const lineage = [head, ...(Array.isArray(syncChain) ? syncChain : []).map((x) => String(x).toLowerCase())];
105
+ const at = lineage.findIndex((l) => shas.some((s) => l.startsWith(s)));
106
+ if (at < 0) {
107
+ const synced = lineage.length > 1 ? ` (nor ${lineage.length - 1 === 1 ? 'the sha' : 'any of the ' + (lineage.length - 1) + ' shas'} its base-sync merges sit on)` : '';
108
+ return no('head-moved', shas.length
109
+ ? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)}${synced} — the branch moved after it was handed off by more than a clean merge of its base; ask its executor for a new hand-off`
110
+ : `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
111
+ }
112
+ let executor = null;
113
+ for (const n of issues) {
114
+ const live = claimsByIssue ? claimsByIssue[n] : null;
115
+ if (!live) return no('claims-unreadable', `#${n}'s comments could not be read — the executor's claim cannot be checked`);
116
+ const match = live.find((c) => c.branch === branch && c.login === comment.login && c.at < comment.createdAt);
117
+ if (!match) {
118
+ return no('no-executor-claim', `#${n} has no live 🔒 claim on ${branch} by ${comment.login || 'the hand-off author'} posted before the hand-off — ` +
119
+ 'the hand-off must come from the party holding the claim');
120
+ }
121
+ if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
122
+ }
123
+ return { ok: true, issues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
124
+ }
125
+
126
+ /**
127
+ * The squash trailer recording the door the issue set came through. It names the HANDED-OFF sha —
128
+ * the one the executor vouched for — and, after a sync (#579), the head that actually landed.
129
+ */
130
+ function handoffTrailer(v) {
131
+ if (!v || !v.ok) return '';
132
+ const handed = String(v.handedOff || v.sha).slice(0, 12);
133
+ const synced = v.syncMerges ? ` (synced to ${String(v.sha).slice(0, 12)} by ${v.syncMerges} base merge${v.syncMerges === 1 ? '' : 's'})` : '';
134
+ return `Colab-Handoff: ${v.url} @ ${handed}${synced}`;
135
+ }
136
+
137
+ /**
138
+ * #579 — walk the remote head's first-parent line while each commit is a PURE base-sync merge, and
139
+ * return the shas it sits on, nearest first. A commit qualifies only when all three hold:
140
+ * - exactly two parents (a squash, a rebase, a cherry-pick or a fix-up has one);
141
+ * - its second parent is already on the base (`merge-base --is-ancestor p2 <baseRef>`) — it
142
+ * brought in landed base content, not a side branch;
143
+ * - its tree equals `git merge-tree --write-tree p1 p2`'s — git's own conflict-free merge of the
144
+ * two. A conflict (exit 1) or a hand-edited result (a different tree) is NOT pure: someone wrote
145
+ * content into it, and only the executor can vouch for content.
146
+ * The walk stops at the first commit that fails, so a sync merge stacked on a fix-up yields only
147
+ * the fix-up's sha — which a hand-off naming the commit before the fix-up does not match.
148
+ *
149
+ * `run(args)` is git in the repo, returning { ok, code, stdout } (tools/lib/git.js `git`). A git
150
+ * too old for `merge-tree --write-tree` (< 2.38) proves nothing, so the chain is just empty there:
151
+ * the hand-off then needs the exact head, exactly as before #579.
152
+ */
153
+ function syncMergeChain(run, head, baseRef, maxDepth = 50) {
154
+ const chain = [];
155
+ let cur = String(head || '');
156
+ for (let i = 0; cur && i < maxDepth; i++) {
157
+ const p = run(['rev-list', '--parents', '-n', '1', cur]);
158
+ if (!p.ok) break;
159
+ const parts = String(p.stdout).trim().split(/\s+/);
160
+ if (parts.length !== 3) break;
161
+ const [, p1, p2] = parts;
162
+ if (run(['merge-base', '--is-ancestor', p2, baseRef]).code !== 0) break;
163
+ const mt = run(['merge-tree', '--write-tree', p1, p2]);
164
+ if (mt.code !== 0) break;
165
+ const merged = String(mt.stdout).split('\n')[0].trim();
166
+ const tree = run(['rev-parse', `${cur}^{tree}`]);
167
+ if (!tree.ok || !/^[0-9a-f]{40,64}$/.test(merged) || merged !== String(tree.stdout).trim()) break;
168
+ chain.push(p1.toLowerCase());
169
+ cur = p1;
170
+ }
171
+ return chain;
172
+ }
173
+
174
+ /**
175
+ * #591 — `--batch b1,b2@<handoff-url>`: split the batch list into member branch names and, for the
176
+ * members built on another machine, the hand-off each one names. One list, one source: the `@` rides
177
+ * the member it belongs to, so the hand-off cannot drift from the member list the way a second
178
+ * `--handoffs` map could. Each entry splits on its FIRST `@` — a §4 branch name never holds one, and
179
+ * a hand-off URL never holds a `,`. The URL itself is judged later by handoffVerdict, exactly as a
180
+ * single `--handoff` is, so a malformed one is refused with today's message, not a new one.
181
+ * Returns { members: [branch…] (deduped, in order), handoffs: { [branch]: url }, errors: [msg…] }.
182
+ */
183
+ function parseBatchEntries(list) {
184
+ const members = [];
185
+ const handoffs = {};
186
+ const errors = [];
187
+ for (const raw of String(list || '').split(',').map((x) => x.trim()).filter(Boolean)) {
188
+ const at = raw.indexOf('@');
189
+ const branch = (at < 0 ? raw : raw.slice(0, at)).trim();
190
+ const url = at < 0 ? '' : raw.slice(at + 1).trim();
191
+ if (!branch) { errors.push(`"${raw}" names a hand-off but no branch — write <branch>@<hand-off-url>`); continue; }
192
+ if (at >= 0 && !url) { errors.push(`"${raw}" has an @ but no hand-off URL after it`); continue; }
193
+ if (url) {
194
+ if (handoffs[branch] && handoffs[branch] !== url) { errors.push(`${branch} is named with two different hand-offs (${handoffs[branch]}, ${url})`); continue; }
195
+ handoffs[branch] = url;
196
+ }
197
+ if (!members.includes(branch)) members.push(branch);
198
+ }
199
+ return { members, handoffs, errors };
200
+ }
201
+
202
+ /**
203
+ * #591 — read a `Colab-Handoff:` trailer back off a squash commit body (handoffTrailer's inverse):
204
+ * `{ url, handedOff }` or null. A batch lands in a second call, so the member's door is read from
205
+ * the commit the combined run graded, never re-supplied on the command line.
206
+ */
207
+ function parseHandoffTrailer(body) {
208
+ const m = String(body || '').match(/^Colab-Handoff: (\S+) @ ([0-9a-f]{7,40})\b/m);
209
+ return m ? { url: m[1], handedOff: m[2] } : null;
210
+ }
211
+
212
+ module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
@@ -642,7 +642,7 @@ function sameContent(a, b) {
642
642
  * so divergence is undecidable and the classification stops at current/behind.
643
643
  */
644
644
  function classifyStamped(opts) {
645
- const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames } = opts;
645
+ const { root, hb, templateName, stampVersion, localText, comparable = true, tmplNames, render = null } = opts;
646
646
 
647
647
  if (hb.untagged || !hb.hasGit) {
648
648
  return { state: 'n-a', reason: 'handbook is untagged — stamp comparison inactive', from: stampVersion, to: hb.version };
@@ -675,7 +675,11 @@ function classifyStamped(opts) {
675
675
  return { state: 'n-a', reason: `cannot read templates/${templateName} at ${stampVersion} — cannot tell pristine from edited`, from: stampVersion, to: hb.version };
676
676
  }
677
677
  const expected = stampLine(templateName, stampVersion) + pristine;
678
- if (sameContent(localText, expected)) {
678
+ // #526: `colab template` writes a CI copy with the repo's own refs. `render` (when given) is
679
+ // that rendering, so such a copy still reads as pristine; the raw body still counts too (a copy
680
+ // made before #526, or in a repo whose descriptor changed since).
681
+ const rendered = typeof render === 'function' ? stampLine(templateName, stampVersion) + render(pristine) : null;
682
+ if (sameContent(localText, expected) || (rendered !== null && sameContent(localText, rendered))) {
679
683
  return { state: 'behind', reason: 'pristine copy, template changed since this stamp', from: stampVersion, to: hb.version };
680
684
  }
681
685
  return { state: 'diverged', reason: `hand-edited since it was copied @ ${stampVersion} — copy-and-own, review by hand`, from: stampVersion, to: hb.version };
@@ -0,0 +1,80 @@
1
+ 'use strict';
2
+ /**
3
+ * Trunk substitution for a copied CI template (#526). Pure: text in, text out, no I/O.
4
+ *
5
+ * The CI templates protect two refs by name — `main` and `dev` — in three places: the concurrency
6
+ * `group`, `cancel-in-progress`, and the `dedupe` guard's `if:`. Those names are the defaults of the
7
+ * two shapes a repo can have, not facts about any one repo. Copied verbatim into a repo whose trunk
8
+ * is `master`, the trunk runs become cancellable (the deadlock CONVENTIONS §4 warns about) and the
9
+ * tree-reuse guard never fires there. `colab template` knows the trunk — it is in
10
+ * `.github/project.yml` — so it writes the right refs instead of leaving an EDIT point.
11
+ *
12
+ * Which refs a repo protects:
13
+ * - one branch (trunk `main`, or any trunk on a repo with no release branch) → `[trunk]`;
14
+ * - two branches (trunk ≠ `main` where the promotion into `main` releases — exposure live or
15
+ * released, or legacy tier A/C) → `['main', trunk]`.
16
+ *
17
+ * The Laravel template's test tier also names `main` as the branch whose suite gates a release;
18
+ * on a one-branch repo that branch is the trunk, so it is rewritten too.
19
+ *
20
+ * Only the exact expression shapes the templates ship are rewritten. A copy whose shape was
21
+ * already edited is left alone and reported as `missed`, never guessed at.
22
+ */
23
+
24
+ const TEMPLATE_REFS = ['main', 'dev'];
25
+
26
+ /** The refs a repo's CI protects, from its parsed descriptor. null when no `trunk:` is declared. */
27
+ function protectedRefs(doc) {
28
+ const trunk = doc && typeof doc.trunk === 'string' && doc.trunk.trim() ? doc.trunk.trim() : null;
29
+ if (!trunk) return null;
30
+ const exposure = doc.exposure == null ? null : String(doc.exposure);
31
+ const tier = doc.tier == null ? null : String(doc.tier).toUpperCase();
32
+ const promotes = exposure === 'live' || exposure === 'released' || (exposure == null && (tier === 'A' || tier === 'C'));
33
+ const twoBranch = trunk !== 'main' && promotes;
34
+ return { trunk, twoBranch, refs: twoBranch ? ['main', trunk] : [trunk] };
35
+ }
36
+
37
+ const eq = (r) => `github.ref == 'refs/heads/${r}'`;
38
+ const ne = (r) => `github.ref != 'refs/heads/${r}'`;
39
+
40
+ /**
41
+ * Rewrite the template's `main`/`dev` refs to `p` (protectedRefs' result).
42
+ * Returns { text, changes: [what], missed: [what] }. `changes` is empty when the template's own
43
+ * refs are already right (a `dev` trunk with a `main` release branch).
44
+ */
45
+ function substituteTrunk(text, p) {
46
+ const changes = [];
47
+ const missed = [];
48
+ let out = text;
49
+ const swap = (label, from, to) => {
50
+ if (!out.includes(from)) { missed.push(label); return; }
51
+ if (from !== to) { out = out.split(from).join(to); changes.push(label); }
52
+ };
53
+ const tplEq = TEMPLATE_REFS.map(eq);
54
+ swap('concurrency group', `(${tplEq.join(' || ')}) && format(`, `(${p.refs.map(eq).join(' || ')}) && format(`);
55
+ swap('cancel-in-progress', `cancel-in-progress: \${{ ${TEMPLATE_REFS.map(ne).join(' && ')} }}`,
56
+ `cancel-in-progress: \${{ ${p.refs.map(ne).join(' && ')} }}`);
57
+ swap("dedupe guard's if:", `github.event.created || ${tplEq.join(' || ')})`, `github.event.created || ${p.refs.map(eq).join(' || ')})`);
58
+ // ci-laravel's test tier (only present there): the release-gating branch is the trunk on a one-branch repo.
59
+ if (!p.twoBranch && p.trunk !== 'main' && out.includes('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')) {
60
+ out = out.split('[ "$BASE_REF" = "main" ]').join(`[ "$BASE_REF" = "${p.trunk}" ]`);
61
+ out = out.split('[ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]')
62
+ .join(`[ "$REF" = "refs/heads/${p.trunk}" ] || [ "$trunk" = "${p.trunk}" ]`);
63
+ changes.push('test tier');
64
+ }
65
+ return { text: out, changes, missed };
66
+ }
67
+
68
+ /**
69
+ * What `colab template <name>` writes for a repo whose descriptor is `doc`: the body with this
70
+ * repo's refs when `name` is a CI template and a trunk is declared, else the body unchanged.
71
+ * `colab update` uses the same rendering both to recognise a pristine copy and to refresh one, so
72
+ * a refreshed file stays byte-identical to what `colab template <name> --force` would write.
73
+ */
74
+ function renderForRepo(name, body, doc) {
75
+ if (!/^ci-/.test(String(name || ''))) return body;
76
+ const p = protectedRefs(doc);
77
+ return p ? substituteTrunk(body, p).text : body;
78
+ }
79
+
80
+ module.exports = { TEMPLATE_REFS, protectedRefs, substituteTrunk, renderForRepo };
@@ -18,6 +18,8 @@
18
18
  */
19
19
 
20
20
  const NOTICE_TITLE = 'tree-already-green';
21
+ /** #570: the CI guard's docs-only mode leaves this notice instead — same run shape, a different reason. */
22
+ const DOCS_NOTICE_TITLE = 'docs-only-skip';
21
23
 
22
24
  /** `tree-reuse:` in project.yml. Absent = reuse on. `off` = the one legal value. */
23
25
  function parseTreeReuse(doc) {
@@ -72,17 +74,32 @@ function parseCitation(annotations) {
72
74
  return { url: m[1], runId, tree: m[2], head: m[3], branch: m[4] };
73
75
  }
74
76
 
77
+ /**
78
+ * #570: the docs-only notice in a check run's annotations (`base=<sha> files=<n> run=<url>`), or null.
79
+ * A docs-only skip has the same shape as a tree skip (the guard green, the rest skipped), so the
80
+ * reader must recognise it — otherwise it reads as a tree citation nobody can parse.
81
+ */
82
+ function parseDocsSkip(annotations) {
83
+ if (!Array.isArray(annotations)) return null;
84
+ const a = annotations.find((x) => x && x.title === DOCS_NOTICE_TITLE && typeof x.message === 'string');
85
+ if (!a) return null;
86
+ const m = a.message.trim().match(/^base=([0-9a-f]+)\s+files=(\d+)\s+run=(\S+)$/i);
87
+ if (!m) return null;
88
+ return { base: m[1], files: Number(m[2]), url: m[3] };
89
+ }
90
+
75
91
  /**
76
92
  * The verdict suffix for a green trunk read that relied on cited runs. `cites`: [{url, branch,
77
93
  * head, proof}] where proof is 'verified' | 'unverified'; `unreadable`: count of skip-runs whose
78
94
  * citation could not be read. '' when there is nothing to say (an ordinary green run).
79
95
  */
80
- function citationNote(cites, unreadable = 0) {
96
+ function citationNote(cites, unreadable = 0, docs = []) {
81
97
  const parts = (cites || []).map((c) =>
82
98
  `relied on ${c.url} (${c.branch}@${String(c.head).slice(0, 7)}${c.proof === 'verified' ? ', tree verified locally' : ', tree not verified locally'})`);
83
99
  for (let i = 0; i < unreadable; i++) parts.push('cited run unreadable');
84
- if (!parts.length) return '';
85
- return ` — tree already green (#493): suite skipped, ${parts.join('; ')}`;
100
+ const tree = parts.length ? ` — tree already green (#493): suite skipped, ${parts.join('; ')}` : '';
101
+ const doc = (docs || []).map((d) => `${d.files} path(s) since ${String(d.base).slice(0, 7)}, whose green run is ${d.url}`);
102
+ return tree + (doc.length ? ` — docs-only (#570): suite skipped, ${doc.join('; ')}` : '');
86
103
  }
87
104
 
88
- module.exports = { NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, citationNote };
105
+ module.exports = { NOTICE_TITLE, DOCS_NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, parseDocsSkip, citationNote };
@@ -265,6 +265,62 @@ function prereleaseTagTriggers({ readFile, workflows, deploy }) {
265
265
  return out;
266
266
  }
267
267
 
268
+ // ---- callers of the reusable instruction-files workflow (#599) ---------------
269
+ // The ratchet (#588) is meant to fail on the SESSION BRANCH, before trunk. A caller narrowed to
270
+ // `push: branches: [main]` (measured: 15 of 16 adopting copies) never runs there, so a branch that
271
+ // trips it merges green and the failure first appears on trunk — where the cure rule (#297) then
272
+ // cannot find the job on the cure branch's push run and, with no `workflow_dispatch` to fall back on
273
+ // (#510), ships only through a human grant. A caller is recognised by what it RUNS — a job `uses:`
274
+ // the reusable `.github/workflows/instruction-files.yml` — never by its file name. One branch per
275
+ // session-branch type is probed (plus a machine-prefixed one, §4), so `branches: ['feat/**']` reads
276
+ // as narrowed too; the trunk itself is probed as well, since a caller that skips trunk is narrowed
277
+ // the other way.
278
+ const INSTRUCTION_FILES_USES = /^\s*(?:-\s*)?uses:\s*["']?[^\s"'#]*\.github\/workflows\/instruction-files\.ya?ml(?:@[^\s"'#]*)?["']?\s*(?:#.*)?$/m;
279
+ const SESSION_BRANCH_PROBES = ["feat/probe-1", "fix/probe-1", "docs/probe-1", "chore/probe-1", "refactor/probe-1",
280
+ "test/probe-1", "perf/probe-1", "design/probe-1", "ada/box-a/feat/probe-1"];
281
+
282
+ /** Does this workflow call the reusable instruction-files workflow? (#599) */
283
+ function isInstructionFilesCaller(text) {
284
+ return !!text && INSTRUCTION_FILES_USES.test(text);
285
+ }
286
+
287
+ /**
288
+ * Each caller of the reusable instruction-files workflow whose trigger cannot run it on a session
289
+ * branch, or which cannot be dispatched (#599). `readFile(relPath)` returns the text or null;
290
+ * `trunk` is project.yml's value (`main` when absent). Returns
291
+ * [{ workflow, narrowed:[branch…], dispatchable:boolean, text }] — only callers with a problem.
292
+ */
293
+ function instructionFilesCallerFindings({ readFile, workflows, trunk }) {
294
+ const out = [];
295
+ for (const wf of workflows || []) {
296
+ const text = readFile(`.github/workflows/${wf}`);
297
+ if (!isInstructionFilesCaller(text)) continue;
298
+ const on = parseWorkflowOn(text);
299
+ const probes = [trunk || "main", ...SESSION_BRANCH_PROBES];
300
+ const narrowed = probes.filter((b) => !workflowFiresOnBranchPush(on, b));
301
+ const dispatchable = on.events.has("workflow_dispatch");
302
+ if (!narrowed.length && dispatchable) continue;
303
+ const why = [];
304
+ if (narrowed.length) {
305
+ why.push(!on.events.has("push")
306
+ ? "has no push trigger, so it never runs on a session branch"
307
+ : `its push trigger does not fire on ${narrowed.slice(0, 3).join(", ")}${narrowed.length > 3 ? ` (+${narrowed.length - 3} more)` : ""}` +
308
+ " — the ratchet then fails first on trunk instead of on the branch that broke it");
309
+ }
310
+ if (!dispatchable) {
311
+ why.push("it declares no workflow_dispatch, so a cure branch cannot prove the job by dispatch (#510) and a red trunk ships only through a human ci-grant");
312
+ }
313
+ out.push({
314
+ workflow: wf, narrowed, dispatchable,
315
+ text:
316
+ `.github/workflows/${wf} calls the reusable instruction-files workflow, but ${why.join("; and ")}. ` +
317
+ "Fix: use the template trigger — an unfiltered `push:`, `pull_request:` and `workflow_dispatch:` " +
318
+ "(templates/instruction-files.yml; handbook-sync grafts it) (#599)",
319
+ });
320
+ }
321
+ return out;
322
+ }
323
+
268
324
  // --------------------------------------------------- workflow_dispatch inputs (#474)
269
325
  //
270
326
  // The names declared under `on: workflow_dispatch: inputs:`, in order. `[]` for a bare
@@ -318,4 +374,5 @@ module.exports = {
318
374
  workflowFiresOnBranchPush, workflowsFiringOnBranchPush,
319
375
  isDeployWorkflow, isReleaseTagTemplateCopy, prereleaseTagTriggers,
320
376
  workflowDispatchInputs, workflowNameOf,
377
+ SESSION_BRANCH_PROBES, isInstructionFilesCaller, instructionFilesCallerFindings,
321
378
  };