@futurelastic/colab-handbook 1.14.0-rc.8 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -397,7 +397,7 @@ function remainingSteps(ctx = {}) {
397
397
  { n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
398
398
  );
399
399
  if (ctx.fork) {
400
- steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
400
+ steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched, and keep \`instruction-files: upstream\` in .github/project.yml (adopt writes it with the descriptor; add it by hand to one that predates #602) so the instruction-file check leaves the upstream's files unjudged; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
401
401
  const agentFiles = ctx.upstreamAgentFiles || [];
402
402
  if (agentFiles.length) {
403
403
  steps.push({ n: 5, text: `Upstream ships its own agent workflow (${listShort(agentFiles)}): leave it in place, and say in the appended block that fork work runs code-start → code-wrap → code-ship, not that workflow — §9 "A fork of an upstream", step 5` });
@@ -69,7 +69,19 @@ const HUMAN = 'human';
69
69
  * GitHub's close reason takes. Frozen and closed: a kind outside this list is not a disposition
70
70
  * with an unknown authority, it is not a disposition.
71
71
  */
72
- const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-boss', 'not planned', 'leave']);
72
+ const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-owner', 'not planned', 'leave']);
73
+
74
+ /**
75
+ * #609 — names this module still READS but never writes. `needs-owner` replaced `needs-boss`
76
+ * ("Boss" named one deployment's human; the standard is for any owner). During the switch a
77
+ * reader must accept both, or an issue marked under the old name reads as unrecognised — "not
78
+ * cleared" — to a tool that only knows the new one. Each legacy name classifies exactly like the
79
+ * kind it maps to. Kept out of KINDS / TOKENS / TOKEN_BY_KIND on purpose: those are what a writer
80
+ * may emit, and `formatMarker` refuses a legacy kind. Drop an entry once the old name has had no
81
+ * open use for its window (a separate issue, filed then).
82
+ */
83
+ const LEGACY_KINDS = Object.freeze({ 'needs-boss': 'needs-owner' });
84
+ const LEGACY_TOKENS = Object.freeze({ 'needs-boss': 'needs-owner' });
73
85
 
74
86
  /**
75
87
  * The same seven by MARKER TOKEN. No token is a prefix or a decorated variant of another — the
@@ -82,13 +94,14 @@ const TOKEN_BY_KIND = Object.freeze({
82
94
  split: 'split',
83
95
  'routed-out': 'routed-out',
84
96
  hold: 'hold',
85
- 'needs-boss': 'needs-boss',
97
+ 'needs-owner': 'needs-owner',
86
98
  'not planned': 'not-planned',
87
99
  leave: 'leave',
88
100
  });
89
- const KIND_BY_TOKEN = Object.freeze(
90
- Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind]))
91
- );
101
+ const KIND_BY_TOKEN = Object.freeze({
102
+ ...Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind])),
103
+ ...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609)
104
+ });
92
105
  const TOKENS = Object.freeze(Object.values(TOKEN_BY_KIND));
93
106
 
94
107
  /**
@@ -149,7 +162,10 @@ function parseMarker(text) {
149
162
  if (typeof text !== 'string' || text === '') return null;
150
163
  const tokens = [...text.matchAll(new RegExp(MARKER_PATTERN, 'g'))].map((m) => m[1]);
151
164
  if (tokens.length === 0) return null;
152
- const distinct = [...new Set(tokens)];
165
+ // Distinct by the KIND a token reads as, so a legacy token and its current spelling (#609) are
166
+ // one proposal, not two; an unrecognised token stays distinct by its own spelling.
167
+ const distinct = [...new Set(tokens.map((t) => (
168
+ Object.prototype.hasOwnProperty.call(LEGACY_TOKENS, t) ? TOKEN_BY_KIND[LEGACY_TOKENS[t]] : t)))];
153
169
  if (distinct.length > 1) {
154
170
  return { token: null, kind: null, recognised: false, why: `${distinct.length} markers proposing different dispositions` };
155
171
  }
@@ -251,9 +267,10 @@ function verdict(kind, authority, applicable, why, blockers, extra) {
251
267
  */
252
268
  function classify(facts) {
253
269
  const f = facts && typeof facts === 'object' ? facts : {};
254
- const kind = f.kind !== undefined && f.kind !== null
270
+ const named = f.kind !== undefined && f.kind !== null
255
271
  ? f.kind
256
272
  : (f.token !== undefined && f.token !== null ? KIND_BY_TOKEN[f.token] : undefined);
273
+ const kind = Object.prototype.hasOwnProperty.call(LEGACY_KINDS, named) ? LEGACY_KINDS[named] : named;
257
274
 
258
275
  if (!KINDS.includes(kind)) {
259
276
  return verdict(null, HUMAN, false, 'not a recognised disposition — not cleared, never a default', []);
@@ -331,11 +348,11 @@ function classify(facts) {
331
348
  : verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
332
349
  }
333
350
 
334
- case 'needs-boss':
351
+ case 'needs-owner':
335
352
  // Record-first: the pass writes the question down with the apply lever pre-filled and moves
336
353
  // on. It does not stop and wait, and it never applies this itself.
337
354
  return verdict(kind, HUMAN, true,
338
- 'never applied by an agent — the agent records the question, Boss answers, the issue returns to intake', []);
355
+ 'never applied by an agent — the agent records the question, the owner answers, the issue returns to intake', []);
339
356
 
340
357
  case 'not planned': {
341
358
  const sup = f.supersededBy && typeof f.supersededBy === 'object' ? f.supersededBy : {};
@@ -375,7 +392,7 @@ function classify(facts) {
375
392
 
376
393
  module.exports = {
377
394
  AGENT, HUMAN,
378
- KINDS, TOKENS, TOKEN_BY_KIND, KIND_BY_TOKEN,
395
+ KINDS, TOKENS, TOKEN_BY_KIND, KIND_BY_TOKEN, LEGACY_KINDS, LEGACY_TOKENS,
379
396
  ASSERTS_AN_OUTCOME, SKIP_FENCE_CLASSES, EVIDENCE_FIELDS, HOLD_STALE_DAYS, MARKER_PATTERN,
380
397
  parseMarker, formatMarker, evidenceShape, axisPermits, classify,
381
398
  };
@@ -8,15 +8,33 @@
8
8
  * caller. Nothing here takes a list, a flag, an env var or a project.yml field. The allowlist and the
9
9
  * exclusions below are constants, so widening them is a handbook change reviewed in a commit.
10
10
  *
11
- * Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary, a
12
- * symlink, a submodule pointer. A false "no" costs a human click. A false "yes" merges code nobody
13
- * approved.
11
+ * Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary (other
12
+ * than a design artifact under `docs/`, below), a symlink, a submodule pointer. A false "no" costs a
13
+ * human click. A false "yes" merges code nobody approved.
14
+ *
15
+ * #606: the same rule also decides when `colab ship` lands a change WITHOUT WAITING FOR CI
16
+ * (shipDocsOnly, below — on by default, narrowed by `ci-docs-skip`). So widening anything here
17
+ * widens BOTH at once — the binary design-artifact rule below did exactly that: a PNG mockup under
18
+ * `docs/design/` is now docs-only for the autonomy exception too (CONVENTIONS.md §2).
14
19
  */
15
20
 
16
21
  /** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
17
22
  const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
18
23
  /** A path under this top-level directory counts as documentation whatever its extension. */
19
24
  const DOCS_DIR = 'docs/';
25
+ /**
26
+ * #606: a BINARY under `docs/` with one of these extensions is a design artifact (a mockup, a
27
+ * diagram, a printed spec) and counts as documentation. Case-insensitive (`Mock.PNG` matches). Any
28
+ * other binary under `docs/`, and every binary outside it, is still not docs-only.
29
+ */
30
+ const DOCS_BINARY_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.pdf']);
31
+ function docsBinaryOk(p) {
32
+ const s = String(p);
33
+ if (!s.startsWith(DOCS_DIR)) return false;
34
+ const base = s.slice(s.lastIndexOf('/') + 1);
35
+ const dot = base.lastIndexOf('.');
36
+ return dot > 0 && DOCS_BINARY_EXTENSIONS.includes(base.slice(dot).toLowerCase());
37
+ }
20
38
  /** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
21
39
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
22
40
  /**
@@ -77,15 +95,18 @@ function pathReason(p) {
77
95
  * Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
78
96
  * `reason` is one line for a human, set on both outcomes.
79
97
  */
80
- function classify(entries) {
98
+ function classify(entries, { exclude = [] } = {}) {
81
99
  const paths = new Map();
82
100
  for (const e of entries || []) {
83
101
  const why = [];
84
102
  const nameWhy = pathReason(e.path);
85
103
  if (nameWhy) why.push(nameWhy);
104
+ // #606: a path the repo's suite reads, listed in `ci-docs-skip` — documentation, but it needs CI.
105
+ const listed = excludedBy(e.path, exclude);
106
+ if (!nameWhy && listed) why.push(`listed in ci-docs-skip (${listed}) — the suite reads it`);
86
107
  if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
87
108
  if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
88
- if (e.binary) why.push('binary change');
109
+ if (e.binary && !docsBinaryOk(e.path)) why.push('binary change');
89
110
  const prev = paths.get(e.path) || [];
90
111
  paths.set(e.path, [...new Set([...prev, ...why])]);
91
112
  }
@@ -101,6 +122,12 @@ function classify(entries) {
101
122
  return { docsOnly: true, files, offenders: [], reason: `docs-only (${files} files)` };
102
123
  }
103
124
 
125
+ /** The `ci-docs-skip` member `p` is, or sits under — a path prefix, never a string prefix. */
126
+ function excludedBy(p, exclude) {
127
+ const s = String(p);
128
+ return (exclude || []).find((x) => s === x || s.startsWith(`${x}/`)) || null;
129
+ }
130
+
104
131
  /**
105
132
  * Parse `git diff --raw -z --no-renames --no-abbrev` output into
106
133
  * `[{ path, oldMode, newMode, oldSha, newSha, status }]`. The sha/status fields are additive
@@ -151,10 +178,30 @@ function readEntries(git, repo, cmd, range) {
151
178
  * The branch shape: what `branch` changes relative to its merge base with `base` — the same three-dot
152
179
  * diff the squash would land.
153
180
  */
154
- function branchChanges(git, repo, base, branch) {
181
+ function branchChanges(git, repo, base, branch, opts = {}) {
155
182
  const entries = readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
156
183
  if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read the diff ${base}...${branch}` };
157
- return classify(entries);
184
+ return classify(entries, opts);
185
+ }
186
+
187
+ /** One commit's own change (against its parent(s), `diff-tree -m`) — the shape a trunk squash has. */
188
+ function commitChanges(git, repo, sha, opts = {}) {
189
+ const entries = readEntries(git, repo, 'diff-tree', [sha]);
190
+ if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read commit ${String(sha).slice(0, 7)}` };
191
+ return classify(entries, opts);
192
+ }
193
+
194
+ /**
195
+ * #606: does `colab ship` treat this branch as needing no CI? The SAME classification as the
196
+ * autonomy exception (#345), narrowed by the repo's `ci-docs-skip` list — a path the suite reads is
197
+ * documentation but still needs CI — and switched off entirely by `ci-docs-skip: off`. An invalid
198
+ * value reads as off (every reader takes doubt as "CI required"); the audit fails it.
199
+ * Returns the classify() shape plus `{ setting }` (parseCiDocsSkip's verdict).
200
+ */
201
+ function shipDocsOnly(git, repo, base, branch, doc) {
202
+ const setting = parseCiDocsSkip(doc);
203
+ if (!setting.on) return { docsOnly: false, files: 0, offenders: [], reason: setting.reason, setting };
204
+ return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude }), setting };
158
205
  }
159
206
 
160
207
  /**
@@ -179,24 +226,32 @@ function directChanges(git, repo, trunk, since) {
179
226
  }
180
227
 
181
228
  /**
182
- * #570: `ci-docs-skip:` in project.yml — the opt-in to the CI templates' docs-only mode. Absent (or
183
- * null) = off. A list = on; each member is a repo path whose changes always run the suite even though
184
- * this module calls them documentation (`docs/api/` feeding a generator). `[]` = on, nothing excluded.
229
+ * #570/#606: `ci-docs-skip:` in project.yml — which changes `colab ship` may land without waiting for
230
+ * CI (#606), and the paths the CI templates' legacy guard (#570) excludes. ON BY DEFAULT for ship:
231
+ * absent = on, nothing excluded. A list = on, and each member is a repo path whose changes always run
232
+ * the suite even though this module calls them documentation (`docs/api/` feeding a generator, a
233
+ * README a link checker reads). `[]` = on, nothing excluded. `off` = the one opt-out, for a repo whose
234
+ * suite reads most of its docs (YAML 1.1 readers turn a bare `off` into boolean false; both spell it).
185
235
  *
186
- * The CI guard parses the same shape in shell and reads anything else as "not opted in" — the
187
- * stricter direction — so an invalid value here is a finding: a declaration that silently does
188
- * nothing. Members are plain paths (the guard matches `p == x` or `p` under `x/`): no glob, no `..`
189
- * or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
236
+ * The legacy CI guard parses the same list in shell, but stays opt-in until its follow-up removes it:
237
+ * there `off` and absent both mean "run the full suite". Both readers take anything else — an empty
238
+ * `ci-docs-skip:` included — as "CI required", the stricter direction. So an invalid value here is a finding:
239
+ * a declaration that silently opts the repo out. Members are plain paths (the guard matches `p == x`
240
+ * or `p` under `x/`): no glob, no `..` or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
190
241
  */
191
242
  const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
192
243
  function parseCiDocsSkip(doc) {
193
244
  const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
194
- const v = has ? doc[CI_DOCS_SKIP_KEY] : null;
195
- if (v === null || v === undefined) {
196
- return { declared: false, valid: true, on: false, exclude: null, reason: 'ci-docs-skip absent — a docs-only change runs the full CI suite (#570)' };
245
+ if (!has) {
246
+ return { declared: false, valid: true, on: true, exclude: [], reason: 'ci-docs-skip absent — on by default (#606): colab ship lands a docs-only change without waiting for CI' };
247
+ }
248
+ const v = doc[CI_DOCS_SKIP_KEY];
249
+ if (v === 'off' || v === false) {
250
+ return { declared: true, valid: true, on: false, exclude: null, reason: 'ci-docs-skip: off — colab ship requires CI for every change' };
197
251
  }
198
252
  const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
199
- reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none); the CI guard reads anything else as not opted in, so docs-only changes run the full suite` });
253
+ reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none) or \`off\`; every reader takes anything else as "CI required", so the declaration silently opts this repo out of the docs-only path` });
254
+ if (v === null || v === undefined) return bad('is empty');
200
255
  if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
