@futurelastic/colab-handbook 1.21.0-rc.8 → 1.22.0-rc.1

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
@@ -141,6 +141,8 @@ const migrationGrant = require("../tools/lib/migration-grant.js");
141
141
  const ciGrantLib = require("../tools/lib/ci-grant.js");
142
142
  // #407: the optional `trust-humans` list — read through the same module every grant reader uses.
143
143
  const trustHumansLib = require("../tools/lib/trust-humans.js");
144
+ // #739: `.github/factories.yml` — the trust file for several teams on one repository.
145
+ const factoriesLib = require("../tools/lib/factories.js");
144
146
  // #403: the `live-env:` key — read through the same module `colab gate-hermetic` uses.
145
147
  const hermeticLib = require("../tools/lib/hermetic.js");
146
148
  // #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
@@ -149,6 +151,8 @@ const treeGreenLib = require("../tools/lib/tree-green.js");
149
151
  const docsOnlyLib = require("../tools/lib/docs-only.js");
150
152
  // #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
151
153
  const verifyRunsLib = require("../tools/lib/verify-runs.js");
154
+ // #736: `release-only-checks:` — read through the same module ship's release-only door uses.
155
+ const releaseOnlyLib = require("../tools/lib/release-only.js");
152
156
  // #410: the optional `gate:` block — read through the same module the skills name.
153
157
  const gateLib = require("../tools/lib/gate.js");
154
158
  // #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
@@ -268,7 +272,11 @@ function parseScalarValue(raw) {
268
272
  return val;
269
273
  }
270
274
 
271
- const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630
275
+ 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
276
+ // #736: the one map whose KEYS are free text — a check's display name ("Install smoke", "CI / install (*)"),
277
+ // optionally quoted, never containing ":" — and whose every value is an INLINE list of paths. Still one
278
+ // level, still no block list: any other line under it is a finding.
279
+ const FREE_KEY_MAP_KEYS = new Set(["release-only-checks"]);
272
280
  // The one map whose pairs may hold an INLINE list (`coupled: [a, b]`) — still one level, still no block list (#630).
273
281
  const LIST_IN_MAP_KEYS = new Set(["contention"]);
274
282
  // A key whose empty value may open EITHER a block list or a one-level map: `migrations:` is a list of
@@ -295,6 +303,19 @@ function parseFlatYaml(text) {
295
303
  out[listKey].push(parseScalarValue(item[1]));
296
304
  return;
297
305
  }
