@futurelastic/colab-handbook 1.21.0-rc.8 → 1.21.0-rc.9

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.
package/audit/audit.mjs CHANGED
@@ -149,6 +149,8 @@ const treeGreenLib = require("../tools/lib/tree-green.js");
149
149
  const docsOnlyLib = require("../tools/lib/docs-only.js");
150
150
  // #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
151
151
  const verifyRunsLib = require("../tools/lib/verify-runs.js");
152
+ // #736: `release-only-checks:` — read through the same module ship's release-only door uses.
153
+ const releaseOnlyLib = require("../tools/lib/release-only.js");
152
154
  // #410: the optional `gate:` block — read through the same module the skills name.
153
155
  const gateLib = require("../tools/lib/gate.js");
154
156
  // #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
@@ -268,7 +270,11 @@ function parseScalarValue(raw) {
268
270
  return val;
269
271
  }
270
272
 
271
- const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630
273
+ const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention", "release-only-checks"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630 · release-only-checks: #736
274
+ // #736: the one map whose KEYS are free text — a check's display name ("Install smoke", "CI / install (*)"),
275
+ // optionally quoted, never containing ":" — and whose every value is an INLINE list of paths. Still one
276
+ // level, still no block list: any other line under it is a finding.
277
+ const FREE_KEY_MAP_KEYS = new Set(["release-only-checks"]);
272
278
  // The one map whose pairs may hold an INLINE list (`coupled: [a, b]`) — still one level, still no block list (#630).
273
279
  const LIST_IN_MAP_KEYS = new Set(["contention"]);
274
280
  // A key whose empty value may open EITHER a block list or a one-level map: `migrations:` is a list of
@@ -295,6 +301,19 @@ function parseFlatYaml(text) {
295
301
  out[listKey].push(parseScalarValue(item[1]));
296
302
  return;
297
303
  }