201
256
  const exclude = [];
202
257
  for (const m of v) {
@@ -207,11 +262,11 @@ function parseCiDocsSkip(doc) {
207
262
  exclude.push(s);
208
263
  }
209
264
  return { declared: true, valid: true, on: true, exclude,
210
- reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change skips the CI suite' };
265
+ reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — colab ship lands a docs-only change without waiting for CI' };
211
266
  }
212
267
 
213
268
  module.exports = {
214
- DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
269
+ DOC_EXTENSIONS, DOCS_DIR, DOCS_BINARY_EXTENSIONS, docsBinaryOk, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
215
270
  pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
216
- CI_DOCS_SKIP_KEY, parseCiDocsSkip,
271
+ CI_DOCS_SKIP_KEY, parseCiDocsSkip, excludedBy, commitChanges, shipDocsOnly,
217
272
  };
package/tools/lib/git.js CHANGED
@@ -755,6 +755,11 @@ function ghPrClose(repo, num, comment) {
755
755
  return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
756
756
  }
757
757
 
758
+ /** #605: cancel one workflow run (a deleted batch ref's run still in flight). The run result, ok or not. */
759
+ function ghRunCancel(repo, id) {
760
+ return gh(['run', 'cancel', String(id)], { cwd: repo });
761
+ }
762
+
758
763
  function ghIssueComment(repo, issueNum, body) {
759
764
  const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
760
765
  if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
@@ -1441,5 +1446,5 @@ module.exports = {
1441
1446
  ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
1442
1447
  ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
1443
1448
  ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
1444
- ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
1449
+ ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility, ghRunCancel,
1445
1450
  };
@@ -328,6 +328,30 @@ function ratchetVerdict({ changed = [], head = [], base = null }) {
328
328
  return { fail: false, reason: null, bad };
329
329
  }
330
330
 
331
+ /**
332
+ * #602 — `instruction-files:` in .github/project.yml → `{ declared, exempt, valid, value, reason }`.
333
+ * `upstream` says this repo's CLAUDE.md/AGENTS.md belong to an upstream it tracks (a fork,
334
+ * CONVENTIONS.md §9 *A fork of an upstream*), so the shape is not judged here. Absent = judged.
335
+ * Any other value is invalid and read in the STRICTER direction — judged — while the audit fails
336
+ * the value. The committed record of `colab adopt`'s fork test, which reads a remote CI never has;
337
+ * never a second fork test.
338
+ */
339
+ const INSTRUCTION_FILES_KEY = 'instruction-files';
340
+ function parseInstructionFiles(doc) {
341
+ const has = !!doc && typeof doc === 'object' && Object.prototype.hasOwnProperty.call(doc, INSTRUCTION_FILES_KEY);
342
+ const v = has ? doc[INSTRUCTION_FILES_KEY] : null;
343
+ if (v === null || v === undefined) {
344
+ return { declared: false, exempt: false, valid: true, value: null, reason: 'instruction-files absent — every CLAUDE.md is judged (#588)' };
345
+ }
346
+ if (v === 'upstream') {
347
+ return { declared: true, exempt: true, valid: true, value: 'upstream', reason: 'instruction-files: upstream — CLAUDE.md/AGENTS.md are upstream-owned (a fork), so their shape is not judged here (CONVENTIONS.md §9, #602)' };
348
+ }
349
+ return {
350
+ declared: true, exempt: false, valid: false, value: v,
351
+ reason: `instruction-files is ${JSON.stringify(v)} — the only defined value is "upstream"; read as absent, so every CLAUDE.md is still judged (#602)`,
352
+ };
353
+ }
354
+
331
355
  module.exports = {
332
356
  stripCode,
333
357
  IMPORT_MAX_DEPTH,
@@ -349,4 +373,6 @@ module.exports = {
349
373
  judgeClaudeMd,
350
374
  RULE_FILE_RE,
351
375
  ratchetVerdict,
376
+ INSTRUCTION_FILES_KEY,
377
+ parseInstructionFiles,
352
378
  };
@@ -22,6 +22,7 @@ const fs = require('fs');
22
22
  const path = require('path');
23
23
  const { execFileSync } = require('child_process');
24
24
  const inst = require('./instruction-file.js');
25
+ const yaml = require('./yaml.js');
25
26
 
26
27
  const CLAUDE_RE = /(^|\/)CLAUDE\.md$/;
27
28
 
@@ -84,6 +85,26 @@ function judgeSide(cwd, side) {
84
85
  });
85
86
  }
86
87
 
88
+ /**
89
+ * #602 — the `instruction-files:` declaration on `side`, read from the SAME tree the CLAUDE.md
90
+ * files are judged on (head, index or working tree), never the merge base: a fork's adoption
91
+ * change adds the key, the CI caller and the appended Conventions block together, and the block
92
+ * touches CLAUDE.md — a base-side read would fail exactly the change that declares the exemption.
93
+ * An unreadable or unparseable descriptor reads as absent (judged — the stricter direction).
94
+ */
95
+ function declarationOn(cwd, side) {
96
+ const text = reader(cwd, side)('.github/project.yml');
97
+ if (text === null || text === undefined) return inst.parseInstructionFiles(null);
98
+ let doc = null;
99
+ try { doc = yaml.parse(text); } catch (_) { doc = null; }
100
+ return inst.parseInstructionFiles(doc);
101
+ }
102
+
103
+ /** The neutral verdict of a repo whose instruction files are upstream-owned. */
104
+ function exemptVerdict(mode, base, decl) {
105
+ return { ok: true, mode, base, exempt: decl.value, reason: null, fail: false, files: [], bad: [], changed: [] };
106
+ }
107
+
87
108
  /**
88
109
  * Run the gate. Options:
89
110
  * cwd repo (default process.cwd())
@@ -93,7 +114,10 @@ function judgeSide(cwd, side) {
93
114
  * With neither `staged` nor `base`, every CLAUDE.md at the head is judged with no ratchet:
94
115
  * any non-conforming file fails (`reason: 'strict'`).
95
116
  *
96
- * Returns `{ ok, error?, fail, reason, mode, base, files, bad, changed }`. `ok: false` means the
117
+ * A repo declaring `instruction-files: upstream` on the judged side (#602) is not judged: the
118
+ * verdict is `{ ok: true, exempt: 'upstream', fail: false, files: [] }`, whatever its CLAUDE.md says.
119
+ *
120
+ * Returns `{ ok, error?, exempt?, fail, reason, mode, base, files, bad, changed }`. `ok: false` means the
97
121
  * gate could not answer (not a repo, base unknown, merge base not reachable in a shallow clone)
98
122
  * — callers must refuse rather than read that as a pass.
99
123
  */
@@ -102,6 +126,8 @@ function gate({ cwd = process.cwd(), staged = false, base = null, head = null }
102
126
  const hasHead = git(cwd, ['rev-parse', '--verify', '-q', 'HEAD^{commit}']) !== null;
103
127
 
104
128
  if (staged) {
129
+ const decl = declarationOn(cwd, 'index');
130
+ if (decl.exempt) return exemptVerdict('staged', hasHead ? 'HEAD' : null, decl);
105
131
  const files = judgeSide(cwd, 'index');
106
132
  const changed = (git(cwd, ['diff', '--cached', '--name-only', '-z']) || '').split('\0').filter(Boolean);
107
133
  const baseFiles = hasHead ? judgeSide(cwd, { ref: 'HEAD' }) : [];
@@ -111,6 +137,8 @@ function gate({ cwd = process.cwd(), staged = false, base = null, head = null }
111
137
 
112
138
  const headSide = head === 'worktree' ? 'worktree' : { ref: head || 'HEAD' };
113
139
  if (headSide !== 'worktree' && !hasHead && !head) return { ok: false, error: 'HEAD has no commit yet' };
140
+ const decl = declarationOn(cwd, headSide);
141
+ if (decl.exempt) return exemptVerdict(base ? 'ratchet' : 'strict', null, decl);
114
142
  const files = judgeSide(cwd, headSide);
115
143
  if (files === null) return { ok: false, error: `cannot read ${head || 'HEAD'}` };
116
144
 
@@ -135,6 +163,7 @@ function gate({ cwd = process.cwd(), staged = false, base = null, head = null }
135
163
  /** One human line per verdict, naming the fix. */
136
164
  function describe(r) {
137
165
  if (!r.ok) return [`cannot judge: ${r.error}`];
166
+ if (r.exempt) return [`instruction files not judged: \`instruction-files: ${r.exempt}\` in .github/project.yml — CLAUDE.md/AGENTS.md are upstream-owned on this fork (CONVENTIONS.md §9 "A fork of an upstream", #602)`];
138
167
  if (!r.bad.length) return [`instruction files conform (${r.files.length} CLAUDE.md judged)`];
139
168
  const why = {
140
169
  touched: 'this change touches CLAUDE.md/AGENTS.md, so every CLAUDE.md must conform',
@@ -147,4 +176,4 @@ function describe(r) {
147
176
  return lines;
148
177
  }
149
178
 
150
- module.exports = { CLAUDE_RE, listClaude, reader, judgeSide, gate, describe };
179
+ module.exports = { CLAUDE_RE, listClaude, reader, judgeSide, declarationOn, gate, describe };
@@ -0,0 +1,161 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/integration-profile.js — where a repo's heavy CI lane runs, and what a green trunk
4
+ * promises (#610). The pure half: project.yml in, a profile and verdicts out. No git, no gh.
5
+ *
6
+ * #607 split CI into a light lane (every push; the lane `colab ship` reads) and a heavy lane (the
7
+ * whole suite, e2e, load: nightly and at every official build). That is ONE shape. Some repos cannot
8
+ * accept a trunk that is only light-green between releases; others want the heavy lane more often
9
+ * than at release. `integration-profile:` makes the shape a declared choice:
10
+ *
11
+ * gated every landing waits on a green heavy run at the candidate's exact sha
12
+ * (the branch head, or the batch head under `colab ship --batch`). Trunk is
13
+ * always heavy-green.
14
+ * qualify ship reads the light lane only; the heavy lane runs on trunk on a clock (the
15
+ * heavy workflow's cron), plus nightly and at the release gate. Trunk may be heavy-
16
+ * red for at most one clock window; a red is reverted first.
17
+ * release-heavy #607's shape and the DEFAULT when the key is absent: light per merge, heavy
18
+ * nightly and at the official build.
19
+ * promote a `develop → main` repo: the heavy lane gates the promotion. Kept for repos that
20
+ * already run it for an approval gate; not offered to new repos.
21
+ *
22
+ * Under EVERY profile a final release needs the heavy lane green at the candidate's sha, wherever the
23
+ * repo has a heavy lane at all (release-finalize.js `heavy-lane`).
24
+ *
25
+ * The heavy lane is found by its workflow FILE (`heavy-workflow:`, default `ci-heavy.yml` — the name
26
+ * #607's templates give it, and the name release-auto.yml already dispatches by). Run rows carry the
27
+ * workflow's `name:`, not its file, so the caller reads the file at the sha to learn which rows are
28
+ * heavy (`tools/colab` heavyWorkflowNameAt).
29
+ *
30
+ * FAIL CLOSED, like parseShipBatch: a malformed value reads as the default (`release-heavy`, ship
31
+ * unchanged) and the audit fails it. A typo must never silently weaken a declared `gated` — but it
32
+ * cannot strengthen anything either, and the audit is where a broken descriptor is reported.
33
+ */
34
+
35
+ const KEY = 'integration-profile';
36
+ const HEAVY_KEY = 'heavy-workflow';
37
+ const PROFILES = Object.freeze(['gated', 'qualify', 'release-heavy', 'promote']);
38
+ const DEFAULT_PROFILE = 'release-heavy';
39
+ const DEFAULT_HEAVY_WORKFLOW = 'ci-heavy.yml';
40
+
41
+ function hasKey(doc, key) {
42
+ return !!doc && Object.prototype.hasOwnProperty.call(doc, key) && doc[key] !== null && doc[key] !== undefined && doc[key] !== '';
43
+ }
44
+
45
+ /** `{ profile, declared, valid, reason }` — absent → release-heavy, undeclared; bad → release-heavy, invalid. */
46
+ function parseProfile(doc) {
47
+ if (!hasKey(doc, KEY)) return { profile: DEFAULT_PROFILE, declared: false, valid: true, reason: `${KEY} absent (${DEFAULT_PROFILE})` };
48
+ const raw = doc[KEY];
49
+ const v = typeof raw === 'string' ? raw.trim() : raw;
50
+ if (typeof v === 'string' && PROFILES.includes(v)) return { profile: v, declared: true, valid: true, reason: `${KEY}: ${v}` };
51
+ return { profile: DEFAULT_PROFILE, declared: true, valid: false,
52
+ reason: `${KEY} is ${JSON.stringify(raw)}, expected one of ${PROFILES.join(' | ')} (omit for ${DEFAULT_PROFILE})` };
53
+ }
54
+
55
+ /** `{ file, declared, valid, reason }` — a bare workflow file name under .github/workflows. */
56
+ function parseHeavyWorkflow(doc) {
57
+ if (!hasKey(doc, HEAVY_KEY)) return { file: DEFAULT_HEAVY_WORKFLOW, declared: false, valid: true, reason: `${HEAVY_KEY} absent (${DEFAULT_HEAVY_WORKFLOW})` };
58
+ const raw = doc[HEAVY_KEY];
59
+ const v = typeof raw === 'string' ? raw.trim() : '';
60
+ if (/^[A-Za-z0-9._-]+\.ya?ml$/.test(v)) return { file: v, declared: true, valid: true, reason: `${HEAVY_KEY}: ${v}` };
61
+ return { file: DEFAULT_HEAVY_WORKFLOW, declared: true, valid: false,
62
+ reason: `${HEAVY_KEY} is ${JSON.stringify(raw)}, expected a workflow file name in .github/workflows (e.g. ${DEFAULT_HEAVY_WORKFLOW})` };
63
+ }
64
+
65
+ /**
66
+ * The heavy lane's verdict at one sha, from the rows of that workflow at that sha
67
+ * (`{status, conclusion}`). Same all-runs reading as ship's: any finished not-green row (cancelled
68
+ * aside) is red; any unfinished row is pending; green needs a success. A red re-run green later is
69
+ * still red here only while the red row is the newest — callers pass the newest attempt's rows.
70
+ * null rows → `unread` (the run list could not be read — never "none")
71
+ */
72
+ function heavyVerdict(rows) {
73
+ if (!Array.isArray(rows)) return { state: 'unread', why: 'the run list could not be read' };
74
+ if (!rows.length) return { state: 'none', why: 'no heavy run at this sha' };
75
+ // A re-run is the same run with a higher attempt; separate dispatches are separate rows. The newest
76
+ // dispatch speaks for the sha (a red then a green re-dispatch is green), so read the newest row.
77
+ const newest = rows.slice().sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')))[0];
78
+ const ref = newest.url || (newest.databaseId !== undefined && newest.databaseId !== null ? `run ${newest.databaseId}` : null);
79
+ if (newest.status !== 'completed') return { state: 'pending', why: `the heavy run is ${newest.status || 'in flight'}`, url: ref };
80
+ if (newest.conclusion === 'success') return { state: 'green', why: 'the heavy run succeeded', url: ref };
81
+ if (newest.conclusion === 'cancelled') return { state: 'none', why: 'the newest heavy run was cancelled', url: ref };
82
+ return { state: 'red', why: `the heavy run finished ${newest.conclusion || 'without a conclusion'}`, url: ref };
83
+ }
84
+
85
+ /**
86
+ * #610's one restriction: on exposure `live` the promotion deploys, so a trunk that may be heavy-red
87
+ * (qualify, release-heavy) must not feed it — unless the deploy is a tag the release gate qualifies.
88
+ * Only a DECLARED profile is refused: an absent key reads release-heavy for ship, but a repo that never
89
+ * declared is not suddenly failing; it gets a suggestion instead. Returns null or `{ level, message }`.
90
+ */
91
+ function liveRestriction({ profile, declared, exposure, deploy }) {
92
+ if (exposure !== 'live') return null;
93
+ if (deploy === 'tag') return null;
94
+ if (profile === 'gated' || profile === 'promote') return null;
95
+ if (declared) {
96
+ return { level: 'fail', message: `${KEY}: ${profile} on exposure: live with deploy: ${deploy || '(none)'} — ${profile} allows a heavy-red trunk, and here the promotion deploys it. Choose gated, or deploy from a qualified tag (CONVENTIONS.md §7, Integration profiles)` };
97
+ }
98
+ return { level: 'suggest', message: `exposure: live reads ${KEY}: ${DEFAULT_PROFILE} by default, which allows a heavy-red trunk to be promoted — consider declaring ${KEY}: gated (CONVENTIONS.md §7, Integration profiles)` };
99
+ }
100
+
101
+ /**
102
+ * The gate a `colab ship` landing must pass under the profile, given the heavy verdict at the
103
+ * candidate. Only `gated` gates a landing; every other profile returns null (ship reads the light
104
+ * lane exactly as before). `docsOnly` landings never wait on CI (#606) and are exempt here too.
105
+ * → null | { ok, action: 'pass'|'dispatch'|'wait'|'refuse', detail }
106
+ */
107
+ function landingGate({ profile, docsOnly = false, heavyPresent, verdict, file, at }) {
108
+ if (profile !== 'gated' || docsOnly) return null;
109
+ if (!heavyPresent) {
110
+ return { ok: false, action: 'refuse', detail: `${KEY}: gated, but no .github/workflows/${file} at ${at} — gated lands only on a green heavy run, and there is no heavy lane to run (add one from templates/ci-<stack>-heavy.yml, or name it with ${HEAVY_KEY}:)` };
111
+ }
112
+ const v = verdict || { state: 'unread', why: 'not read' };
113
+ const link = v.url ? ` (${v.url})` : '';
114
+ switch (v.state) {
115
+ case 'green': return { ok: true, action: 'pass', detail: `${KEY}: gated — heavy lane green at ${at}${link}` };
116
+ case 'none': return { ok: false, action: 'dispatch', detail: `${KEY}: gated — no heavy run at ${at} yet (${v.why})` };
117
+ case 'pending': return { ok: false, action: 'wait', detail: `${KEY}: gated — ${v.why} at ${at}${link}` };
118
+ case 'red': return { ok: false, action: 'refuse', detail: `${KEY}: gated — ${v.why} at ${at}${link}; it blocks landing (fix it, or re-dispatch the heavy lane once a flake is proven)` };
119
+ default: return { ok: false, action: 'wait', detail: `${KEY}: gated — cannot read the heavy lane at ${at} (${v.why})` };
120
+ }
121
+ }
122
+
123
+ /**
124
+ * A batch's effective verdict under `gated`: the combined (light) verdict AND the heavy verdict at the
125
+ * batch head. Shapes match ship-batch.js combinedVerdict (`{state, attempt, runIds, why}`), so the
126
+ * existing re-run / split / land machinery reads it unchanged — a heavy red splits the wave toward the
127
+ * culprit exactly as a light red does. `heavy: null` (profile not gated) → the light verdict as is.
128
+ */
129
+ function waveVerdict(light, heavy) {
130
+ if (!heavy || !light) return light;
131
+ if (light.state !== 'green') return light;
132
+ if (heavy.state === 'green') return { ...light, why: `${light.why}; heavy lane green` };
133
+ if (heavy.state === 'red') return { ...light, state: 'red', why: `heavy lane: ${heavy.why}${heavy.url ? ` (${heavy.url}; re-dispatch it for a red:infra, it is not one of the run ids below)` : ''}` };
134
+ return { ...light, state: 'pending', heavyMissing: heavy.state === 'none', why: `light green; heavy lane: ${heavy.why}` };
135
+ }
136
+
137
+ /**
138
+ * The final release's heavy-lane condition — under EVERY profile (#610). A repo with no heavy lane at
139
+ * the candidate has nothing to gate (#607's templates say the same: "no heavy lane here → no gate"),
140
+ * so it passes and says so; refusing every release of a repo that never wrote one would break every
141
+ * adopter. With one: green → ok; red → blocking; none / running / unreadable → `pending` — the
142
+ * candidate keeps testing, it is not refused (the release workflow starts the heavy lane at each
143
+ * candidate; by hand: the printed command).
144
+ * → { ok, pending, detail }
145
+ */
146
+ function releaseHeavyCondition({ present, file, verdict, at, ref }) {
147
+ if (!present) return { ok: true, pending: false, detail: `no .github/workflows/${file} at ${at} — no heavy lane in this repo, nothing to gate` };
148
+ const v = verdict || { state: 'unread', why: 'not read' };
149
+ const link = v.url ? ` (${v.url})` : '';
150
+ const start = `gh workflow run ${file} --ref ${ref || '<the candidate tag>'} -f ref=${ref || '<the candidate tag>'}`;
151
+ if (v.state === 'green') return { ok: true, pending: false, detail: `heavy lane green at ${at}${link}` };
152
+ if (v.state === 'red') return { ok: false, pending: false, detail: `heavy lane red at ${at}${link} — a final needs it green at this exact sha: re-run it green, or cut a new candidate` };
153
+ if (v.state === 'pending') return { ok: false, pending: true, detail: `heavy lane still running at ${at}${link} — no final until it is green` };
154
+ if (v.state === 'none') return { ok: false, pending: true, detail: `no heavy run at ${at} yet — start it: ${start}` };
155
+ return { ok: false, pending: true, detail: `cannot read the heavy lane at ${at} (${v.why}) — not finalized in this run` };
156
+ }
157
+
158
+ module.exports = {
159
+ KEY, HEAVY_KEY, PROFILES, DEFAULT_PROFILE, DEFAULT_HEAVY_WORKFLOW,
160
+ parseProfile, parseHeavyWorkflow, heavyVerdict, liveRestriction, landingGate, waveVerdict, releaseHeavyCondition,
161
+ };
@@ -931,6 +931,8 @@ function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, e
931
931
  * triggers workflow-triggers.js prereleaseTagTriggers(...) findings
932
932
  * lastFinal, suggestion, override, tags, tagsAtSha
933
933
  * ci, suite, schema, switches { ok, detail } each, measured by the caller
934
+ * heavy #610 — integration-profile.js releaseHeavyCondition(), read on the final routes only;
935
+ * absent → no row
934
936
  *
935
937
  * Returns { ok, checks: [{ condition, ok, detail }], refusals, version, tag, bump, overridden }.
936
938
  * Every check is reported, not just the first failure: a caller fixing one refusal should not
@@ -1062,6 +1064,14 @@ function decide(facts) {
1062
1064
  else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
1063
1065
  }
1064
1066
 
1067
+ // #610: a final needs the heavy lane green at its exact sha, under every integration profile. Only
1068
+ // the two final routes tag a final here; a candidate is gated at `release finalize`. A heavy run
1069
+ // still to start or still running is the route holding (a no-op under --auto), not a refusal.
1070
+ if (finalRoute && tag && f.heavy) {
1071
+ add('heavy-lane', f.heavy.ok, f.heavy.detail, f.heavy.pending);
1072
+ if (!f.heavy.ok && f.heavy.pending && f.auto) noop = true;
1073
+ }
1074
+
1065
1075
  // #446: what the fast route keeps in place of the test period it does not have.
1066
1076
  let handoff = null;
1067
1077
  let grant = null;
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
77
77
 
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
- 'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
80
+ 'ci-green', 'full-suite', 'heavy-lane', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
81
  ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
82
82
  ]);
83
83
 
@@ -591,6 +591,7 @@ function handoffCommand(tag) {
591
591
  * trunk trunkGreenVerdict(...)
592
592
  * regressions regressionVerdict(...)
593
593
  * ci, suite, schema, switches { ok, detail }
594
+ * heavy #610 — integration-profile.js releaseHeavyCondition(): { ok, pending, detail }; absent → no row
594
595
  * cutRun #566 — cutRunVerdict(): the run that cut the candidate concluded success
595
596
  * finalGrant #441 — release-policy.js finalGrantVerdict() of policy.effective.finalGrant (only
596
597
  * read when the policy carries one; absent = unresolved, never a grant)
@@ -677,6 +678,10 @@ function decide(facts) {
677
678
  add(condition, v && v.ok, v ? v.detail : 'not measured');
678
679
  }
679
680
  if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
681
+ // #610: the heavy lane green at the candidate's exact sha, under every integration profile.
682
+ // integration-profile.js releaseHeavyCondition; absent from `facts` (a caller predating it) → no row.
683
+ const hv = f.heavy || null;
684
+ if (hv) add('heavy-lane', hv.ok, hv.detail);
680
685
  for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
681
686
  add(condition, v && v.ok, v ? v.detail : 'not measured');
682
687
  }
@@ -690,12 +695,14 @@ function decide(facts) {
690
695
 
691
696
  if (held.length) return out('held');
692
697
  if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
693
- const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
698
+ const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
699
+ && !(c.condition === 'heavy-lane' && hv && hv.pending));
694
700
  if (blocking.length) return out('refused');
695
701
  if (ownClock) {
696
702
  if (!tr.ok && !tr.pending) return out('refused');
697
703
  if (!per.elapsed || tr.pending) return out('testing');
698
704
  }
705
+ if (hv && hv.pending) return out('testing'); // #610: the heavy lane is still to run or still running
699
706
  if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
700
707
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
701
708
  return out('finalized', { finalTag: cand.version });