306
+ if (mapKey !== null && FREE_KEY_MAP_KEYS.has(mapKey) && !item) {
307
+ const fp = line.match(/^(\s+)("[^"]+"|'[^']+'|[^\s#"'][^:#]*?)\s*:\s*(.*)$/);
308
+ const fpVal = fp ? fp[3].replace(/\s+#.*$/, "").trim() : "";
309
+ if (fp && (mapIndent === null || fp[1].length === mapIndent) && /^\[.*\]$/.test(fpVal)) {
310
+ if (mapIndent === null) mapIndent = fp[1].length;
311
+ if (out[mapKey] === null || typeof out[mapKey] !== "object") out[mapKey] = {};
312
+ const inner = fpVal.slice(1, -1).trim();
313
+ out[mapKey][fp[2]] = inner === "" ? [] : inner.split(",").map((x) => parseScalarValue(x));
314
+ return;
315
+ }
316
+ problems.push(`line ${idx + 1}: "${mapKey}:" takes one level of "<check name>: [paths]" pairs, each list inline — nothing deeper, no block list`);
317
+ return;
318
+ }
298
319
  const pair = line.match(/^(\s+)([A-Za-z0-9_.-]+)\s*:\s*(.*)$/);
299
320
  if (mapKey !== null && pair && !item) {
300
321
  const [, indent, sub, subRaw] = pair;
@@ -1532,6 +1553,21 @@ function auditRepoInner(target, ctx) {
1532
1553
  if (!tr.valid) fail(tr.reason);
1533
1554
  }
1534
1555
 
1556
+ // ---- .github/factories.yml (#739) -----------------------------------------
1557
+ // The trust file several teams ("factories") share one repository through. Absent = nothing
1558
+ // (one team, no cross-factory rule). tools/lib/factories.js parseFactories is the one reading.
1559
+ // An invalid file fails: every reader then answers "nobody" (fail closed), so each cross-factory
1560
+ // rule the file was meant to turn on stops matching anyone — loud here, not at the next claim.
1561
+ {
1562
+ const text = src.readFile(factoriesLib.PATH);
1563
+ if (text === null || text === undefined) info.factories = null;
1564
+ else {
1565
+ const fr = factoriesLib.parseFactories(text);
1566
+ info.factories = fr.valid ? Object.keys(fr.doc.factories) : null;
1567
+ for (const why of fr.findings) fail(`${factoriesLib.PATH}: ${why}`);
1568
+ }
1569
+ }
1570
+
1535
1571
  // ---- live-env (#403) ------------------------------------------------------
1536
1572
  // `live-env: none` is the one declaration that skips code-wrap A3's hermetic second test run
1537
1573
  // (`colab gate-hermetic`). tools/lib/hermetic.js parseLiveEnv is the one reading. An invalid
@@ -1600,6 +1636,18 @@ function auditRepoInner(target, ctx) {
1600
1636
  for (const why of vp.problems) fail(why);
1601
1637
  }
1602
1638
 
1639
+ // ---- release-only-checks (#736) ---------------------------------------------
1640
+ // Checks that matter only to a release, each next to the paths it covers: ship's per-branch
1641
+ // release-only door lets a branch past a trunk red only on them when it touches none of those
1642
+ // paths. An invalid declaration fails: the reader ignores the whole key, so it exempts nothing.
1643
+ {
1644
+ const ro = releaseOnlyLib.parseReleaseOnly(cfg);
1645
+ info.releaseOnlyChecks = ro.declared && ro.valid
1646
+ ? ro.checks.map((c) => ({ check: c.key, workflow: c.workflow, job: c.job, paths: c.paths }))
1647
+ : null;
1648
+ for (const why of ro.problems) fail(why);
1649
+ }
1650
+
1603
1651
  // ---- gate (#410) ----------------------------------------------------------
1604
1652
  // Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
1605
1653
  // 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.22.0-rc.1"
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
@@ -31,9 +31,18 @@ const ANY_HEADING_RE = /^#{1,6}\s+\S/;
31
31
  /** A GitHub checklist line: `- [ ] …` or `- [x] …` (case-insensitive on the mark). */
32
32
  const ITEM_RE = /^-\s*\[([ xX])\]\s*(.+)$/;
33
33
 
34
- /** `Remainder: #M` — the trailer that hands unticked boxes to a follow-up issue, same shape as
35
- * the `Filed-by:` / `Group:` / `Because:` trailers this repo already writes onto issues. */
36
- const REMAINDER_RE = /^Remainder:\s*#(\d+)\b/im;
34
+ /** `Remainder: #M` — the declaration that hands unticked boxes to a follow-up issue, same shape as
35
+ * the `Filed-by:` / `Group:` / `Because:` trailers this repo already writes onto issues.
36
+ *
37
+ * Read ANYWHERE in a text, not only at the start of a line (#737): no rule says the declaration
38
+ * must start a line, and the two common forms people actually write were both missed — at the end
39
+ * of the unticked item it hands off (`- [ ] measure X … — Remainder: #M`) and inside a sentence or
40
+ * in bold (`item 4 moved to **Remainder: #M**`, `**Remainder:** #M`). Measured: a graded,
41
+ * CI-green branch sat refused for ~16 h until the same trailer was restated on its own line.
42
+ * The left edge still has to be a word boundary (`xRemainder:` does not count), and `#M` must be
43
+ * digits, so the `Remainder: #M` placeholder in prose and refusal messages never matches.
44
+ * Emphasis markers (`*`, `_`) are allowed on either side of the colon. */
45
+ const REMAINDER_RE = /(?<![A-Za-z0-9])Remainder[*_]*:[*_]*\s*#(\d+)\b/i;
37
46
 
38
47
  /**
39
48
  * The raw text of the `## Plan` section (between its heading and the next heading, or the end of
@@ -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
 
@@ -0,0 +1,329 @@
1
+ 'use strict';
2
+ /**
3
+ * `.github/factories.yml` (#739, epic #738): the trust file that lets several independent teams
4
+ * ("factories") work on one repository with nothing shared but its forge.
5
+ *
6
+ * WHAT IT HOLDS. Who the teams are and what each may prove:
7
+ *
8
+ * version: 1
9
+ * steward: core # the factory that owns intake, trunk health and release
10
+ * forge: github.com # the repository's one home forge (a host name)
11
+ * factories:
12
+ * core: # a MAP keyed by factory id — never a list of factory objects
13
+ * tier: steward # steward · partner · outside
14
+ * machines: [box-a, box-b] # machine ids, unique across the whole file
15
+ * key: ssh-ed25519 AAAA… # ONE SSH public key: signs claim commits and verdict markers
16
+ * humans: [operator-a] # logins that count as a human for grants
17
+ * slices: [slice:core] # labels; each owned by exactly one factory
18
+ * steward-areas: [CONVENTIONS.md, .github/**] # paths whose change needs one steward verdict
19
+ *
20
+ * WHERE IT IS READ FROM is the caller's job, and the rule is the one `trust-humans:` follows: the
21
+ * TRUNK's committed copy, never the branch being judged — a branch that could edit this file could
22
+ * grant itself a factory, a machine or a key. Nothing here reads git.
23
+ *
24
+ * FAIL CLOSED. A malformed file is `valid: false` and every lookup answers "nobody": a reader that
25
+ * fell back to "no factories file" would silently drop every cross-factory rule the adopter
26
+ * declared the file to turn on.
27
+ *
28
+ * THE SIGNATURE FORMATS (mechanics: tools/docs/factories.md; why: docs/adr/739-*.md).
29
+ * claim commit an SSH-signed git commit, checked with `git verify-commit` against
30
+ * allowedSigners(doc, 'git') — the principal is the factory id.
31
+ * verdict marker `<!-- colab:verdict phase=<p> v=<v> head=<sha40> factory=<id> sig=<b64> -->`;
32
+ * `sig` is an SSH signature (namespace `colab-verdict`) over verdictPayload(),
33
+ * never over the comment body. `forge`, `repo` and `issue` in the payload come
34
+ * from the VERIFIER's own context, so a marker copied elsewhere fails.
35
+ *
36
+ * PURE: text or a parsed doc in, a verdict out. No git, no network, no ssh-keygen.
37
+ */
38
+
39
+ const yaml = require('./yaml.js');
40
+ const { LOGIN_RE } = require('./trust-humans.js');
41
+
42
+ /** Where the file lives, relative to the repository root. */
43
+ const PATH = '.github/factories.yml';
44
+ const VERSION = 1;
45
+ const TIERS = ['steward', 'partner', 'outside'];
46
+ const TOP_KEYS = ['version', 'steward', 'forge', 'factories', 'steward-areas'];
47
+ const FACTORY_KEYS = ['tier', 'machines', 'key', 'humans', 'slices'];
48
+
49
+ const FACTORY_ID_RE = /^[a-z0-9][a-z0-9-]{0,38}$/;
50
+ const MACHINE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
51
+ const FORGE_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?$/;
52
+ const SLICE_RE = /^slice:[a-z0-9][a-z0-9._-]*$/;
53
+ /** One OpenSSH public key line: type, base64 blob, optional comment. */
54
+ const SSH_KEY_RE = /^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]+={0,2}( [^\s]+)?$/;
55
+
56
+ // ── the shared vocabulary (CONVENTIONS.md §5, *Factories*) ──────────────────────────────────
57
+ // Prose is the source; these are the machine copy. Not in tools/lib/codec yet — that is a closed
58
+ // public surface, and nothing writes these strings yet; the first writer (#743) moves what it writes.
59
+ const FACTORY_LABEL_PREFIX = 'factory:';
60
+ const SLICE_LABEL_PREFIX = 'slice:';
61
+ const QUEUE_READY_LABEL = 'queue:ready';
62
+ const REVIEW_LABEL_PREFIX = 'review:';
63
+ const AUDIT_STATUS_CONTEXT = 'audit';
64
+ /** `review/<check>@<factory>` — the commit-status context one factory's reviewer posts. */
65
+ function reviewStatusContext(check, factory) { return `review/${check}@${factory}`; }
66
+
67
+ // ── signatures ──────────────────────────────────────────────────────────────────────────────
68
+ const VERDICT_NAMESPACE = 'colab-verdict';
69
+ const CLAIM_NAMESPACE = 'git';
70
+ const PAYLOAD_HEADER = 'colab-verdict/1';
71
+ /** The signed fields, in signing order. `forge`/`repo` come from the verifier, the rest from the marker. */
72
+ const PAYLOAD_FIELDS = ['forge', 'repo', 'issue', 'phase', 'verdict', 'head', 'factory'];
73
+ const VERDICTS = ['pass', 'rework', 'blocked', 'escalate'];
74
+
75
+ function isList(v) { return Array.isArray(v); }
76
+ function str(v) { return typeof v === 'string' ? v.trim() : v; }
77
+
78
+ /**
79
+ * Two factories under one id are merged silently by the YAML subset parser (last one wins), which
80
+ * would hide exactly the clash the validator exists to report. So the raw text is read once more:
81
+ * the direct children of `factories:` and the top-level keys, each seen at most once.
82
+ */
83
+ function duplicateKeys(text) {
84
+ const out = [];
85
+ const lines = String(text).split(/\r?\n/).map((l) => l.replace(/(^|\s)#.*$/, '').replace(/\s+$/, ''))
86
+ .filter((l) => l.trim() !== '');
87
+ const top = new Map();
88
+ let inFactories = false;
89
+ let childIndent = null;
90
+ const children = new Map();
91
+ for (const l of lines) {
92
+ const indent = l.match(/^ */)[0].length;
93
+ const m = l.trim().match(/^([^:\s][^:]*):/);
94
+ if (indent === 0) {
95
+ inFactories = false;
96
+ if (m) {
97
+ top.set(m[1], (top.get(m[1]) || 0) + 1);
98
+ if (m[1] === 'factories') { inFactories = true; childIndent = null; }
99
+ }
100
+ continue;
101
+ }
102
+ if (!inFactories || !m) continue;
103
+ if (childIndent === null) childIndent = indent;
104
+ if (indent === childIndent) children.set(m[1], (children.get(m[1]) || 0) + 1);
105
+ }
106
+ for (const [k, n] of top) if (n > 1) out.push(`top-level key \`${k}\` appears ${n} times`);
107
+ for (const [k, n] of children) if (n > 1) out.push(`factory \`${k}\` is declared ${n} times — one id, one factory`);
108
+ return out;
109
+ }
110
+
111
+ /** A list field → its trimmed strings, or a finding. `allowEmpty` for `humans`. */
112
+ function listOf(v, what, re, allowEmpty, findings) {
113
+ if (v === null || v === undefined) {
114
+ if (allowEmpty) return [];
115
+ findings.push(`${what} is missing`);
116
+ return [];
117
+ }
118
+ if (!isList(v)) { findings.push(`${what} must be a list, got ${JSON.stringify(v)}`); return []; }
119
+ if (!allowEmpty && v.length === 0) { findings.push(`${what} is an empty list`); return []; }
120
+ const out = [];
121
+ for (const raw of v) {
122
+ const s = str(raw);
123
+ if (typeof s !== 'string' || !re.test(s)) findings.push(`${what} has an invalid entry ${JSON.stringify(raw)}`);
124
+ else out.push(s);
125
+ }
126
+ return out;
127
+ }
128
+
129
+ /**
130
+ * The file's text → `{ valid, findings, doc }`.
131
+ * doc — `{ version, steward, forge, factories: { <id>: { tier, machines, key, humans, slices } },
132
+ * stewardAreas }`, normalised; present even when invalid, for a reader that wants to
133
+ * print what it saw. Never act on it when `valid` is false.
134
+ * Every finding names the field and, for a clash, both factories.
135
+ */
136
+ function parseFactories(text) {
137
+ const findings = [];
138
+ let raw;
139
+ try { raw = yaml.parse(String(text == null ? '' : text)); } catch (e) {
140
+ return { valid: false, findings: [`${PATH} could not be parsed: ${e.message}`], doc: null };
141
+ }
142
+ findings.push(...duplicateKeys(text));
143
+ if (!raw || typeof raw !== 'object' || isList(raw)) {
144
+ return { valid: false, findings: [`${PATH} must be a map of keys`], doc: null };
145
+ }
146
+ for (const k of Object.keys(raw)) if (!TOP_KEYS.includes(k)) findings.push(`unknown key \`${k}\``);
147
+
148
+ if (raw.version !== VERSION) findings.push(`version must be ${VERSION}, got ${JSON.stringify(raw.version ?? null)}`);
149
+ const forge = str(raw.forge);
150
+ if (typeof forge !== 'string' || !FORGE_RE.test(forge)) findings.push(`forge must be a host name (e.g. github.com), got ${JSON.stringify(raw.forge ?? null)}`);
151
+
152
+ const factories = {};
153
+ const fs = raw.factories;
154
+ if (!fs || typeof fs !== 'object' || isList(fs)) {
155
+ findings.push('factories must be a map keyed by factory id (not a list of factory objects)');
156
+ } else {
157
+ for (const [id, f] of Object.entries(fs)) {
158
+ const where = `factories.${id}`;
159
+ if (!FACTORY_ID_RE.test(id)) findings.push(`${where}: a factory id is lowercase letters, digits and hyphens`);
160
+ if (!f || typeof f !== 'object' || isList(f)) { findings.push(`${where} must be a map`); continue; }
161
+ for (const k of Object.keys(f)) if (!FACTORY_KEYS.includes(k)) findings.push(`${where}: unknown key \`${k}\``);
162
+ const tier = str(f.tier);
163
+ if (!TIERS.includes(tier)) findings.push(`${where}.tier must be one of ${TIERS.join(' · ')}, got ${JSON.stringify(f.tier ?? null)}`);
164
+ const key = str(f.key);
165
+ if (typeof key !== 'string' || !SSH_KEY_RE.test(key)) findings.push(`${where}.key must be one SSH public key line (type, base64, optional comment)`);
166
+ factories[id] = {
167
+ tier: TIERS.includes(tier) ? tier : null,
168
+ machines: listOf(f.machines, `${where}.machines`, MACHINE_ID_RE, false, findings),
169
+ key: typeof key === 'string' && SSH_KEY_RE.test(key) ? key : null,
170
+ humans: listOf(f.humans, `${where}.humans`, LOGIN_RE, true, findings).map((h) => h.toLowerCase()),
171
+ slices: listOf(f.slices, `${where}.slices`, SLICE_RE, true, findings),
172
+ };
173
+ }
174
+ if (Object.keys(factories).length === 0) findings.push('factories declares no factory');
175
+ }
176
+
177
+ // Across the file: a machine and a slice each belong to exactly one factory.
178
+ for (const [field, noun] of [['machines', 'machine'], ['slices', 'slice']]) {
179
+ const owner = new Map();
180
+ for (const [id, f] of Object.entries(factories)) {
181
+ for (const v of f[field]) {
182
+ const prev = owner.get(v);
183
+ if (prev && prev !== id) findings.push(`${noun} \`${v}\` is claimed by both \`${prev}\` and \`${id}\` — each ${noun} belongs to one factory`);
184
+ else if (prev === id) findings.push(`${noun} \`${v}\` is listed twice in \`${id}\``);
185
+ else owner.set(v, id);
186
+ }
187
+ }
188
+ }
189
+ const keyOwner = new Map();
190
+ for (const [id, f] of Object.entries(factories)) {
191
+ if (!f.key) continue;
192
+ const blob = f.key.split(' ')[1];
193
+ if (keyOwner.has(blob)) findings.push(`factories \`${keyOwner.get(blob)}\` and \`${id}\` share one key — a key identifies one factory`);
194
+ else keyOwner.set(blob, id);
195
+ }
196
+
197
+ const steward = str(raw.steward);
198
+ const stewards = Object.entries(factories).filter(([, f]) => f.tier === 'steward').map(([id]) => id);
199
+ if (typeof steward !== 'string' || !factories[steward]) findings.push(`steward must name a declared factory, got ${JSON.stringify(raw.steward ?? null)}`);
200
+ else if (factories[steward].tier !== 'steward') findings.push(`steward \`${steward}\` must have tier steward`);
201
+ if (stewards.length > 1) findings.push(`exactly one factory has tier steward, found ${stewards.map((s) => `\`${s}\``).join(', ')}`);
202
+
203
+ const stewardAreas = listOf(raw['steward-areas'], 'steward-areas', /^\S+$/, true, findings);
204
+
205
+ const doc = { version: raw.version, steward: steward || null, forge: forge || null, factories, stewardAreas };
206
+ return { valid: findings.length === 0, findings, doc };
207
+ }
208
+
209
+ /** A parsed result, or null — the guard every lookup shares: invalid answers nobody. */
210
+ function usable(parsed) { return parsed && parsed.valid && parsed.doc ? parsed.doc : null; }
211
+
212
+ /** The factory a machine id belongs to, or null (unknown machine, or an invalid file). */
213
+ function factoryOfMachine(parsed, machine) {
214
+ const doc = usable(parsed);
215
+ if (!doc) return null;
216
+ for (const [id, f] of Object.entries(doc.factories)) if (f.machines.includes(machine)) return id;
217
+ return null;
218
+ }
219
+
220
+ /** The factory owning a slice label (`slice:<name>`), or null. */
221
+ function factoryOfSlice(parsed, label) {
222
+ const doc = usable(parsed);
223
+ if (!doc) return null;
224
+ for (const [id, f] of Object.entries(doc.factories)) if (f.slices.includes(label)) return id;
225
+ return null;
226
+ }
227
+
228
+ /** Whether `login` counts as a human of `factory` (case-insensitive, as logins are). */
229
+ function isHumanOf(parsed, factory, login) {
230
+ const doc = usable(parsed);
231
+ const f = doc && doc.factories[factory];
232
+ return !!(f && login && f.humans.includes(String(login).toLowerCase()));
233
+ }
234
+
235
+ /**
236
+ * An OpenSSH allowed_signers file for one namespace: one line per factory, principal = factory id.
237
+ * Feed it to `ssh-keygen -Y verify -f` (verdicts, namespace `colab-verdict`) or set it as
238
+ * `gpg.ssh.allowedSignersFile` for `git verify-commit` (claim commits, namespace `git`).
239
+ * An invalid file yields an EMPTY list — nothing verifies, which is the fail-closed answer.
240
+ */
241
+ function allowedSigners(parsed, namespace) {
242
+ const doc = usable(parsed);
243
+ if (!doc) return '';
244
+ return Object.entries(doc.factories)
245
+ .map(([id, f]) => `${id} namespaces="${namespace}" ${f.key.split(' ').slice(0, 2).join(' ')}\n`)
246
+ .join('');
247
+ }
248
+
249
+ const FIELD_VALUE_RE = /^[^\s=]+$/;
250
+
251
+ /**
252
+ * The canonical payload a verdict signature covers — the exact bytes, as a string:
253
+ *
254
+ * colab-verdict/1\n
255
+ * forge=<forge>\n repo=<owner/name>\n issue=<N>\n phase=<phase>\n verdict=<v>\n head=<sha40>\n factory=<id>\n
256
+ *
257
+ * (one field per line, no spaces, LF endings, a trailing LF). `ctx` = `{ forge, repo }` from the
258
+ * verifier's own context — the factories file's `forge` and the repository it is reading — never
259
+ * from the comment. `fields` = `{ issue, phase, verdict, head, factory }`: `issue` is the issue the
260
+ * comment sits on (the verifier's context again — the marker does not carry it), the rest from the
261
+ * marker.
262
+ * Throws on a field that cannot be encoded unambiguously; a signer and a verifier that disagree
263
+ * about bytes would make every signature fail, so there is no lenient mode.
264
+ */
265
+ function verdictPayload(fields, ctx) {
266
+ const all = { forge: ctx && ctx.forge, repo: ctx && ctx.repo, ...(fields || {}) };
267
+ all.issue = all.issue == null ? all.issue : String(all.issue);
268
+ if (!/^[1-9][0-9]*$/.test(all.issue || '')) throw new TypeError(`verdictPayload: issue must be a positive integer, got ${JSON.stringify(all.issue)}`);
269
+ if (!/^[0-9a-f]{40}$/.test(all.head || '')) throw new TypeError(`verdictPayload: head must be a full 40-hex commit sha, got ${JSON.stringify(all.head)}`);
270
+ if (!VERDICTS.includes(all.verdict)) throw new TypeError(`verdictPayload: verdict must be one of ${VERDICTS.join(', ')}, got ${JSON.stringify(all.verdict)}`);
271
+ if (!FACTORY_ID_RE.test(all.factory || '')) throw new TypeError(`verdictPayload: factory ${JSON.stringify(all.factory)} is not a factory id`);
272
+ if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(all.repo || '')) throw new TypeError(`verdictPayload: repo must be owner/name, got ${JSON.stringify(all.repo)}`);
273
+ for (const k of PAYLOAD_FIELDS) {
274
+ if (typeof all[k] !== 'string' || !FIELD_VALUE_RE.test(all[k])) throw new TypeError(`verdictPayload: ${k} must be a non-empty value with no space or "=", got ${JSON.stringify(all[k])}`);
275
+ }
276
+ return `${PAYLOAD_HEADER}\n${PAYLOAD_FIELDS.map((k) => `${k}=${all[k]}`).join('\n')}\n`;
277
+ }
278
+
279
+ /** An armored SSH signature (`-----BEGIN SSH SIGNATURE-----` …) → the one-line `sig=` value. */
280
+ function sigFromArmor(armored) {
281
+ const body = String(armored || '').split(/\r?\n/).filter((l) => l && !/^-----(BEGIN|END) SSH SIGNATURE-----$/.test(l)).join('');
282
+ if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) throw new TypeError('sigFromArmor: not an armored SSH signature');
283
+ return body;
284
+ }
285
+
286
+ /** The one-line `sig=` value → the armored form `ssh-keygen -Y verify -s` reads (70-column lines). */
287
+ function armorFromSig(sig) {
288
+ const s = String(sig || '');
289
+ const lines = s.match(/.{1,70}/g) || [];
290
+ return `-----BEGIN SSH SIGNATURE-----\n${lines.join('\n')}\n-----END SSH SIGNATURE-----\n`;
291
+ }
292
+
293
+ const MARKER_RE = /^<!-- colab:verdict ((?:[a-z][a-z0-9_-]*=[^\s=]+=* ?)+)-->$/;
294
+
295
+ /** `{ phase, verdict, head, factory, sig, extra? }` → the marker. `extra` fields ride UNSIGNED. */
296
+ function encodeVerdictMarker({ phase, verdict, head, factory, sig, extra = {} }) {
297
+ const parts = [`phase=${phase}`, `v=${verdict}`, `head=${head}`, `factory=${factory}`];
298
+ for (const [k, v] of Object.entries(extra)) parts.push(`${k}=${v}`);
299
+ parts.push(`sig=${sig}`);
300
+ for (const p of parts) if (!/^[a-z][a-z0-9_-]*=[^\s=]+=*$/.test(p)) throw new TypeError(`encodeVerdictMarker: field ${JSON.stringify(p)} cannot be encoded`);
301
+ return `<!-- colab:verdict ${parts.join(' ')} -->`;
302
+ }
303
+
304
+ /**
305
+ * One marker line → `{ phase, verdict, head, factory, sig, signed, extra }`, or null.
306
+ * `signed` is true only when it carries both `factory` and `sig` — an unsigned marker (the form
307
+ * written before #739) still decodes, and must never be read as any factory's word.
308
+ */
309
+ function decodeVerdictMarker(line) {
310
+ const m = MARKER_RE.exec(String(line || '').trim());
311
+ if (!m) return null;
312
+ const f = {};
313
+ for (const tok of m[1].trim().split(' ')) {
314
+ const i = tok.indexOf('=');
315
+ f[tok.slice(0, i)] = tok.slice(i + 1);
316
+ }
317
+ const known = new Set(['phase', 'v', 'head', 'factory', 'sig']);
318
+ const extra = Object.fromEntries(Object.entries(f).filter(([k]) => !known.has(k)));
319
+ return { phase: f.phase || null, verdict: f.v || null, head: f.head || null, factory: f.factory || null,
320
+ sig: f.sig || null, signed: !!(f.factory && f.sig), extra };
321
+ }
322
+
323
+ module.exports = {
324
+ PATH, VERSION, TIERS, VERDICTS,
325
+ FACTORY_LABEL_PREFIX, SLICE_LABEL_PREFIX, QUEUE_READY_LABEL, REVIEW_LABEL_PREFIX, AUDIT_STATUS_CONTEXT,
326
+ VERDICT_NAMESPACE, CLAIM_NAMESPACE, PAYLOAD_HEADER, PAYLOAD_FIELDS,
327
+ reviewStatusContext, parseFactories, factoryOfMachine, factoryOfSlice, isHumanOf, allowedSigners,
328
+ verdictPayload, sigFromArmor, armorFromSig, encodeVerdictMarker, decodeVerdictMarker,
329
+ };
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 };