@futurelastic/colab-handbook 1.13.0-rc.8 → 1.13.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.
@@ -39,6 +39,12 @@
39
39
  * On a route whose final is a human act (`deploy-tag`) --auto never tags: it stops at
40
40
  * candidate-ready and posts the one command, number pre-filled.
41
41
  *
42
+ * `--tag` (#548) may name ANY open candidate, not only the newest, so a human can release what
43
+ * finished testing without trunk freezing for a whole period. An older one is held to the same rule
44
+ * --auto applies to it: its own test period and its own trunk window are required on every row
45
+ * (selectCandidate marks it `older`; decide() reads that). Newer candidates stay open, and a
46
+ * version's record closes as superseded only once a final ABOVE it is tagged.
47
+ *
42
48
  * Before ANY final, the three #424 pre-tag checks (release-tag.js preTagChecks) are required:
43
49
  * manifest-version, on-trunk, outranks-final.
44
50
  *
@@ -71,7 +77,7 @@ const STATES = Object.freeze([
71
77
 
72
78
  const CONDITIONS = Object.freeze([
73
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
74
- 'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
75
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
76
82
  ]);
77
83
 
@@ -134,6 +140,8 @@ function trackingBody({ version, row, final, testPeriodDays }) {
134
140
  * { kind: 'already-final', version, detail }
135
141
  * { kind: 'refused', detail }
136
142
  * { kind: 'candidate', candidate: { tag, version, n, sha, cutAt }, superseded: [version], detail }
143
+ * { kind: 'candidate', older: true, newest: <tag>, … } #548: `pin` names an open candidate that
144
+ * is not the newest — decide() then requires its own test period and trunk window, as --auto does
137
145
  */
138
146
  function selectCandidate(tags, pin, remote = 'origin') {
139
147
  const all = tags || [];
@@ -159,16 +167,32 @@ function selectCandidate(tags, pin, remote = 'origin') {
159
167
  const newest = open[open.length - 1];
160
168
  const superseded = [...new Set(open.map((x) => x.p.version).filter((v) => v !== newest.p.version))];
161
169
 
162
- if (pin && pin !== newest.t.name) {
163
- return { kind: 'refused', detail: `--tag ${pin} is not the newest candidate (${newest.t.name}) — a final names the candidate that was actually tested last` };
164
- }
165
- const t = newest.t;
170
+ // #548: --tag may name an OLDER open candidate. It is then judged on its own clock, exactly as
171
+ // --auto judges it (decide() makes test-period and trunk-green over its own window required), so a
172
+ // human can release what finished testing while trunk keeps merging; the newer candidates stay open.
173
+ const chosen = pin ? open.find((x) => x.t.name === pin) : newest;
174
+ if (!chosen) return { kind: 'refused', detail: `--tag ${pin} is not an open candidate` };
175
+ const older = chosen !== newest;
176
+ const t = chosen.t;
166
177
  if (!t.annotated || !String(t.subject || '').endsWith(CUT_SUBJECT_SUFFIX)) {
167
178
  return { kind: 'refused', detail: `${t.name} was not made by \`colab release cut\` (not an annotated tag whose message ends "${CUT_SUBJECT_SUFFIX}") — a candidate cut by hand is never finalized (CONVENTIONS.md §6)` };
168
179
  }
169
180
  if (!t.onMain) return { kind: 'refused', detail: `${t.name} (${String(t.sha).slice(0, 7)}) is not on ${remote}/main — candidates are cut from main` };
170
181
  if (!t.date || Number.isNaN(Date.parse(t.date))) return { kind: 'refused', detail: `${t.name} has no readable tagger date — the test period cannot be placed` };
171
182
 
183
+ if (older) {
184
+ // Only versions BELOW the pinned one are superseded by it; a newer version's candidates stay open.
185
+ const below = [...new Set(open.map((x) => x.p.version).filter((v) => compareVersions(v, chosen.p.version) < 0))];
186
+ const newer = open.filter((x) => compareVersions(x.p.version, chosen.p.version) > 0 || (x.p.version === chosen.p.version && x.p.n > chosen.p.n)).map((x) => x.t.name);
187
+ return {
188
+ kind: 'candidate',
189
+ older: true,
190
+ newest: newest.t.name,
191
+ candidate: { tag: t.name, version: chosen.p.version, n: chosen.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
192
+ superseded: below,
193
+ detail: `${t.name} at ${String(t.sha).slice(0, 7)}, cut ${new Date(t.date).toISOString()} — an older candidate, judged on its own clock (newer, still open: ${newer.join(', ')})${below.length ? `; supersedes ${below.join(', ')}` : ''}`,
194
+ };
195
+ }
172
196
  return {
173
197
  kind: 'candidate',
174
198
  candidate: { tag: t.name, version: newest.p.version, n: newest.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
@@ -295,9 +319,72 @@ function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
295
319
  return { line, next };
296
320
  }
297
321
 
322
+ // ---- the run that cut the candidate (#566) ------------------------------------------------------
323
+
324
+ // Slack around the tag's cut instant: the tagger date is the runner's clock, a run's createdAt /
325
+ // updatedAt are GitHub's, both to the second.
326
+ const CUT_RUN_SLACK_MS = 120000;
327
+
328
+ /**
329
+ * Did the run that CUT this candidate finish what it does after the cut? `rows` are the workflow
330
+ * runs at the candidate's commit (`git.ghRunsAtCommit`, null = unread), WITHOUT the #425 own-workflow
331
+ * filter — the release workflow is exactly the one this reads; only the calling run itself is dropped
332
+ * (`ownRunId`), since a run cannot vouch for or against itself while it is still running.
333
+ *
334
+ * The cutter is every run that was in progress at `cutAt` (the annotated tag's date): created no later
335
+ * than the cut, and either not finished or finished no earlier than it. Each one must have concluded
336
+ * `success`. Measured (#566): the run that cut a candidate had its image-publish job CANCELLED; ci-green
337
+ * and full-suite set that run aside as superseded (#461 — a cancelled run never stands for its workflow
338
+ * while that workflow has any other run at the sha) and counted an EARLIER run of the same workflow at
339
+ * the same commit that concluded success having cut nothing. finalize said candidate-ready for a
340
+ * candidate whose image did not exist. Here only the cutter vouches, and cancelled is a failure: a run
341
+ * cancelled after its cut may have stopped before its publish.
342
+ *
343
+ * A CANCELLED row whose job count `jobCount(databaseId)` reads 0 never ran — the measured shape of a
344
+ * pending run GitHub cancelled out of the release workflow's concurrency group when a newer one queued —
345
+ * so it cut nothing and is dropped. Asked lazily, only for a cancelled row; null (unread) keeps it.
346
+ *
347
+ * No run in progress at the cut → ok: the candidate was cut by hand (`colab release cut` outside a
348
+ * workflow), and no run owes it anything. A completed row with no `updatedAt` (an older read) cannot
349
+ * be placed around the cut and is not counted — absence of the field never refuses.
350
+ *
351
+ * Returns { ok, detail, runs } — `runs` the cutter rows' ids, for the report.
352
+ */
353
+ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } = {}) {
354
+ if (rows === null || rows === undefined) return { ok: false, detail: `the workflow runs at ${tag} could not be read — the run that cut it cannot be checked`, runs: [] };
355
+ const cut = Date.parse(cutAt);
356
+ if (Number.isNaN(cut)) return { ok: false, detail: `${tag} carries no readable cut time — the run that cut it cannot be found`, runs: [] };
357
+ const own = ownRunId === null || ownRunId === undefined || ownRunId === '' ? null : String(ownRunId);
358
+ const cutters = rows.filter((r) => {
359
+ if (!r || (own && String(r.databaseId) === own)) return false;
360
+ const created = Date.parse(r.createdAt);
361
+ if (Number.isNaN(created) || created > cut + CUT_RUN_SLACK_MS) return false;
362
+ if (r.status !== 'completed') return true;
363
+ const ended = Date.parse(r.updatedAt);
364
+ if (Number.isNaN(ended) || ended < cut - CUT_RUN_SLACK_MS) return false;
365
+ if (r.conclusion === 'cancelled' && typeof jobCount === 'function' && r.databaseId != null && jobCount(r.databaseId) === 0) return false;
366
+ return true;
367
+ });
368
+ const ids = cutters.map((r) => r.databaseId).filter((x) => x !== null && x !== undefined);
369
+ const name = (r) => `${r.workflowName || '(unnamed workflow)'} run ${r.databaseId != null ? r.databaseId : '(id unread)'}`;
370
+ if (!cutters.length) return { ok: true, detail: `no workflow run at ${tag} was in progress when it was cut (${cutAt}) — cut by hand, no run's publish to wait for`, runs: [] };
371
+ const bad = cutters.filter((r) => !(r.status === 'completed' && r.conclusion === 'success'));
372
+ if (!bad.length) return { ok: true, detail: `the run that cut ${tag} (${cutters.map(name).join(', ')}) concluded success`, runs: ids };
373
+ const how = (r) => (r.status === 'completed' ? `concluded ${r.conclusion || 'with no conclusion'}` : `is still ${r.status || 'running'}`);
374
+ const rerun = bad.filter((r) => r.status === 'completed' && r.databaseId != null).map((r) => `gh run rerun ${r.databaseId} --failed`);
375
+ return {
376
+ ok: false,
377
+ detail: `the run that cut ${tag} — ${bad.map((r) => `${name(r)} ${how(r)}`).join('; ')} — did not finish what it publishes after the cut (an image, a package, a Release): ${tag}'s artifacts may not exist. An earlier green run at the same commit that cut nothing cannot vouch for it (#566). ${rerun.length ? `Re-run it (${rerun.join('; ')}) and finalize again, or cut a new candidate.` : 'Wait for it to finish, then finalize again.'}`,
378
+ runs: ids,
379
+ };
380
+ }
381
+
298
382
  // ---- the test period ----------------------------------------------------------------------------
299
383
 
300
- /** { start, endsAt, elapsed, detail } — start = max(cutAt, trackingCreatedAt). All ISO strings. */
384
+ /**
385
+ * { start, endsAt, days, elapsed, detail } — start = max(cutAt, trackingCreatedAt), ISO strings. `days` 0
386
+ * (#549, human final only) is no test period: elapsed at once, and the detail says so.
387
+ */
301
388
  function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
302
389
  const cut = Date.parse(cutAt);
303
390
  const created = trackingCreatedAt ? Date.parse(trackingCreatedAt) : NaN;
@@ -310,8 +397,11 @@ function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
310
397
  return {
311
398
  start: new Date(startMs).toISOString(),
312
399
  endsAt: new Date(endMs).toISOString(),
400
+ days: testPeriodDays,
313
401
  elapsed,
314
- detail: elapsed
402
+ detail: testPeriodDays === 0
403
+ ? 'no test period (release.test-period: 0d, a human final — the human\'s finalize is the test, #549)'
404
+ : elapsed
315
405
  ? `${testPeriodDays}d test period from ${new Date(startMs).toISOString()} ended ${new Date(endMs).toISOString()}`
316
406
  : `${testPeriodDays}d test period from ${new Date(startMs).toISOString()} ends ${new Date(endMs).toISOString()} (${hours}h left)`,
317
407
  };
@@ -450,6 +540,7 @@ function handoffCommand(tag) {
450
540
  * trunk trunkGreenVerdict(...)
451
541
  * regressions regressionVerdict(...)
452
542
  * ci, suite, schema, switches { ok, detail }
543
+ * cutRun #566 — cutRunVerdict(): the run that cut the candidate concluded success
453
544
  * finalGrant #441 — release-policy.js finalGrantVerdict() of policy.effective.finalGrant (only
454
545
  * read when the policy carries one; absent = unresolved, never a grant)
455
546
  * migrations #441 — migrationGrantVerdict() (only read when the policy carries a grant)
@@ -517,11 +608,15 @@ function decide(facts) {
517
608
  }
518
609
  const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
519
610
  add('regressions', reg.ok, reg.detail);
611
+ // #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
612
+ // --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
613
+ // no longer explains why THIS one, and its own clean period is what does.
614
+ const ownClock = auto || !!s.older;
520
615
  const per = f.period || { elapsed: false, detail: 'not measured' };
521
- add('test-period', per.elapsed, per.detail, auto);
616
+ add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
522
617
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
523
- add('trunk-green', tr.ok, tr.detail, auto);
524
- for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
618
+ add('trunk-green', tr.ok, tr.detail, ownClock);
619
+ for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['cut-run', f.cutRun], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
525
620
  add(condition, v && v.ok, v ? v.detail : 'not measured');
526
621
  }
527
622
  // #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
@@ -533,14 +628,14 @@ function decide(facts) {
533
628
  }
534
629
 
535
630
  if (held.length) return out('held');
536
- if ((reg.permanent) || (auto && tr.permanent)) return out('needs-new-candidate');
631
+ if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
537
632
  const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
538
633
  if (blocking.length) return out('refused');
539
- if (auto) {
634
+ if (ownClock) {
540
635
  if (!tr.ok && !tr.pending) return out('refused');
541
636
  if (!per.elapsed || tr.pending) return out('testing');
542
- return out('finalized', { finalTag: cand.version, grant: grantUsed });
543
637
  }
638
+ if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
544
639
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
545
640
  return out('finalized', { finalTag: cand.version });
546
641
  }
@@ -590,7 +685,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
590
685
  '',
591
686
  `Candidate: ${candidate.tag}`,
592
687
  `Commit: ${candidate.sha}`,
593
- period ? `Test period: ${period.start} -> ${period.endsAt}` : null,
688
+ period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
594
689
  `Finalized by: ${actor}`,
595
690
  verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
596
691
  '',
@@ -603,7 +698,7 @@ module.exports = {
603
698
  STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
604
699
  parseVersion, compareVersions, parseCandidate,
605
700
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
606
- selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
701
+ selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
607
702
  handoffCommand, decide, tagMessage, migrationGrantVerdict,
608
703
  carriedIssues, previousFinal, releasedEvent, releasedComment,
609
704
  };
@@ -11,7 +11,7 @@
11
11
  * route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | deploy-tag-fast | live
12
12
  * candidates: auto # auto | off
13
13
  * candidates-per-day: 1 # positive integer — an opt-in cap; no route has one by default (#443)
14
- * test-period: 3d # <N>d, never below the route's 3 days
14
+ * test-period: 3d # <N>d, never below the route's 3 days — or 0d where the final is human (#549)
15
15
  * final: auto # auto | human
16
16
  * guard-run: <command> # #422 — a breaking-change detector `release cut --auto` runs
17
17
  * guard-result: <path> # #422 — or the file an earlier CI step wrote its result to
@@ -95,6 +95,8 @@ const FINAL = Object.freeze(['auto', 'human']);
95
95
  // The routes' own test period (CONVENTIONS.md §6: "The test period is 3 days"). A floor, not a
96
96
  // suggestion: a declared period may be longer, never shorter.
97
97
  const TEST_PERIOD_DAYS = 3;
98
+ // #549: the one value below the floor — no test period at all, and only where the final is human.
99
+ const TEST_PERIOD_ZERO = '0d';
98
100
 
99
101
  /**
100
102
  * Each route's own policy — CONVENTIONS.md §6, *Release routes*, row for row.
@@ -369,8 +371,14 @@ function evaluateRelease(cfg) {
369
371
  const days = parseTestPeriod(v);
370
372
  if (days === null) fail(`release.test-period is ${JSON.stringify(v)}, expected a whole number of days like "${TEST_PERIOD_DAYS}d"`);
371
373
  else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} cuts no candidate, so there is no test period. Remove the key`);
372
- else if (days < effective.testPeriodDays) {
373
- widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer`);
374
+ else if (days === 0 && effective.final === 'human') {
375
+ // #549: a human final may declare no test period — the human's finalize is the test.
376
+ effective.testPeriodDays = 0;
377
+ } else if (days === 0) {
378
+ widen('test-period', v, `the final is automatic here, so the test period is the only look a candidate gets before it becomes a release — no human looked. ${TEST_PERIOD_ZERO} fits only a human final (final: human). Set ${effective.testPeriodDays}d or longer`);
379
+ } else if (days < effective.testPeriodDays) {
380
+ widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer` +
381
+ (effective.final === 'human' ? ` — or ${TEST_PERIOD_ZERO} for no test period, since the final here is a human act` : ''));
374
382
  } else effective.testPeriodDays = days;
375
383
  }
376
384
 
@@ -46,6 +46,70 @@ function parseShipBatch(doc) {
46
46
  return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
47
47
  }
48
48
 
49
+ const WAIT_KEY = 'ship-batch-wait';
50
+ const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
51
+
52
+ /**
53
+ * #555: `ship-batch-wait:` from project.yml — how long a LONE ready candidate waits for a partner
54
+ * before it lands alone. A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
55
+ * bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
56
+ *
57
+ * Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
58
+ * (owner, 2026-10-07: "Should not set any hard code number") — the repo chooses, from its own
59
+ * history. Anything malformed FAILS CLOSED to no wait, with the reason: a bad value must never delay
60
+ * a landing. The audit and the CI templates' descriptor check fail the same values.
61
+ */
62
+ function parseShipBatchWait(doc) {
63
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, WAIT_KEY);
64
+ if (!has || doc[WAIT_KEY] === null || doc[WAIT_KEY] === undefined) {
65
+ return { sec: 0, declared: false, valid: true, reason: `${WAIT_KEY} absent` };
66
+ }
67
+ const v = doc[WAIT_KEY];
68
+ const m = typeof v === 'string' ? /^(\d+)([smh])$/.exec(v.trim()) : null;
69
+ if (m) {
70
+ const sec = Number(m[1]) * WAIT_UNITS[m[2]];
71
+ if (Number.isSafeInteger(sec)) return { sec, declared: true, valid: true, reason: `${WAIT_KEY}: ${v.trim()}` };
72
+ }
73
+ return { sec: 0, declared: true, valid: false, reason: `${WAIT_KEY} is ${JSON.stringify(v)}, expected a whole number with a unit — 90s, 6m, 1h (omit for no wait)` };
74
+ }
75
+
76
+ /**
77
+ * #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
78
+ * Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
79
+ * already in flight — the lane is otherwise idle by then):
80
+ * n parseShipBatch(doc).n
81
+ * waitSec parseShipBatchWait(doc).sec (0 = absent, zero, or malformed)
82
+ * eligibleCount members that passed their own gates
83
+ * readySinceMs when the lone member became ready — its head CI's last update, else its head
84
+ * commit's date; null = unreadable
85
+ * nowMs the clock
86
+ * Out: `{ wait: true, leftSec }` or `{ wait: false, reason }`. The window is counted from the member's
87
+ * own ready time, not from this call, so the command stays stateless and re-entrant: every call
88
+ * re-derives how much is left, on any machine, and the window can never restart.
89
+ */
90
+ function partnerWait({ n, waitSec, eligibleCount, readySinceMs, nowMs }) {
91
+ if (!(n > 1)) return { wait: false, reason: 'not-enabled' };
92
+ if (!(waitSec > 0)) return { wait: false, reason: 'no-window' };
93
+ if (eligibleCount !== 1) return { wait: false, reason: eligibleCount > 1 ? 'has-partner' : 'none-ready' };
94
+ if (!Number.isFinite(readySinceMs) || !Number.isFinite(nowMs)) return { wait: false, reason: 'ready-time-unread' };
95
+ const leftSec = Math.ceil(waitSec - Math.max(0, nowMs - readySinceMs) / 1000);
96
+ if (leftSec <= 0) return { wait: false, reason: 'window-elapsed' };
97
+ return { wait: true, leftSec };
98
+ }
99
+
100
+ /**
101
+ * When did a member become ready? The newest `updatedAt` among its finished head runs (a run's last
102
+ * update is its completion), else — no run, because none can arrive — its head commit's date.
103
+ * Null when neither reads; the caller then does not wait.
104
+ */
105
+ function readySince(rows, commitIso) {
106
+ const done = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
107
+ .map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
108
+ if (done.length) return Math.max(...done);
109
+ const c = Date.parse(commitIso || '');
110
+ return Number.isFinite(c) ? c : null;
111
+ }
112
+
49
113
  function batchRefName(baseSha) {
50
114
  return `${REF_PREFIX}${String(baseSha || '').slice(0, 7)}`;
51
115
  }
@@ -77,6 +141,48 @@ function parseMemberTrailers(messages) {
77
141
  return out;
78
142
  }
79
143
 
144
+ /**
145
+ * #554: a member dropped at build used to leave no trace in git — only a `✗ <member>: …` line on
146
+ * one terminal — so eviction rate could not be measured. The batch head now records each drop:
147
+ *
148
+ * Ship-Batch-Dropped: <ref> <branch>@<sha> <class>
149
+ *
150
+ * appended to the LAST built member's message (the head commit), so it reaches trunk with a landed
151
+ * batch and rides the head commit's message of a combined run that went red. `class` is one token
152
+ * from DROP_CLASSES; the human reason stays on the terminal. A branch (already pushed, so already
153
+ * public) and a sha, never a host — the same rule as memberTrailer.
154
+ */
155
+ const DROP_TRAILER_KEY = 'Ship-Batch-Dropped';
156
+ const DROP_CLASSES = ['conflict', 'generated-no-hook', 'hook-failed', 'hook-markers', 'squash-failed', 'empty', 'message', 'commit-failed'];
157
+
158
+ function droppedTrailer({ ref, branch, sha, cls }) {
159
+ const c = DROP_CLASSES.includes(cls) ? cls : 'other';
160
+ return `${DROP_TRAILER_KEY}: ${ref} ${branch}@${String(sha || '').slice(0, 12)} ${c}`;
161
+ }
162
+
163
+ /** Every `Ship-Batch-Dropped:` trailer across commit messages → [{ ref, branch, sha, cls }]. */
164
+ function parseDroppedTrailers(messages) {
165
+ const out = [];
166
+ for (const msg of messages || []) {
167
+ for (const line of String(msg || '').split('\n')) {
168
+ const m = new RegExp(`^${DROP_TRAILER_KEY}:\\s+(\\S+)\\s+(\\S+)@([0-9a-f]{7,40})\\s+([a-z-]+)\\s*$`).exec(line.trim());
169
+ if (m) out.push({ ref: m[1], branch: m[2], sha: m[3], cls: m[4] });
170
+ }
171
+ }
172
+ return out;
173
+ }
174
+
175
+ /**
176
+ * `msg` with `lines` appended to its final trailer block — never as a new paragraph, which would
177
+ * split the block and hide the earlier trailers from `git interpret-trailers`. Lines already
178
+ * present are not repeated (a rebuild re-composes the same message).
179
+ */
180
+ function appendTrailers(msg, lines) {
181
+ const body = String(msg || '').replace(/\s+$/, '');
182
+ const add = (lines || []).filter((l) => l && !body.split('\n').includes(l));
183
+ return add.length ? `${body}\n${add.join('\n')}\n` : `${body}\n`;
184
+ }
185
+
80
186
  /**
81
187
  * A member's OWN head CI, read as a joining class (§4 Branch CI):
82
188
  * green every run at its head finished, all success
@@ -315,8 +421,9 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
315
421
  }
316
422
 
317
423
  module.exports = {
318
- MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
319
- parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
424
+ MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
425
+ parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
426
+ droppedTrailer, parseDroppedTrailers, appendTrailers,
320
427
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
321
428
  batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
322
429
  };
@@ -190,10 +190,21 @@ function bodyShaClaims(message) {
190
190
  * an issue that carries no delivery-type label is still covered.
191
191
  */
192
192
  const TOOL_MARKS = ['🔒 Claimed', '✅ Released', '🚢 Shipped', '🔖 Referenced', '↩️ Sent back'];
193
+ /**
194
+ * #535: a comment whose WHOLE body is one signature line (`— <name> · <machine>/<session>`) is
195
+ * not evidence either. Some deployments post one after every comment; it records who spoke, never
196
+ * what was delivered. Only the bare line is excluded — a distill that merely ENDS in a signature
197
+ * still counts, so the test is on the whole trimmed body, single line, no `m` flag.
198
+ */
199
+ const SIGNATURE_ONLY = /^—[^\S\n][^\n]*\S$/;
200
+ function isSignatureOnly(body) {
201
+ return SIGNATURE_ONLY.test(body);
202
+ }
193
203
  function evidenceComments(comments) {
194
204
  return (Array.isArray(comments) ? comments : []).filter((c) => {
195
205
  const body = String((c && c.body) || '').trim();
196
206
  if (!body) return false;
207
+ if (isSignatureOnly(body)) return false;
197
208
  return !TOOL_MARKS.some((mark) => body.startsWith(mark));
198
209
  });
199
210
  }
@@ -312,6 +323,6 @@ function zeroClaimVerdict(issuesCount, branchName, brokenClaimsCount, { remoteOn
312
323
 
313
324
  module.exports = {
314
325
  branchIssueNumbers, commitIssueNumbers, corroborateIssues, branchType,
315
- subjectSanity, bodyShaClaims, evidenceComments, hasEvidence, TOOL_MARKS,
326
+ subjectSanity, bodyShaClaims, evidenceComments, hasEvidence, isSignatureOnly, TOOL_MARKS,
316
327
  closesCoverage, zeroClaimVerdict,
317
328
  };
@@ -0,0 +1,110 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/thresholds.js — repo-declared values for the ADVISORY thresholds (#560, epic #558).
4
+ *
5
+ * Before this module each of these numbers was one fleet-wide constant, written into a skill's
6
+ * prose or a tool's source. The ruling on #560: today's value stays as the documented default, and
7
+ * a repo may override it in `.github/project.yml`:
8
+ *
9
+ * thresholds:
10
+ * hot-file-count: 4
11
+ * hold-stale-days: 45
12
+ *
13
+ * Nothing changes for a repo that declares nothing. Only ADVISORY thresholds live here — a number
14
+ * that decides what gets flagged, ranked or warned about. Safety limits (a cap a repo may only
15
+ * tighten) and protocol counts are out of scope (epic #558) and keep their own fields.
16
+ *
17
+ * Every value is a whole number with a per-key floor (and, for a percent, a ceiling of 100), and the
18
+ * unit is in the key's name. That keeps the CI templates' shell copy of this rule (the descriptor
19
+ * check, #416) small enough to be held to this table by tools/lib/ci-template-descriptor-check.test.js.
20
+ *
21
+ * NO-DEFAULT keys (#556): `def: null`. The batch-history judgement has no fleet-wide number to fall
22
+ * back on — the owner's ruling is that none be hard-coded — so an undeclared one means "do not judge":
23
+ * its value is null, and its reader shows the measurement without an advisory.
24
+ *
25
+ * A malformed value — a typo'd key, a non-number, a number under the floor — falls back to the
26
+ * default and is reported; the audit and the descriptor check fail it. A typo'd key is a problem,
27
+ * not an ignored extra: silently reverting to the default is exactly the failure #416 measured.
28
+ *
29
+ * Pure: a parsed descriptor in, values out. Both YAML readers feed it — the CLI's (numbers come
30
+ * through as numbers) and the audit's (they come through as digit strings) — so it accepts both.
31
+ */
32
+
33
+ const KEY = 'thresholds';
34
+
35
+ /**
36
+ * key → { def, min, max?, what, where }. `where` names the one place that reads the value. `def: null`
37
+ * = no default (#556): undeclared means its reader does not judge. `max` absent = MAX_VALUE.
38
+ * Order is the order `colab thresholds` prints.
39
+ */
40
+ const SPEC = Object.freeze({
41
+ 'hot-file-count': { def: 3, min: 2, what: 'waiting issues on one path before triage files HOT FILE', where: 'skills/code-triage/3-hot-file.md' },
42
+ 'dependents-count': { def: 3, min: 1, what: 'open issues blocked_by one issue before triage ranks it as leverage', where: 'skills/code-triage/4-order.md' },
43
+ 'hold-stale-days': { def: 30, min: 1, what: 'days a hold\'s wake condition may stand unmoved before a human confirms it', where: 'tools/lib/disposition.js' },
44
+ 'smoke-minutes': { def: 3, min: 1, what: 'target run time of gate.smoke', where: 'skills/code-wrap/SKILL.md' },
45
+ 'claude-md-kb': { def: 40, min: 1, what: 'authored KB of CLAUDE.md plus its @-imports before the audit warns', where: 'audit/audit.mjs' },
46
+ 'claude-md-line-multiple': { def: 6, min: 2, what: 'longest line as a multiple of the file\'s median line before the audit warns', where: 'audit/audit.mjs' },
47
+ 'claude-md-line-floor-bytes': { def: 2048, min: 0, what: 'a line under this many bytes is never flagged on the multiple alone', where: 'audit/audit.mjs' },
48
+ 'transitional-days': { def: 180, min: 1, what: 'days a transitional descriptor value holds before the audit says how long', where: 'audit/audit.mjs' },
49
+ 'doc-budget-slack': { def: 100, min: 0, what: 'lines under a doc budget before check-doc-budget asks to lower it', where: 'scripts/check-doc-budget.mjs' },
50
+ // #556 — the audit's batch-history advisories (tools/lib/batch-history.js). No defaults, by ruling.
51
+ 'batch-min-samples': { def: null, min: 1, what: 'measured events a batch rate needs before the audit judges it (undeclared: any)', where: 'audit/audit.mjs --batch-history' },
52
+ 'batch-first-green-pct-min': { def: null, min: 0, max: 100, what: 'first-attempt green % of combined runs below which the audit suggests lowering ship-batch', where: 'audit/audit.mjs --batch-history' },
53
+ 'batch-eviction-pct-max': { def: null, min: 0, max: 100, what: '% of batch members dropped at build above which the audit flags eviction', where: 'audit/audit.mjs --batch-history' },
54
+ 'batch-overlap-pct': { def: null, min: 0, max: 100, what: '% of serial landings with a missed or near-miss partner at which the audit suggests opting in to ship-batch', where: 'audit/audit.mjs --batch-history' },
55
+ });
56
+
57
+ const DEFAULTS = Object.freeze(Object.fromEntries(Object.entries(SPEC).map(([k, s]) => [k, s.def])));
58
+
59
+ /** At most nine digits — the CI templates' shell check compares with `[ -ge ]`, which must not overflow. */
60
+ const MAX_VALUE = 999999999;
61
+
62
+ function wholeNumber(raw) {
63
+ if (typeof raw === 'number') return Number.isInteger(raw) && raw <= MAX_VALUE ? raw : NaN;
64
+ if (typeof raw === 'string' && /^\s*[0-9]{1,9}\s*$/.test(raw)) return Number(raw);
65
+ return NaN;
66
+ }
67
+
68
+ /**
69
+ * `doc` → `{ values, declared, problems }`. `values` always carries every key (the default where
70
+ * nothing valid was declared — null for a no-default key); `declared` names the keys whose declared value is in force;
71
+ * `problems` is one sentence per malformed entry, each ending with the default it fell back to.
72
+ */
73
+ function parseThresholds(doc) {
74
+ const values = Object.assign({}, DEFAULTS);
75
+ const declared = {};
76
+ const problems = [];
77
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, KEY);
78
+ const raw = has ? doc[KEY] : undefined;
79
+ if (raw === undefined || raw === null || raw === '') return { values, declared, problems };
80
+ if (typeof raw !== 'object' || Array.isArray(raw)) {
81
+ problems.push(`${KEY} must be a map of "name: whole number" pairs, got ${JSON.stringify(raw)} — every threshold keeps its default`);
82
+ return { values, declared, problems };
83
+ }
84
+ for (const [k, v] of Object.entries(raw)) {
85
+ const spec = SPEC[k];
86
+ if (!spec) {
87
+ problems.push(`${KEY}.${k} is not a known threshold (known: ${Object.keys(SPEC).join(', ')}) — ignored`);
88
+ continue;
89
+ }
90
+ if (v === null || v === undefined || v === '') continue; // an empty entry declares nothing
91
+ const n = wholeNumber(v);
92
+ const max = spec.max === undefined ? MAX_VALUE : spec.max;
93
+ if (!Number.isFinite(n) || n < spec.min || n > max) {
94
+ const range = spec.max === undefined ? `≥ ${spec.min}` : `${spec.min}–${spec.max}`;
95
+ problems.push(`${KEY}.${k} must be a whole number ${range}, got ${JSON.stringify(v)} — ${spec.def === null ? 'not declared, so not judged' : `using the default ${spec.def}`}`);
96
+ continue;
97
+ }
98
+ values[k] = n;
99
+ declared[k] = true;
100
+ }
101
+ return { values, declared, problems };
102
+ }
103
+
104
+ /** The resolved value of one key — the convenience a single consumer wants. Null = undeclared, no default. */
105
+ function thresholdValue(doc, key) {
106
+ if (!SPEC[key]) throw new Error(`unknown threshold ${key}`);
107
+ return parseThresholds(doc).values[key];
108
+ }
109
+
110
+ module.exports = { KEY, SPEC, DEFAULTS, MAX_VALUE, parseThresholds, thresholdValue };