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

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 (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  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/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
@@ -20,12 +20,18 @@
20
20
  * What it measures, per window:
21
21
  * batches landed and their fill; every combined-run build, first-attempt green, green after
22
22
  * the one re-run, red, still pending
23
- * red red builds and how many of their members then landed serially (the fallback)
23
+ * red red builds and how many of their members then landed alone — serially, or as a
24
+ * batch of one (#580) — the fallback
24
25
  * dropped members dropped at build, by class, and the eviction rate among attempted members
25
26
  * serial serial landings, and MISSED PARTNERS: another candidate that landed later but was
26
27
  * already green when this one landed alone (could have joined), or turned green
27
28
  * within this landing's trunk-CI cycle (a partner wait of `waitSec` would have caught
28
- * it — the number `ship-batch-wait` is tuned from)
29
+ * it — the number `ship-batch-wait` is tuned from). `serial` means landed through the
30
+ * SERIAL PATH (no Ship-Batch trailer), and only that
31
+ * alone the same partner scan over every change that LANDED ALONE: a serial landing, or a
32
+ * batch of one (#580). Since #562 a lone ready candidate on a ship-batch repo lands as
33
+ * a fill-1 batch, so on such a repo `serial` reads zero whether partners were missed or
34
+ * not; `alone` is the signal `ship-batch-wait` is tuned from there
29
35
  * queueWait per landed change, green-at-head → landing
30
36
  */
31
37
 
@@ -175,16 +181,21 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
175
181
  const rerunGreen = buildRows.filter((b) => b.state === 'green' && b.attempt > 1).length;
176
182
  const redBuilds = buildRows.filter((b) => b.state === 'red');
177
183
 
178
- // ---- red builds → did their members then land serially? ----
184
+ // ---- red builds → did their members then land alone (serially, or as a batch of one)? ----
179
185
  const serialChanges = changes.filter((c) => c.landing.kind === 'serial');
180
- let redMembers = 0, relanded = 0, redMembersUnread = 0;
186
+ // #580: a fill-1 batch landed alone exactly as a serial landing did — only its path differs.
187
+ const isBatchOfOne = (c) => c.landing.kind === 'batch' && c.landing.members.length === 1;
188
+ const aloneChanges = changes.filter((c) => c.landing.kind === 'serial' || isBatchOfOne(c));
189
+ let redMembers = 0, relanded = 0, relandedAlone = 0, redMembersUnread = 0;
181
190
  for (const b of redBuilds) {
182
191
  const members = b.messages && b.messages.length ? shipBatch.parseMemberTrailers(b.messages) : [];
183
192
  if (!members.length) { redMembersUnread++; continue; }
184
193
  for (const m of members) {
185
194
  redMembers++;
186
195
  const nums = branchName.branchIssueNumbers(m.branch);
187
- if (serialChanges.some((c) => c.atMs >= b.createdMs && (c.branch === m.branch || c.issues.some((n) => nums.includes(n))))) relanded++;
196
+ const isMember = (c) => c.atMs >= b.createdMs && (c.branch === m.branch || c.issues.some((n) => nums.includes(n)));
197
+ if (serialChanges.some(isMember)) relanded++;
198
+ if (aloneChanges.some(isMember)) relandedAlone++;
188
199
  }
189
200
  }
190
201
  if (redMembersUnread) notes.push(`${redMembersUnread} red build(s) whose members could not be read (the ref is gone and its commits were not readable)`);
@@ -205,42 +216,57 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
205
216
  const byClass = {};
206
217
  for (const d of dropped) byClass[d.cls] = (byClass[d.cls] || 0) + 1;
207
218
 
208
- // ---- missed partners: serial landings that landed alone while a partner was (nearly) ready ----
209
- const pairs = [];
210
- let withMissed = 0, withNear = 0, cyclesUnread = 0, overlapped = 0;
219
+ // ---- missed partners: landings that went alone while a partner was (nearly) ready ----
211
220
  // A partner is judged by ITS state at this landing's moment, never by the head it finally landed
212
221
  // with: a serial ship syncs the other branches, so their final heads all post-date it. The cycle
213
222
  // ends when this landing's trunk run finishes — or at the next landing, whichever is first (a
214
223
  // re-run moves a run's updated_at hours later, and the next landing moves trunk anyway).
215
224
  const landingTimes = landings.map((l) => l.atMs).sort((a, b) => a - b);
216
- for (const c of serialChanges) {
217
- const next = landingTimes.find((t) => t > c.atMs);
218
- let end = cycleEnd(c.landing.sha);
219
- if (end === null) cyclesUnread++;
220
- else if (next !== undefined) end = Math.min(end, next);
221
- let missed = false, near = false;
222
- const label = c.branch || c.landing.sha.slice(0, 7);
223
- for (const o of changes) {
224
- if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
225
- const gNow = greenAt(runsByBranch, o.branch, c.atMs);
226
- if (gNow !== null) {
227
- missed = true;
228
- pairs.push({ kind: 'missed', landed: label, partner: o.branch });
229
- continue;
230
- }
231
- if (end === null) continue;
232
- const gEnd = greenAt(runsByBranch, o.branch, end);
233
- if (gEnd !== null && gEnd > c.atMs) {
234
- near = true;
235
- const from = c.greenMs !== null ? c.greenMs : c.atMs;
236
- pairs.push({ kind: 'near', landed: label, partner: o.branch, waitSec: Math.round((gEnd - from) / 1000) });
225
+ const scanPartners = (lone, tagVia) => {
226
+ const pairs = [];
227
+ let withMissed = 0, withNear = 0, cyclesUnread = 0, overlapped = 0;
228
+ for (const c of lone) {
229
+ const next = landingTimes.find((t) => t > c.atMs);
230
+ let end = cycleEnd(c.landing.sha);
231
+ if (end === null) cyclesUnread++;
232
+ else if (next !== undefined) end = Math.min(end, next);
233
+ let missed = false, near = false;
234
+ const label = c.branch || c.landing.sha.slice(0, 7);
235
+ const via = tagVia ? { via: c.landing.kind === 'serial' ? 'serial' : 'batch-of-one' } : {};
236
+ for (const o of changes) {
237
+ if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
238
+ const gNow = greenAt(runsByBranch, o.branch, c.atMs);
239
+ if (gNow !== null) {
240
+ missed = true;
241
+ pairs.push({ kind: 'missed', landed: label, partner: o.branch, ...via });
242
+ continue;
243
+ }
244
+ if (end === null) continue;
245
+ const gEnd = greenAt(runsByBranch, o.branch, end);
246
+ if (gEnd !== null && gEnd > c.atMs) {
247
+ near = true;
248
+ const from = c.greenMs !== null ? c.greenMs : c.atMs;
249
+ pairs.push({ kind: 'near', landed: label, partner: o.branch, waitSec: Math.round((gEnd - from) / 1000), ...via });
250
+ }
237
251
  }
252
+ if (missed) withMissed++;
253
+ else if (near) withNear++;
254
+ if (end !== null && (missed || near)) overlapped++;
238
255
  }
239
- if (missed) withMissed++;
240
- else if (near) withNear++;
241
- if (end !== null && (missed || near)) overlapped++;
242
- }
243
- if (cyclesUnread) notes.push(`${cyclesUnread} serial landing(s) with no finished trunk run in the window — near misses not judged for them`);
256
+ return {
257
+ landings: lone.length, withMissedPartner: withMissed, withNearMiss: withNear,
258
+ // #556: the overlap rate's honest denominator — only a landing whose trunk-CI cycle was read
259
+ // could have been judged for a partner inside it; `overlapped` counts those that had one.
260
+ cyclesRead: lone.length - cyclesUnread, overlapped,
261
+ nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
262
+ pairs,
263
+ };
264
+ };
265
+ const serial = scanPartners(serialChanges, false);
266
+ const alone = scanPartners(aloneChanges, true);
267
+ // The alone set contains the serial one, so its unread count is the one note (never two).
268
+ const aloneUnread = alone.landings - alone.cyclesRead;
269
+ if (aloneUnread) notes.push(`${aloneUnread} lone landing(s) (serial or a batch of one) with no finished trunk run in the window — near misses not judged for them`);
244
270
  const unknownGreen = changes.filter((c) => c.greenMs === null).length;
245
271
  if (unknownGreen) notes.push(`${unknownGreen} landed change(s) with no readable green-at-head run — left out of queue wait and partner matching`);
246
272
 
@@ -259,16 +285,13 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
259
285
  pending: buildRows.length - finished.length,
260
286
  firstAttemptGreenRate: rate(firstGreen, finished.length),
261
287
  },
262
- red: { builds: redBuilds.length, members: redMembers, relandedSerially: relanded },
288
+ // relandedSerially: through the serial path only; relandedAlone: serially OR as a batch of one (#580).
289
+ red: { builds: redBuilds.length, members: redMembers, relandedSerially: relanded, relandedAlone },
263
290
  dropped: { count: dropped.length, attempted: builtMembers + dropped.length, rate: rate(dropped.length, builtMembers + dropped.length), byClass, members: dropped },
264
- serial: {
265
- landings: serialChanges.length, withMissedPartner: withMissed, withNearMiss: withNear,
266
- // #556: the overlap rate's honest denominator — only a landing whose trunk-CI cycle was read
267
- // could have been judged for a partner inside it; `overlapped` counts those that had one.
268
- cyclesRead: serialChanges.length - cyclesUnread, overlapped,
269
- nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
270
- pairs,
271
- },
291
+ // `serial`: landed through the serial path. `alone`: landed alone by either path — a serial
292
+ // landing or a batch of one (#580); its pairs carry `via: 'serial' | 'batch-of-one'`.
293
+ serial,
294
+ alone: { ...alone, batchOfOne: aloneChanges.filter(isBatchOfOne).length },
272
295
  queueWait,
273
296
  notes,
274
297
  };
@@ -55,7 +55,7 @@ function releaseComments(sorted) {
55
55
 
56
56
  /**
57
57
  * Live claim comments on an issue. Returns [{login, host, machine, session, sessionName, at,
58
- * identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
58
+ * branch, worktree, identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
59
59
  * is built from `comps` (claim-identity.js `components()`, #267); the raw fields are returned too
60
60
  * for callers that need `sameClaimant`'s degrade-on-missing comparison.
61
61
  *
@@ -91,7 +91,8 @@ function liveClaimComments(comments, comps) {
91
91
  const { host, session, sessionName } = claim;
92
92
  const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
93
93
  const at = c.createdAt;
94
- const entry = { login, host, machine: machineTok, session, sessionName, at };
94
+ // #578: branch/worktree ride along so a reader can ask WHICH branch a live claim holds.
95
+ const entry = { login, host, machine: machineTok, session, sessionName, at, branch: claim.branch, worktree: claim.worktree };
95
96
  const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
96
97
  || (r.login === login && !isNamedWinner(entry, r.winner))));
97
98
  if (!cancelled) live.push({ ...entry, identity: claimIdentity.identityString({ login, host, session }, comps) });
@@ -27,3 +27,10 @@ export const OPTIONS_RE: RegExp;
27
27
  export const MOCKUP_RE: RegExp;
28
28
  export function encodeMockup(url: string): string;
29
29
  export function mockupUrls(body: unknown): string[];
30
+
31
+ /** An ask record a dashboard that tracks asks wrote (#582) — read-only to colab. */
32
+ export interface AskRecord { ns: string; id: string; version: number; index: number; }
33
+ /** An answer record naming an ask by id (#582). */
34
+ export interface AnswerRecord { ns: string; ask: string; version: number | null; index: number; }
35
+ export function askRecords(text: unknown): AskRecord[];
36
+ export function answerRecords(text: unknown): AnswerRecord[];
@@ -74,8 +74,62 @@ function mockupUrls(body) {
74
74
  return out;
75
75
  }
76
76
 
77
+ /**
78
+ * ASK / ANSWER RECORDS (#582) — the structured question a dashboard that tracks asks writes onto an
79
+ * issue, and the answer that settles it. READ-ONLY here: colab never writes either, it only needs to
80
+ * know which asks are still open so `colab decision --record` can name the one a ruling settles.
81
+ *
82
+ * Wire shape, namespaced by whatever tool wrote it (the namespace is not interpreted — any tool
83
+ * writing this shape is read the same way):
84
+ * `<!-- <tool>:ask id=<id> v=<n> [key=value …] -->` + the question below it
85
+ * `<!-- <tool>:answer ask=<id> [v=<n>] [key=value …] -->` (+ optional note)
86
+ * and the same heads as a bare line form `<tool>:ask id=…` at the start of a line. Attribute values
87
+ * are percent-encoded and space-separated. Other kinds naming an ask (a wait, a delegation) are not
88
+ * answers and are not read.
89
+ */
90
+ const RECORD_NS = '[a-z][a-z0-9_-]*';
91
+ function recordHeads(text, kind) {
92
+ if (typeof text !== 'string' || text === '') return [];
93
+ const heads = [];
94
+ const markerRe = new RegExp(`<!--\\s*(${RECORD_NS}):${kind}\\s+([^>]*?)\\s*-->`, 'g');
95
+ const lineRe = new RegExp(`^(${RECORD_NS}):${kind}\\s+([^\\n]*)$`, 'gm');
96
+ for (const re of [markerRe, lineRe]) {
97
+ let m;
98
+ while ((m = re.exec(text))) {
99
+ const attrs = parseRecordAttrs(m[2]);
100
+ if (attrs) heads.push({ index: m.index, ns: m[1], attrs });
101
+ }
102
+ }
103
+ return heads.sort((a, b) => a.index - b.index);
104
+ }
105
+ /** `k=v k2=v2` → `{k: v, k2: v2}` (values percent-decoded), or null when any token is not `k=v`. */
106
+ function parseRecordAttrs(raw) {
107
+ const out = {};
108
+ const toks = String(raw).trim().split(/\s+/).filter(Boolean);
109
+ if (toks.length === 0) return null;
110
+ for (const t of toks) {
111
+ const m = /^([a-z][a-z0-9_-]*)=(\S*)$/i.exec(t);
112
+ if (!m) return null;
113
+ try { out[m[1]] = decodeURIComponent(m[2]); } catch (_) { out[m[1]] = m[2]; }
114
+ }
115
+ return out;
116
+ }
117
+ /** Every ask record in `text`, in order: `{ns, id, version, index}`. Requires `id` and an integer `v >= 1`. */
118
+ function askRecords(text) {
119
+ return recordHeads(text, 'ask')
120
+ .filter((h) => h.attrs.id && /^\d+$/.test(h.attrs.v || '') && Number(h.attrs.v) >= 1)
121
+ .map((h) => ({ ns: h.ns, id: h.attrs.id, version: Number(h.attrs.v), index: h.index }));
122
+ }
123
+ /** Every answer record in `text`, in order: `{ns, ask, version, index}` (`version` null when absent). */
124
+ function answerRecords(text) {
125
+ return recordHeads(text, 'answer')
126
+ .filter((h) => h.attrs.ask)
127
+ .map((h) => ({ ns: h.ns, ask: h.attrs.ask, version: /^\d+$/.test(h.attrs.v || '') ? Number(h.attrs.v) : null, index: h.index }));
128
+ }
129
+
77
130
  module.exports = {
78
131
  DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
79
132
  encodeDecision, decodeDecision, encodeReopen, decodeReopen,
80
133
  OPTIONS_RE, MOCKUP_RE, encodeMockup, mockupUrls,
134
+ askRecords, answerRecords,
81
135
  };
@@ -14,13 +14,20 @@ export function parseQualifiedIssueRef(arg: unknown): { slug: string; number: nu
14
14
 
15
15
  export const HOLD_RE: RegExp;
16
16
  export const BECAUSE_RE: RegExp;
17
+ export type HoldShape = 'ask' | 'task' | 'wait';
18
+ export const HOLD_SHAPES: ReadonlyArray<HoldShape>;
17
19
  export interface DecodedHold {
18
20
  label: string;
19
21
  owner: string;
22
+ /** The declared `shape:` as written (#569) — present only when the line carries one. */
23
+ shape?: string;
20
24
  /** The `wake:` field as written — `parseWakeLine` decides whether it names a wake. */
21
25
  wake: string;
22
26
  /** The `Because:` line's text, or null when the comment is the `Hold:` line alone. */
23
27
  because: string | null;
24
28
  }
25
- export function encodeHold(h?: { label: string; owner: string; wake: string | string[]; because?: string | null }): string;
29
+ export function encodeHold(h?: { label: string; owner: string; shape?: HoldShape | null; wake: string | string[]; because?: string | null }): string;
26
30
  export function decodeHold(body: string | null | undefined): DecodedHold | null;
31
+ /** Declared shape when in the closed set, else inferred from the wake (`ruling` → ask, else wait). */
32
+ export function holdShape(decoded: Partial<DecodedHold> | null | undefined):
33
+ { shape: HoldShape; declared: boolean; invalid: string | null };
@@ -3,7 +3,7 @@
3
3
  * CODEC (#498, epic #496): the HOLD wire format — the two-line comment that parks an issue
4
4
  * (CONVENTIONS.md §5, *Holds*):
5
5
  *
6
- * Hold: <label> — owner: <who clears it> — wake: <condition>[, <condition>…]
6
+ * Hold: <label> — owner: <who clears it>[ — shape: ask|task|wait] — wake: <condition>[, <condition>…]
7
7
  * Because: <what is left>
8
8
  *
9
9
  * — and the closed `wake:` vocabulary that line's last field is drawn from (#382). Pure and
@@ -114,17 +114,47 @@ function parseQualifiedIssueRef(arg) {
114
114
 
115
115
  // ── the Hold: / Because: lines ───────────────────────────────────────────────────────────────
116
116
 
117
- const HOLD_RE = /^Hold: (\S+) — owner: (.+?) — wake: (.+)$/;
117
+ // `shape:` (#569) sits BETWEEN owner and wake on purpose. An older reader's pattern is
118
+ // `owner: (.+?) — wake: (.+)$`: placed there, the field folds into that reader's owner text and
119
+ // its wake still parses whole. Placed after wake: it would corrupt the wake, and the older reader
120
+ // would report a perfectly good hold as a stall. Never move it.
121
+ const HOLD_RE = /^Hold: (\S+) — owner: (.+?)(?: — shape: (\S+))? — wake: (.+)$/;
118
122
  const BECAUSE_RE = /^Because: (.*)$/;
119
123
 
124
+ /**
125
+ * What the owner is being asked for (#569) — closed, read by equality:
126
+ * ask — a choice between ways forward. Posted as a structured ask (`needs-decision` + a
127
+ * `decision:options` block with a recommended default), never as a bare hold.
128
+ * task — an act only a person can perform: verify by hand, run a privileged script, sign,
129
+ * supply a credential.
130
+ * wait — on a third party, another issue, a ref or a date.
131
+ */
132
+ const HOLD_SHAPES = Object.freeze(['ask', 'task', 'wait']);
133
+
134
+ /**
135
+ * The shape a reader acts on: the declared `shape:` when it is in the closed set, otherwise the
136
+ * inference that predates the field — a `ruling` anywhere in the wake reads as `ask`, anything
137
+ * else as `wait`. `declared` says which. An unknown declared value is not trusted (`invalid` names
138
+ * it) and falls back to the inference, so a typo never silently re-routes a hold.
139
+ * @returns {{shape:'ask'|'task'|'wait', declared:boolean, invalid:string|null}}
140
+ */
141
+ function holdShape(decoded) {
142
+ const d = decoded || {};
143
+ if (d.shape != null && HOLD_SHAPES.includes(d.shape)) return { shape: d.shape, declared: true, invalid: null };
144
+ const parsed = parseWakeLine(d.wake);
145
+ const ruling = parsed.ok && parsed.conditions.some((c) => c.kind === 'ruling');
146
+ return { shape: ruling ? 'ask' : 'wait', declared: false, invalid: d.shape != null ? String(d.shape) : null };
147
+ }
148
+
120
149
  /**
121
150
  * `{label, owner, wake, because?}` → the hold comment. `wake` is the field as written (conditions
122
151
  * joined by `, `); pass an array to have it joined. `because` null/absent → the `Hold:` line alone.
123
152
  * The codec writes what it is given — checking `wake` against the vocabulary is `parseWakeLine`'s job.
124
153
  */
125
- function encodeHold({ label, owner, wake, because } = {}) {
154
+ function encodeHold({ label, owner, shape, wake, because } = {}) {
126
155
  const w = Array.isArray(wake) ? wake.join(', ') : wake;
127
- const line = `Hold: ${label} — owner: ${owner} — wake: ${w}`;
156
+ const sh = shape == null ? '' : ` — shape: ${shape}`;
157
+ const line = `Hold: ${label} — owner: ${owner}${sh} — wake: ${w}`;
128
158
  return because == null ? line : `${line}\nBecause: ${because}`;
129
159
  }
130
160
 
@@ -133,20 +163,24 @@ function encodeHold({ label, owner, wake, because } = {}) {
133
163
  * line in the canonical shape. `because` is the second line's text when that line is `Because: …`
134
164
  * and nothing follows it; anything else after the `Hold:` line makes the comment not a hold record
135
165
  * (null) rather than a partially-read one. `wake` is the raw field — `parseWakeLine(wake)` decides
136
- * whether it names a wake at all.
166
+ * whether it names a wake at all. `shape` is present ONLY when the line declares one (#569), as
167
+ * written — `holdShape` decides whether it is in the closed set; absent means "infer from wake".
137
168
  */
138
169
  function decodeHold(body) {
139
170
  const lines = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim().split('\n');
140
171
  const h = HOLD_RE.exec(lines[0]);
141
172
  if (!h) return null;
142
- if (lines.length === 1) return { label: h[1], owner: h[2], wake: h[3], because: null };
173
+ const head = h[3] == null
174
+ ? { label: h[1], owner: h[2], wake: h[4] }
175
+ : { label: h[1], owner: h[2], shape: h[3], wake: h[4] };
176
+ if (lines.length === 1) return { ...head, because: null };
143
177
  const b = lines.length === 2 ? BECAUSE_RE.exec(lines[1]) : null;
144
178
  if (!b) return null;
145
- return { label: h[1], owner: h[2], wake: h[3], because: b[1] };
179
+ return { ...head, because: b[1] };
146
180
  }
147
181
 
148
182
  module.exports = {
149
183
  WAKE_KINDS, CHECKABLE_KINDS, WAKE_KINDS_TEXT,
150
184
  parseWake, parseWakeLine, parseQualifiedIssueRef,
151
- HOLD_RE, BECAUSE_RE, encodeHold, decodeHold,
185
+ HOLD_RE, BECAUSE_RE, HOLD_SHAPES, encodeHold, decodeHold, holdShape,
152
186
  };
@@ -4,7 +4,10 @@
4
4
  * (CONVENTIONS.md §6, *The release rung*), as encode/decode pairs. Pure and synchronous.
5
5
  *
6
6
  * tracking marker — `<!-- colab:release version=vX.Y.Z -->`, the first line of a tracking
7
- * issue's body. Only the marker identifies the version, never the title.
7
+ * issue's body. Only the marker identifies the version, never the title —
8
+ * and only at the START of the body (leading whitespace tolerated): a body
9
+ * that merely MENTIONS the marker further down is talking about releases,
10
+ * not recording one, and is never adopted as the record (#575).
8
11
  * event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
9
12
  * tracking issue, keys in the order written. Its exact presence is what makes
10
13
  * a re-run post nothing twice, so key order is part of the wire format.
@@ -16,7 +19,7 @@
16
19
  */
17
20
 
18
21
  const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
19
- const TRACKING_MARKER_RE = /<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
22
+ const TRACKING_MARKER_RE = /^\s*<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
20
23
  const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
21
24
  const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.$/;
22
25
 
@@ -24,7 +27,7 @@ const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nRelea
24
27
  function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
25
28
 
26
29
  /** The version a body's tracking marker declares, or null — a marker naming a non-canonical
27
- * version (a leading zero) declares nothing. */
30
+ * version (a leading zero) declares nothing, and neither does one anywhere but the body's start. */
28
31
  function decodeTrackingMarker(body) {
29
32
  const m = TRACKING_MARKER_RE.exec(String(body || ''));
30
33
  return m && VERSION_RE.test(m[1]) ? m[1] : null;
@@ -656,6 +656,39 @@
656
656
  "because": null
657
657
  },
658
658
  "note": "synthetic: a Hold line with no Because line"
659
+ },
660
+ {
661
+ "wire": "Hold: blocked:needs-maintainer — owner: maintainer — shape: task — wake: ruling\nBecause: run the signing script on the release machine; only the maintainer holds the key.",
662
+ "decoded": {
663
+ "label": "blocked:needs-maintainer",
664
+ "owner": "maintainer",
665
+ "shape": "task",
666
+ "wake": "ruling",
667
+ "because": "run the signing script on the release machine; only the maintainer holds the key."
668
+ },
669
+ "note": "synthetic (#569): a chore declared as a task — without shape: its `ruling` wake would read as a choice"
670
+ },
671
+ {
672
+ "wire": "Hold: deferred:external-party — owner: upstream maintainers — shape: wait — wake: issueClosed:OWNER/REPO#22, review-by:2026-11-02\nBecause: the design mirrors one still open upstream.",
673
+ "decoded": {
674
+ "label": "deferred:external-party",
675
+ "owner": "upstream maintainers",
676
+ "shape": "wait",
677
+ "wake": "issueClosed:OWNER/REPO#22, review-by:2026-11-02",
678
+ "because": "the design mirrors one still open upstream."
679
+ },
680
+ "note": "synthetic (#569): a declared wait"
681
+ },
682
+ {
683
+ "wire": "Hold: needs-decision — owner: @maintainer — shape: ask — wake: ruling\nBecause: pick the import model; the options block in the body recommends A.",
684
+ "decoded": {
685
+ "label": "needs-decision",
686
+ "owner": "@maintainer",
687
+ "shape": "ask",
688
+ "wake": "ruling",
689
+ "because": "pick the import model; the options block in the body recommends A."
690
+ },
691
+ "note": "synthetic (#569): a declared ask — the choice itself lives in the issue's decision:options block"
659
692
  }
660
693
  ],
661
694
  "notHolds": [
@@ -677,6 +710,18 @@
677
710
  "decoded": "v0.1.6"
678
711
  }
679
712
  ],
713
+ "notTracking": [
714
+ {
715
+ "wire": "Finalize keeps one tracking issue per version; its body starts <!-- colab:release version=v0.1.6 --> and nothing else counts.",
716
+ "decoded": null,
717
+ "note": "synthetic (#575): an issue ABOUT releases that mentions the marker mid-body — never adopted as the record"
718
+ },
719
+ {
720
+ "wire": "fix: release lookup\n\n```\n<!-- colab:release version=v0.1.6 -->\n```",
721
+ "decoded": null,
722
+ "note": "synthetic (#575): the marker quoted on a later line, not the body's first"
723
+ }
724
+ ],
680
725
  "events": [
681
726
  {
682
727
  "wire": "<!-- colab:release-event candidate=v0.1.6-rc.1 -->",
@@ -35,6 +35,7 @@ const DESCRIPTOR = '.github/project.yml';
35
35
  const TUNING = Object.freeze({
36
36
  'ship-batch': (doc) => { const r = shipBatch.parseShipBatch(doc); return r.valid ? null : r.reason; },
37
37
  'ship-batch-wait': (doc) => { const r = shipBatch.parseShipBatchWait(doc); return r.valid ? null : r.reason; },
38
+ [shipBatch.STEPS_KEY]: (doc) => { const r = shipBatch.parseShipBatchSteps(doc); return r.valid ? null : r.reason; },
38
39
  'ci-wait-factor': (doc) => { const r = ciProfile.parseFactor(doc); return r.valid ? null : r.reason; },
39
40
  [thresholds.KEY]: (doc) => { const r = thresholds.parseThresholds(doc); return r.problems.length ? r.problems.join('; ') : null; },
40
41
  });
@@ -49,8 +50,8 @@ const AUTHORITY_KEYS = Object.freeze([
49
50
  'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
50
51
  ]);
51
52
 
52
- /** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`). */
53
- const VALUE_RE = /^[A-Za-z0-9._-]+$/;
53
+ /** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`, `2,4,8`). */
54
+ const VALUE_RE = /^[A-Za-z0-9._,-]+$/;
54
55
 
55
56
  /**
56
57
  * `ship-batch` → `{ top: 'ship-batch', sub: null }`; `thresholds.hot-file-count` → `{ top:
@@ -89,7 +90,7 @@ function replaceValue(line, value) {
89
90
  * old }` (`old` is the previous raw value, or null when the key was absent), or `{ problem }`.
90
91
  */
91
92
  function editText(text, keyPath, value) {
92
- if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ -)` };
93
+ if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ , -)` };
93
94
  const src = String(text);
94
95
  const eol = src.endsWith('\n') ? '' : '\n';
95
96
  const lines = src.split('\n');
@@ -300,6 +300,47 @@ function evaluateIssue({ labels, comments, labelEvents = null, body, trust } = {
300
300
  return { recorded, gated, contradiction: recorded && gated, pair, pending, decisions, ask, unshapedAsk };
301
301
  }
302
302
 
303
+ /**
304
+ * #582: the ask records on this issue still waiting on an answer — what `colab decision --record`
305
+ * shows the recorder, so the ruling can name the ask it settles (`--answers <id>`). A consumer that
306
+ * tracks asks reads a nameless ruling as answering the issue's ONLY open ask; with two or more it
307
+ * cannot tell which one the ruling meant.
308
+ *
309
+ * An ask is OPEN when no answer comes AFTER its latest ask record (same id; a re-ask at a higher
310
+ * version reopens it). An answer is either an answer record naming the id, or a live `⚖ Decision
311
+ * recorded` whose `answers` field is that id. Order is by `createdAt`, then position inside one
312
+ * comment. Deliberately NOT trust-filtered: this only decides what to SHOW and whether a nameless
313
+ * record is ambiguous — it gates no start and authorizes nothing.
314
+ *
315
+ * Returns [{id, version, at, ns}], oldest-asked first.
316
+ */
317
+ function openAsks(comments) {
318
+ const list = Array.isArray(comments) ? comments : [];
319
+ const sorted = list
320
+ .map((c, i) => ({ c, i }))
321
+ .sort((a, b) => (a.c.createdAt < b.c.createdAt ? -1 : a.c.createdAt > b.c.createdAt ? 1 : a.i - b.i));
322
+ const asks = new Map(); // id -> {id, version, at, ns, pos}
323
+ const answers = []; // {id, pos}
324
+ sorted.forEach(({ c }, ci) => {
325
+ const body = String(c.body || '');
326
+ for (const a of codec.askRecords(body)) {
327
+ asks.set(a.id, { id: a.id, version: a.version, at: c.createdAt || null, ns: a.ns, pos: [ci, a.index] });
328
+ }
329
+ for (const r of codec.answerRecords(body)) answers.push({ id: r.ask, pos: [ci, r.index] });
330
+ });
331
+ const live = new Set(liveDecisions(list).map((d) => d.at));
332
+ sorted.forEach(({ c }, ci) => {
333
+ if (!live.has(c.createdAt)) return;
334
+ const d = codec.decodeDecision(c.body);
335
+ if (d && d.answers && d.answers !== '-') answers.push({ id: d.answers, pos: [ci, 0] });
336
+ });
337
+ const after = (p, q) => p[0] > q[0] || (p[0] === q[0] && p[1] > q[1]);
338
+ return [...asks.values()]
339
+ .filter((a) => !answers.some((r) => r.id === a.id && after(r.pos, a.pos)))
340
+ .sort((a, b) => (after(a.pos, b.pos) ? 1 : -1))
341
+ .map(({ id, version, at, ns }) => ({ id, version, at, ns }));
342
+ }
343
+
303
344
  module.exports = {
304
345
  DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
305
346
  decisionCommentBody, reopenCommentBody,
@@ -308,4 +349,5 @@ module.exports = {
308
349
  OPTIONS_RE, PAIR_VERDICTS, pairVerdict,
309
350
  MOCKUP_RE, mockupUrls, ASK_SHAPES, askShape,
310
351
  evaluateIssue,
352
+ openAsks,
311
353
  };
@@ -19,6 +19,19 @@ const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
19
19
  const DOCS_DIR = 'docs/';
20
20
  /** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
21
21
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
22
+ /**
23
+ * #570: build inputs that happen to end in `.txt` — a suite installs or compiles from them, so a change
24
+ * to one changes behaviour. Never documentation, at any depth: a Python dependency manifest exactly as
25
+ * the cure rule names one (cure-diff.js isPythonManifest — a name containing `requirements`, or under a
26
+ * `requirements/` directory, any case), a pip constraints file, and `CMakeLists.txt`. A `.txt` pulled
27
+ * in by `-r`/`-c` under some other name is NOT caught by name — a repo with one lists it in
28
+ * `ci-docs-skip`.
29
+ */
30
+ function buildInput(p, base) {
31
+ // Lazy: cure-diff.js requires this module at load time.
32
+ if (require('./cure-diff').isPythonManifest(p)) return true;
33
+ return /constraints.*\.txt$/i.test(base) || base === 'CMakeLists.txt';
34
+ }
22
35
  /** Config directories: nothing under them is documentation, at any depth. */
23
36
  const NEVER_DIRS = Object.freeze(['.claude', '.github', '.githooks']);
24
37
  /**
@@ -40,6 +53,7 @@ function pathReason(p) {
40
53
  const segs = String(p).split('/');
41
54
  const base = segs[segs.length - 1];
42
55
  if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
56
+ if (buildInput(String(p), base)) return `${base} is a build input, not documentation`;
43
57
  const dir = segs.slice(0, -1).find((s) => NEVER_DIRS.includes(s));
44
58
  if (dir) return `under ${dir}/ (config)`;
45
59
  const dirs = segs.slice(0, -1);
@@ -164,7 +178,40 @@ function directChanges(git, repo, trunk, since) {
164
178
  return { ...verdict, commits: shas.length };
165
179
  }
166
180
 
181
+ /**
182
+ * #570: `ci-docs-skip:` in project.yml — the opt-in to the CI templates' docs-only mode. Absent (or
183
+ * null) = off. A list = on; each member is a repo path whose changes always run the suite even though
184
+ * this module calls them documentation (`docs/api/` feeding a generator). `[]` = on, nothing excluded.
185
+ *
186
+ * The CI guard parses the same shape in shell and reads anything else as "not opted in" — the
187
+ * stricter direction — so an invalid value here is a finding: a declaration that silently does
188
+ * nothing. Members are plain paths (the guard matches `p == x` or `p` under `x/`): no glob, no `..`
189
+ * or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
190
+ */
191
+ const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
192
+ function parseCiDocsSkip(doc) {
193
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
194
+ const v = has ? doc[CI_DOCS_SKIP_KEY] : null;
195
+ if (v === null || v === undefined) {
196
+ return { declared: false, valid: true, on: false, exclude: null, reason: 'ci-docs-skip absent — a docs-only change runs the full CI suite (#570)' };
197
+ }
198
+ const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
199
+ reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none); the CI guard reads anything else as not opted in, so docs-only changes run the full suite` });
200
+ if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
201
+ const exclude = [];
202
+ for (const m of v) {
203
+ const s = typeof m === 'string' ? m.replace(/\/+$/, '') : null;
204
+ if (!s || !/^[A-Za-z0-9._/-]+$/.test(s) || s.startsWith('/') || s.split('/').some((x) => x === '..' || x === '.' || x === '')) {
205
+ return bad(`lists ${JSON.stringify(m)}, which is not a plain repo path`);
206
+ }
207
+ exclude.push(s);
208
+ }
209
+ return { declared: true, valid: true, on: true, exclude,
210
+ reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change skips the CI suite' };
211
+ }
212
+
167
213
  module.exports = {
168
214
  DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
169
215
  pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
216
+ CI_DOCS_SKIP_KEY, parseCiDocsSkip,
170
217
  };