304
+ if (mapKey !== null && FREE_KEY_MAP_KEYS.has(mapKey) && !item) {
305
+ const fp = line.match(/^(\s+)("[^"]+"|'[^']+'|[^\s#"'][^:#]*?)\s*:\s*(.*)$/);
306
+ const fpVal = fp ? fp[3].replace(/\s+#.*$/, "").trim() : "";
307
+ if (fp && (mapIndent === null || fp[1].length === mapIndent) && /^\[.*\]$/.test(fpVal)) {
308
+ if (mapIndent === null) mapIndent = fp[1].length;
309
+ if (out[mapKey] === null || typeof out[mapKey] !== "object") out[mapKey] = {};
310
+ const inner = fpVal.slice(1, -1).trim();
311
+ out[mapKey][fp[2]] = inner === "" ? [] : inner.split(",").map((x) => parseScalarValue(x));
312
+ return;
313
+ }
314
+ problems.push(`line ${idx + 1}: "${mapKey}:" takes one level of "<check name>: [paths]" pairs, each list inline — nothing deeper, no block list`);
315
+ return;
316
+ }
298
317
  const pair = line.match(/^(\s+)([A-Za-z0-9_.-]+)\s*:\s*(.*)$/);
299
318
  if (mapKey !== null && pair && !item) {
300
319
  const [, indent, sub, subRaw] = pair;
@@ -1600,6 +1619,18 @@ function auditRepoInner(target, ctx) {
1600
1619
  for (const why of vp.problems) fail(why);
1601
1620
  }
1602
1621
 
1622
+ // ---- release-only-checks (#736) ---------------------------------------------
1623
+ // Checks that matter only to a release, each next to the paths it covers: ship's per-branch
1624
+ // release-only door lets a branch past a trunk red only on them when it touches none of those
1625
+ // paths. An invalid declaration fails: the reader ignores the whole key, so it exempts nothing.
1626
+ {
1627
+ const ro = releaseOnlyLib.parseReleaseOnly(cfg);
1628
+ info.releaseOnlyChecks = ro.declared && ro.valid
1629
+ ? ro.checks.map((c) => ({ check: c.key, workflow: c.workflow, job: c.job, paths: c.paths }))
1630
+ : null;
1631
+ for (const why of ro.problems) fail(why);
1632
+ }
1633
+
1603
1634
  // ---- gate (#410) ----------------------------------------------------------
1604
1635
  // Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
1605
1636
  // parseGate is the one reading. An invalid block fails: the reader falls back to the local full
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.21.0-rc.8"
36
+ "version": "1.21.0-rc.9"
37
37
  }
package/tools/colab CHANGED
@@ -50,6 +50,7 @@ const ciVerdict = require('./lib/ci-verdict');
50
50
  const baseCiVerdict = require('./lib/base-ci-verdict');
51
51
  const treeGreen = require('./lib/tree-green');
52
52
  const verifyRuns = require('./lib/verify-runs');
53
+ const releaseOnly = require('./lib/release-only'); // #736: the release-only red-trunk door
53
54
  const ciWait = require('./lib/ci-wait'); // #495
54
55
  const ciProfile = require('./lib/ci-profile'); // #559
55
56
  const thresholdsLib = require('./lib/thresholds'); // #560
@@ -11242,6 +11243,17 @@ function ciGrantTrailerLine(grantVerdict, branch, trunk) {
11242
11243
  * through the widened door on a branch editing the CI config is a materially different fact from an
11243
11244
  * ordinary one. The commit is the only artifact that still says so after the runs age out.
11244
11245
  */
11246
+ /**
11247
+ * #736: the `CI-Release-Only:` trailer — the audit trail of a merge that landed over a trunk red only on
11248
+ * release-only checks, naming the red it ignored. Deliberately NOT `CI-Grant:` / `CI-Cure:`:
11249
+ * computeAntiStacking greps exactly those two prefixes ("one exemption per red episode"), and a
11250
+ * release-only red is precisely the one many branches must be able to land over, one after another.
11251
+ */
11252
+ function releaseOnlyTrailerLine(v, branch, trunk) {
11253
+ if (!v || !v.ok) return null;
11254
+ return `CI-Release-Only: branch ${branch} over-red ${trunk}@${shortSha(v.redSha)} ignored ${releaseOnly.ignoredList(v.ignored)}`;
11255
+ }
11256
+
11245
11257
  function ciCureTrailerLine(cureVerdict, branch, trunk) {
11246
11258
  if (!cureVerdict || !cureVerdict.ok) return null;
11247
11259
  const via = (cureVerdict.carveOut
@@ -11465,6 +11477,19 @@ Its own honest limit: it proves the red jobs still ran the steps they ran and st
11465
11477
  never what those steps ASSERTED. Known false refusal: a trunk job that failed by TIMEOUT ran longer
11466
11478
  than any healthy run, so (4c) refuses the genuine repair; take the ordinary ci-grant door there.
11467
11479
 
11480
+ THE RELEASE-ONLY DOOR (#736) is tried before both. A repo may declare, in .github/project.yml, the
11481
+ checks that matter only to a release, each next to the paths it covers:
11482
+ release-only-checks:
11483
+ Install smoke: [packaging/, scripts/install.sh] # a whole workflow, by its name:
11484
+ "CI / install (*)": [installer/**] # one job of a workflow, * in the job part
11485
+ When trunk's red comes ONLY from declared checks (every other judged workflow — or job — green, at
11486
+ least one of them), and the branch touches none of the paths of the checks that are red, the row
11487
+ passes; the detail, \`--dry --json\`'s \`releaseOnly\` and a \`CI-Release-Only:\` trailer name the red it
11488
+ ignored. A branch that touches those paths falls through to the cure rule — it must show that check
11489
+ green itself. Read at trunk, never the branch's own descriptor. No anti-stacking: many branches may
11490
+ land over one release-only red. It makes nothing green — \`colab trunk-ci\` still reads RED and
11491
+ \`colab release cut\` still refuses that commit. Declaring nothing (or an invalid key) changes nothing.
11492
+
11468
11493
  The default squash subject is the branch's HIGHEST-WEIGHT commit (breaking > feat > fix > perf >
11469
11494
  refactor > docs > test > chore, ties to the oldest) — NOT its newest commit, which on a well-run
11470
11495
  branch is the docs pass and used to retitle whole features as \`docs:\`, hiding them from the
@@ -12144,11 +12169,41 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch =
12144
12169
  const r = readCiVerdict(repoAbs, gh, target, trunk);
12145
12170
  // #678: on a forge the engine map names, the verdict is final — the #482 no-workflow door counts
12146
12171
  // `.github/workflows` and reads the branch through gh, neither of which describes a forge's CI.
12147
- if (forgeCi(repoAbs)) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
12172
+ if (forgeCi(repoAbs)) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
12148
12173
  const nw = noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch, docsOnlyThunk);
12149
- if (nw) return { name, ...nw, grantVerdict: null, cureVerdict: null };
12150
- if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
12151
- return applyRedTrunkExemptions({ name, ...r.verdict }, target, trunk, r.run.sha, grantThunk, cureThunk);
12174
+ if (nw) return { name, ...nw, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
12175
+ if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
12176
+ // #736: the release-only door is built here, not passed in — it needs only the branch, so every
12177
+ // caller (the table, --dry, B1) gets it without a new parameter, and a call with no branch never does.
12178
+ const releaseOnlyThunk = branch ? (redSha) => shipReleaseOnly(repoAbs, target, trunk, redSha, branch) : null;
12179
+ return applyRedTrunkExemptions({ name, ...r.verdict }, target, trunk, r.run.sha, grantThunk, cureThunk, releaseOnlyThunk);
12180
+ }
12181
+
12182
+ /**
12183
+ * #736: the release-only door's measurement — I/O only; the rule is tools/lib/release-only.js.
12184
+ *
12185
+ * - the declaration is read at TRUNK (`projectDocAt`), never the branch: a branch that adds its own
12186
+ * check to the list does not change what its own ship reads (the same discipline as trust-humans);
12187
+ * - the runs at the red sha through the SAME verifying policy readCiVerdict used, asking for the judged
12188
+ * heads (git.summarizeRunsForCommit `opts.heads`), so "which workflow is red" is the gate's own answer;
12189
+ * - a run's jobs only for a workflow declared at job level (one `gh run view` each, lazily);
12190
+ * - the paths the branch changes: the three-dot diff the squash would land, renames as delete + add so
12191
+ * a file moved OUT of a covered path still counts as touching it.
12192
+ *
12193
+ * Returns release-only.js's verdict plus `redSha`, or null when nothing is declared (or the declaration
12194
+ * is invalid — the audit reports that; the reader takes it as absent), so a repo that declares nothing
12195
+ * pays nothing and reads exactly as before.
12196
+ */
12197
+ function shipReleaseOnly(repoAbs, target, trunk, redSha, branch) {
12198
+ if (target !== trunk || !redSha || !branch) return null;
12199
+ const decl = releaseOnly.parseReleaseOnly(projectDocAt(repoAbs, trunk));
12200
+ if (!decl.valid || !decl.checks.length) return null;
12201
+ const run = git.ghRunForCommit(repoAbs, trunk, redSha, undefined, { verifying: verifyingPolicy(repoAbs), heads: true });
12202
+ const heads = run && Array.isArray(run.heads) ? run.heads : null;
12203
+ const diff = git.git(['diff', '--name-only', '-z', '--no-renames', `${target}...${shipRefFor(repoAbs, branch)}`, '--'], repoAbs);
12204
+ const changed = diff.ok ? diff.stdout.split('\0').map((x) => x.replace(/^\n+/, '')).filter(Boolean) : null;
12205
+ const v = releaseOnly.releaseOnlyVerdict({ heads, jobsOf: (id) => git.ghRunJobs(repoAbs, id), changed, checks: decl.checks });
12206
+ return v.applies ? { ...v, redSha } : null;
12152
12207
  }
12153
12208
 
12154
12209
  /**
@@ -12778,8 +12833,21 @@ function dirtyOwnerDetail(baseDetail, advisory) {
12778
12833
  * on a human, or on the tracker read; a branch that does not falls through to the grant exactly as
12779
12834
  * it always has, unaffected by this rule's existence.
12780
12835
  */
12781
- function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThunk) {
12782
- if (target !== trunk) return { ...raw, grantVerdict: null, cureVerdict: null };
12836
+ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThunk, releaseOnlyThunk = null) {
12837
+ if (target !== trunk) return { ...raw, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
12838
+
12839
+ // #736: the release-only door goes FIRST — no tracker read and no evidence to measure, only which
12840
+ // workflow is red and what the branch touches. It admits a branch over a red the repo declared
12841
+ // release-only; a refusal falls through to the cure rule and the grant exactly as before (a branch
12842
+ // that touches a red check's paths must show that check green itself — which is the cure rule).
12843
+ const releaseOnlyVerdict = releaseOnlyThunk ? releaseOnlyThunk(redSha) : null;
12844
+ if (releaseOnlyVerdict && releaseOnlyVerdict.ok) {
12845
+ return {
12846
+ name: raw.name, ok: true, class: null,
12847
+ detail: `PRECONDITION OVERRIDDEN by the release-only door (#736) — ${trunk}@${shortSha(redSha)} is red only on release-only check(s), IGNORED for this merge: ${releaseOnly.ignoredList(releaseOnlyVerdict.ignored)}; the branch touches none of their paths. The red still blocks a release cut (raw: ${raw.detail})`,
12848
+ grantVerdict: null, cureVerdict: null, releaseOnlyVerdict, redSha,
12849
+ };
12850
+ }
12783
12851
 
12784
12852
  const cureVerdict = cureThunk ? cureThunk(redSha) : null;
12785
12853
  if (cureVerdict && cureVerdict.ok) {
@@ -12793,7 +12861,7 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
12793
12861
  return {
12794
12862
  name: raw.name, ok: true, class: null,
12795
12863
  detail: `PRECONDITION OVERRIDDEN by the cure rule (#281) — branch contains red ${shortSha(redSha)} and is green at its own head${via}${viaDry} (raw: ${raw.detail})`,
12796
- grantVerdict: null, cureVerdict, redSha,
12864
+ grantVerdict: null, cureVerdict, releaseOnlyVerdict, redSha,
12797
12865
  };
12798
12866
  }
12799
12867
 
@@ -12808,21 +12876,22 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
12808
12876
  return {
12809
12877
  name: raw.name, ok: true, class: null,
12810
12878
  detail: `PRECONDITION OVERRIDDEN by ${who} on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
12811
- grantVerdict, cureVerdict, redSha,
12879
+ grantVerdict, cureVerdict, releaseOnlyVerdict, redSha,
12812
12880
  };
12813
12881
  }
12814
12882
  // #534: both doors were consulted and both refused — say WHY on the row itself, so the prose table,
12815
12883
  // `--dry`, and B1's abort line all tell "needs a grant" from "missing evidence" from "stacked". The
12816
12884
  // JSON payload already carried `ciCure.reason`; the prose detail used to end at the raw trunk read.
12817
- return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict)}`, grantVerdict, cureVerdict, redSha };
12885
+ return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict, releaseOnlyVerdict)}`, grantVerdict, cureVerdict, releaseOnlyVerdict, redSha };
12818
12886
  }
12819
12887
 
12820
12888
  /**
12821
- * Which red-trunk door let a trunk-CI row pass — `'cure rule'`, `'ci-grant'`, or null for a row that
12889
+ * Which red-trunk door let a trunk-CI row pass — `'release-only door'` (#736), `'cure rule'`, `'ci-grant'`, or null for a row that
12822
12890
  * passed on its own (green) or did not pass (#538: B1 re-measures only a door the table relied on).
12823
12891
  */
12824
12892
  function doorThatAdmitted(ciResult) {
12825
12893
  if (!ciResult || !ciResult.ok) return null;
12894
+ if (ciResult.releaseOnlyVerdict && ciResult.releaseOnlyVerdict.ok) return 'release-only door';
12826
12895
  if (ciResult.cureVerdict && ciResult.cureVerdict.ok) return 'cure rule';
12827
12896
  if (ciResult.grantVerdict && ciResult.grantVerdict.ok) return 'ci-grant';
12828
12897
  return null;
@@ -12838,8 +12907,9 @@ const B1_REMEASURE_MS = Number.isFinite(Number(process.env.COLAB_B1_REMEASURE_MS
12838
12907
  * cure's `reason`, the grant's per-issue `missing[].reason` — never a re-wording, so the prose and
12839
12908
  * the `--dry --json` fields cannot read differently.
12840
12909
  */
12841
- function doorRefusalNote(cureVerdict, grantVerdict) {
12910
+ function doorRefusalNote(cureVerdict, grantVerdict, releaseOnlyVerdict = null) {
12842
12911
  const parts = [];
12912
+ if (releaseOnlyVerdict && !releaseOnlyVerdict.ok && releaseOnlyVerdict.reason) parts.push(`release-only door (#736): ${releaseOnlyVerdict.reason}`);
12843
12913
  if (cureVerdict && !cureVerdict.ok && cureVerdict.reason) parts.push(`cure rule (#281): ${cureVerdict.reason}`);
12844
12914
  if (grantVerdict && !grantVerdict.ok) {
12845
12915
  const why = (grantVerdict.missing || []).map((m) => (m.issue ? `#${m.issue}: ` : '') + m.reason)
@@ -13139,6 +13209,22 @@ function priorExemptionRedJobs(repoAbs, trunk, stacking) {
13139
13209
  return raw === null ? null : ciCure.redJobSet(raw);
13140
13210
  }
13141
13211
 
13212
+ /**
13213
+ * #736: the trunk-CI-green row's --dry --json additive payload for the release-only door — built from
13214
+ * the SAME verdict shipCiCheck computed. `null` when the door was not consulted or had nothing to say
13215
+ * (nothing declared, a green trunk, a red that is not a finished run), so a repo that declares nothing
13216
+ * sees `releaseOnly: null` and nothing else changes.
13217
+ */
13218
+ function releaseOnlyPayload(ciResult) {
13219
+ const v = ciResult && ciResult.releaseOnlyVerdict;
13220
+ if (!v) return null;
13221
+ return {
13222
+ ok: v.ok, reason: v.reason, redSha: v.redSha || null,
13223
+ ignored: (v.ignored || []).map((x) => ({ ...x })),
13224
+ touched: (v.touched || []).map((x) => ({ check: x.check, paths: x.paths.slice() })),
13225
+ };
13226
+ }
13227
+
13142
13228
  /**
13143
13229
  * The trunk-CI-green row's --dry --json additive payload for the cure rule (#281), parallel to
13144
13230
  * `ciGrantPayload` above and built from the SAME cureVerdict `shipCiCheck` already computed (never
@@ -13382,6 +13468,7 @@ function cmdShipDryJson(opts) {
13382
13468
  // that same check, below. Parallel to ciGrantPayloadVal, never both non-null at once (the cure
13383
13469
  // rule short-circuits before the grant is even consulted once it succeeds).
13384
13470
  let ciCurePayloadVal = null;
13471
+ let releaseOnlyPayloadVal = null; // #736
13385
13472
  // #293: null unless the sha this branch was cut from turned out to be measurably red — see
13386
13473
  // `baseCiAdvisory`'s doc comment. ADVISORY ONLY: never folds into `ok` — the `checks` row it also
13387
13474
  // produces (below) is always `ok: true` for the same reason.
@@ -13406,7 +13493,7 @@ function cmdShipDryJson(opts) {
13406
13493
  const body = {
13407
13494
  ok, dry: true, repo: shortRepo(repoAbs), branch: sess.branch, worktree: sess.name || null,
13408
13495
  target, mode, issues: sess.issues, closeIssues, refsIssues, checklistFindings, refsBrakeFindings, checks,
13409
- migrationGrant: migrationGrantPayload, ciGrant: ciGrantPayloadVal, ciCure: ciCurePayloadVal,
13496
+ migrationGrant: migrationGrantPayload, ciGrant: ciGrantPayloadVal, ciCure: ciCurePayloadVal, releaseOnly: releaseOnlyPayloadVal,
13410
13497
  baseCi: baseCiPayloadVal, dirtyOwners: dirtyOwnersPayloadVal, autonomyGate: autonomyGatePayloadVal,
13411
13498
  coreReview: coreReviewPayloadVal,
13412
13499
  ...machineTrailerPayload(mode === 'squash' || mode === 'pr-pending'),
@@ -13471,6 +13558,7 @@ function cmdShipDryJson(opts) {
13471
13558
  () => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711: the #482 door learns the #606 measurement
13472
13559
  ciGrantPayloadVal = ciGrantPayload(ciResultJson);
13473
13560
  ciCurePayloadVal = ciCurePayload(ciResultJson);
13561
+ releaseOnlyPayloadVal = releaseOnlyPayload(ciResultJson);
13474
13562
  checks.push({ name: ciResultJson.name, ok: ciResultJson.ok, class: ciResultJson.class, detail: ciResultJson.detail });
13475
13563
 
13476
13564
  // #293: advisory only — was the sha this branch was cut from actually green? Always `ok: true`
@@ -15323,6 +15411,7 @@ function cmdShip(argv) {
15323
15411
  // never silently ride the same exemption twice.
15324
15412
  let ciGrantForTrailer = null; // #105: set below when B1 shipped UNDER a grant — read at commit-message time
15325
15413
  let ciCureForTrailer = null; // #281: set below when B1 shipped UNDER the cure rule — read at commit-message time
15414
+ let releaseOnlyForTrailer = null; // #736: set below when B1 shipped over a release-only red — read at commit-message time
15326
15415
  if (gh || forgeCi(repoAbs)) { // #678: a forge's CI is re-read at B1 exactly as GitHub's is
15327
15416
  const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
15328
15417
  (redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
@@ -15350,7 +15439,10 @@ function cmdShip(argv) {
15350
15439
  : `✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
15351
15440
  return 1;
15352
15441
  }
15353
- if (ciResultB1.cureVerdict && ciResultB1.cureVerdict.ok) {
15442
+ if (ciResultB1.releaseOnlyVerdict && ciResultB1.releaseOnlyVerdict.ok) {
15443
+ warn(` ✓ trunk CI green ONLY because the red is on release-only check(s), ignored for this merge: ${releaseOnly.ignoredList(ciResultB1.releaseOnlyVerdict.ignored)} — this merge carries a CI-Release-Only: trailer; the red still blocks a release cut.`);
15444
+ releaseOnlyForTrailer = ciResultB1.releaseOnlyVerdict;
15445
+ } else if (ciResultB1.cureVerdict && ciResultB1.cureVerdict.ok) {
15354
15446
  warn(ciResultB1.cureVerdict.carveOut
15355
15447
  ? ` ✓ trunk CI green ONLY because of the machine-checkable cure rule, through the #321 WORKFLOW CARVE-OUT (this branch edits .github/workflows/**; jobs proven: ${ciResultB1.cureVerdict.carveOut.jobs.map((j) => j.name).join(', ')}) — this merge carries a CI-Cure: trailer.`
15356
15448
  : ` ✓ trunk CI green ONLY because of the machine-checkable cure rule — this merge carries a CI-Cure: trailer.`);
@@ -15464,7 +15556,8 @@ function cmdShip(argv) {
15464
15556
  // rule short-circuits before the grant is even consulted once it succeeds), so at most one of
15465
15557
  // these two calls ever returns non-null.
15466
15558
  const ciTrailer = ciGrantTrailerLine(ciGrantForTrailer, sess.branch, target) ||
15467
- ciCureTrailerLine(ciCureForTrailer, sess.branch, target);
15559
+ ciCureTrailerLine(ciCureForTrailer, sess.branch, target) ||
15560
+ releaseOnlyTrailerLine(releaseOnlyForTrailer, sess.branch, target); // #736 — the three doors are exclusive per B1
15468
15561
  // #324: an adopted remote-only branch records WHOSE work this was — there is no issue to comment
15469
15562
  // on (a zero-claim ship by definition), so the immutable squash is the one place it survives.
15470
15563
  // #367: on a public repo the host tail is dropped — the branch and sha stay, they are the audit trail.
@@ -15490,7 +15583,7 @@ function cmdShip(argv) {
15490
15583
  for (const tl of ciTrailerLines) {
15491
15584
  if (commitMsg.toLowerCase().includes(tl.toLowerCase())) continue;
15492
15585
  const lastLine = commitMsg.split('\n').pop().trim();
15493
- commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
15586
+ commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|CI-Release-Only|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
15494
15587
  }
15495
15588
  } else {
15496
15589
  // Preserve the branch's crafted commit (subject + footers); insert Closes/Refs above the footers.
@@ -16810,6 +16903,8 @@ scheduled finalize, a dispatch, a deploy — comes after the verdict and is set
16810
16903
  the detail (--json: setAside). Override in .github/project.yml, by workflow name:
16811
16904
  ship-gate-workflows: [CI] exactly these workflows count, whatever their trigger
16812
16905
  ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered
16906
+ release-only-checks (#736) never changes this verdict: a red on a release-only check is RED here;
16907
+ only ship's per-branch release-only door reads that key.
16813
16908
 
16814
16909
  The first output word is one verdict:
16815
16910
  GREEN every judged workflow's newest run at the sha succeeded — ship's row would pass
@@ -46,7 +46,7 @@ const TUNING_KEYS = Object.freeze(Object.keys(TUNING));
46
46
  * can say WHY it refuses them; any key outside TUNING is refused all the same.
47
47
  */
48
48
  const AUTHORITY_KEYS = Object.freeze([
49
- 'autonomy', 'promotion', 'migration-grant', 'ci-grant', 'trust-humans',
49
+ 'autonomy', 'promotion', 'migration-grant', 'ci-grant', 'release-only-checks', 'trust-humans',
50
50
  'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
51
51
  ]);
52
52
 
package/tools/lib/git.js CHANGED
@@ -1348,6 +1348,10 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1348
1348
  // row it meets, which can be a `skipped` one beside a real failure; a caller asking "did any run
1349
1349
  // finish red here" reads this list instead. Absent when none did.
1350
1350
  ...(opts && opts.finishedRed && judged.some(isFinishedRed) ? { finishedRed: excludedRunSummary(judged.filter(isFinishedRed)) } : {}),
1351
+ // #736: opt-in (`opts.heads`) — the JUDGED heads themselves (newest run per counted workflow, the
1352
+ // wholly skipped set aside), so the release-only door can tell which workflow made the sha red.
1353
+ // Absent unless asked, exactly like `finishedRed`.
1354
+ ...(opts && opts.heads ? { heads: excludedRunSummary(judged) } : {}),
1351
1355
  // #651: the rows came from the unfiltered listing because the forge's filter index was empty.
1352
1356
  ...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
1353
1357
  };
@@ -0,0 +1,182 @@
1
+ 'use strict';
2
+ /**
3
+ * #736: checks that matter only to a RELEASE — building and installing the shipped artifact on a
4
+ * clean machine, signing, publishing. When one of them is red on trunk, every branch used to wait
5
+ * for a ci-grant or a cure, including branches that cannot affect that check at all. Measured: one
6
+ * release-only install lane went red from an untested change, and about six hours of finished work
7
+ * waited behind it, every branch green on every check it could reach.
8
+ *
9
+ * A repo declares those checks in project.yml, each next to the paths it covers:
10
+ *
11
+ * release-only-checks:
12
+ * Install smoke: [packaging/, scripts/install.sh] # a whole workflow (its `name:`)
13
+ * "CI / install (*)": [packaging/**] # one job of a workflow; `*` in the job part
14
+ *
15
+ * `colab ship`'s trunk-CI row then lets ONE branch past a trunk that is red ONLY on declared checks,
16
+ * provided the branch touches none of the paths those red checks cover — a third red-trunk door
17
+ * beside the cure rule (#281) and the ci-grant (#105). Like them it makes nothing green: `colab
18
+ * trunk-ci` still reads the red, and `colab release cut` still refuses at that commit, because
19
+ * neither reads this key. The verifying-runs policy (verify-runs.js) is deliberately untouched, so
20
+ * `ship-ignore-workflows` keeps its one shared meaning for ship and the cut.
21
+ *
22
+ * PURE: a parsed descriptor and run/job/diff facts in, verdicts out. The I/O is tools/colab's
23
+ * shipReleaseOnly. Every doubt refuses: the door is an exemption, and a false refusal costs exactly
24
+ * today's behaviour (the cure rule and the ci-grant are still consulted), while a false admission
25
+ * lands a branch over a red nobody looked at.
26
+ */
27
+
28
+ const codeowners = require('./codeowners');
29
+
30
+ const KEY = 'release-only-checks';
31
+ const JOB_SEP = ' / ';
32
+
33
+ /** Conclusions of a run or job that executed nothing — never a red, never a verification. */
34
+ const NEUTRAL = new Set(['skipped', 'neutral']);
35
+
36
+ function unquote(s) {
37
+ const t = String(s).trim();
38
+ if (t.length > 1 && ((t[0] === '"' && t.endsWith('"')) || (t[0] === "'" && t.endsWith("'")))) return t.slice(1, -1).trim();
39
+ return t;
40
+ }
41
+
42
+ /** `*` in a job name matches any run of characters (matrix legs: `install (*)`); the rest is literal. */
43
+ function jobPattern(job) {
44
+ return new RegExp(`^${job.split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
45
+ }
46
+
47
+ /**
48
+ * The declaration from a parsed project.yml doc:
49
+ * `{ declared, valid, checks: [{key, workflow, job, paths, res, jobRe}], problems: string[] }`.
50
+ * Any problem makes the whole key invalid and the reader IGNORES it (no exemption at all) — a
51
+ * half-read declaration must never exempt a check its owner did not name. The audit fails it.
52
+ */
53
+ function parseReleaseOnly(doc) {
54
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, KEY);
55
+ const none = { declared: false, valid: true, checks: [], problems: [] };
56
+ if (!has || doc[KEY] === null || doc[KEY] === undefined) return none;
57
+ const v = doc[KEY];
58
+ const bad = (why) => ({ declared: true, valid: false, checks: [], problems: [why] });
59
+ if (typeof v !== 'object' || Array.isArray(v)) {
60
+ return bad(`${KEY} must be a map of "<workflow>" or "<workflow> / <job>" to an inline list of the paths that check covers, got ${JSON.stringify(v)}`);
61
+ }
62
+ const entries = Object.entries(v);
63
+ if (!entries.length) return bad(`${KEY} declares no check — remove the key, or name at least one`);
64
+ const problems = [];
65
+ const checks = [];
66
+ for (const [rawKey, rawPaths] of entries) {
67
+ const key = unquote(rawKey);
68
+ // Split at the FIRST ` / ` — the way the forge displays a check ("CI / install (macos)"). A trailing
69
+ // ` /` with nothing after it is a job key with no job, never a workflow named "CI /".
70
+ const m = /^(.*?)\s+\/(?:\s+(.*))?$/.exec(key);
71
+ const workflow = (m ? m[1] : key).trim();
72
+ const job = m ? String(m[2] || '').trim() : null;
73
+ if (!workflow || (m && !job)) { problems.push(`${KEY}: "${key}" names no ${!workflow ? 'workflow' : 'job'}`); continue; }
74
+ const list = typeof rawPaths === 'string' ? [rawPaths] : rawPaths;
75
+ if (!Array.isArray(list) || !list.length) {
76
+ problems.push(`${KEY}: "${key}" must list the paths it covers (a check with no paths would exempt every branch), got ${JSON.stringify(rawPaths)}`);
77
+ continue;
78
+ }
79
+ const paths = [];
80
+ const res = [];
81
+ for (const p of list) {
82
+ const s = typeof p === 'string' ? unquote(p) : '';
83
+ const re = s ? codeowners.compile(s) : null;
84
+ if (!re) { problems.push(`${KEY}: "${key}" path ${JSON.stringify(p)} is not a CODEOWNERS-style pattern (no negation, no [ ] ranges)`); continue; }
85
+ paths.push(s);
86
+ res.push(re);
87
+ }
88
+ if (paths.length !== list.length) continue;
89
+ checks.push({ key, workflow, job, paths, res, jobRe: job ? jobPattern(job) : null });
90
+ }
91
+ if (problems.length) return { declared: true, valid: false, checks: [], problems };
92
+ return { declared: true, valid: true, checks, problems: [] };
93
+ }
94
+
95
+ /** The checks that name `workflow`, split into whole-workflow and per-job ones. */
96
+ function checksFor(checks, workflow) {
97
+ const mine = checks.filter((c) => c.workflow === workflow);
98
+ return { whole: mine.find((c) => !c.job) || null, jobs: mine.filter((c) => c.job) };
99
+ }
100
+
101
+ function isGreen(c) { return c === 'success'; }
102
+ function isNeutral(c) { return NEUTRAL.has(c); }
103
+
104
+ /**
105
+ * Does the release-only door admit this branch over a red trunk?
106
+ *
107
+ * @param {object} a
108
+ * @param {Array<{workflowName, status, conclusion, databaseId}>|null} a.heads - the JUDGED heads at the
109
+ * red sha (newest run per counted workflow, git.summarizeRunsForCommit `opts.heads`); null = unread
110
+ * @param {(runId:number) => Array<{name, status, conclusion}>|null} [a.jobsOf] - a run's jobs; null = unread
111
+ * @param {string[]|null} a.changed - the paths the branch changes (three-dot diff); null = unread
112
+ * @param {Array} a.checks - parseReleaseOnly's `checks`
113
+ * @returns {{applies:boolean, ok:boolean, reason:string, ignored:Array, touched:Array}}
114
+ * `applies: false` — nothing declared, or the red is not a finished run (none, wedged, in flight):
115
+ * the door has nothing to say and the raw verdict stands with no note.
116
+ */
117
+ function releaseOnlyVerdict({ heads, jobsOf = null, changed, checks }) {
118
+ const out = (applies, ok, reason, ignored = [], touched = []) => ({ applies, ok, reason, ignored, touched });
119
+ if (!Array.isArray(checks) || !checks.length) return out(false, false, 'no release-only check declared');
120
+ if (!Array.isArray(heads)) return out(true, false, 'could not read the runs at the red sha');
121
+ const unfinished = heads.filter((h) => h.status !== 'completed');
122
+ const red = heads.filter((h) => h.status === 'completed' && !isGreen(h.conclusion) && !isNeutral(h.conclusion));
123
+ if (!red.length) return out(false, false, 'no finished red run at the red sha');
124
+ if (unfinished.length) {
125
+ return out(true, false, `a run is still in flight at the red sha (${unfinished.map((h) => h.workflowName || 'unnamed').join(', ')})`);
126
+ }
127
+
128
+ let verifiedElsewhere = heads.some((h) => h.status === 'completed' && isGreen(h.conclusion) && !checksFor(checks, h.workflowName).whole);
129
+ const ignored = [];
130
+ const redChecks = [];
131
+ for (const h of red) {
132
+ const name = h.workflowName || null;
133
+ const runRef = `${name || 'unnamed'}${h.databaseId ? ` (run ${h.databaseId})` : ''}`;
134
+ const { whole, jobs } = name ? checksFor(checks, name) : { whole: null, jobs: [] };
135
+ if (whole) {
136
+ ignored.push({ check: whole.key, workflow: name, job: null, runId: h.databaseId || null, conclusion: h.conclusion });
137
+ redChecks.push(whole);
138
+ continue;
139
+ }
140
+ if (!jobs.length) return out(true, false, `trunk is also red on ${runRef}, which is not a release-only check`);
141
+ const list = jobsOf && h.databaseId ? jobsOf(h.databaseId) : null;
142
+ if (!Array.isArray(list) || !list.length) return out(true, false, `could not read the jobs of ${runRef} to tell a release-only job from the rest`);
143
+ const redJobs = list.filter((j) => j.status === 'completed' && !isGreen(j.conclusion) && !isNeutral(j.conclusion));
144
+ const stillRunning = list.filter((j) => j.status !== 'completed');
145
+ if (stillRunning.length) return out(true, false, `${runRef} still has a job in flight (${stillRunning.map((j) => j.name).join(', ')})`);
146
+ if (!redJobs.length) return out(true, false, `${runRef} is red but no job of it finished red — nothing to attribute the red to`);
147
+ for (const j of redJobs) {
148
+ const c = jobs.find((x) => x.jobRe.test(String(j.name || '')));
149
+ if (!c) return out(true, false, `trunk is also red on ${name} / ${j.name || 'unnamed'} (run ${h.databaseId}), which is not a release-only check`);
150
+ ignored.push({ check: c.key, workflow: name, job: j.name, runId: h.databaseId || null, conclusion: j.conclusion });
151
+ if (!redChecks.includes(c)) redChecks.push(c);
152
+ }
153
+ if (list.some((j) => j.status === 'completed' && isGreen(j.conclusion) && !jobs.some((x) => x.jobRe.test(String(j.name || ''))))) verifiedElsewhere = true;
154
+ }
155
+ if (!verifiedElsewhere) {
156
+ return out(true, false, 'nothing but release-only checks verified the red sha — no other check ran green there', ignored);
157
+ }
158
+ if (!Array.isArray(changed)) return out(true, false, 'could not read the branch diff to check it against the release-only paths', ignored);
159
+ const touched = [];
160
+ for (const c of redChecks) {
161
+ const hits = changed.filter((p) => c.res.some((re) => re.test(p)));
162
+ if (hits.length) touched.push({ check: c.key, paths: hits });
163
+ }
164
+ if (touched.length) {
165
+ const t = touched.map((x) => `${x.paths.slice(0, 3).join(', ')}${x.paths.length > 3 ? ` (+${x.paths.length - 3})` : ''} — covered by "${x.check}"`).join('; ');
166
+ return out(true, false, `the branch touches what a red release-only check covers (${t}), so it must show that check green on itself — the cure rule or a ci-grant`, ignored, touched);
167
+ }
168
+ return out(true, true, `trunk is red only on release-only check(s), and the branch touches none of their paths`, ignored);
169
+ }
170
+
171
+ /** The compact list a detail or trailer names the ignored red by: `Install smoke (run 7), CI / install (macos) (run 9)`. */
172
+ function ignoredList(ignored) {
173
+ const seen = new Set();
174
+ const parts = [];
175
+ for (const x of ignored || []) {
176
+ const s = `${x.workflow}${x.job ? `${JOB_SEP}${x.job}` : ''}${x.runId ? ` (run ${x.runId})` : ''}`;
177
+ if (!seen.has(s)) { seen.add(s); parts.push(s); }
178
+ }
179
+ return parts.join(', ');
180
+ }
181
+
182
+ module.exports = { KEY, JOB_SEP, parseReleaseOnly, releaseOnlyVerdict, ignoredList };