@futurelastic/colab-handbook 1.12.0 → 1.13.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.
Files changed (73) hide show
  1. package/README.md +243 -213
  2. package/README.vi.md +246 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +6 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1691 -254
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +203 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +4 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +151 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +716 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +762 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +303 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +106 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/stamp.js +7 -0
  65. package/tools/lib/tracker-fake.js +195 -0
  66. package/tools/lib/tracker-github.js +106 -0
  67. package/tools/lib/tracker-scenarios.json +206 -0
  68. package/tools/lib/tracker.js +64 -0
  69. package/tools/lib/tree-green.js +88 -0
  70. package/tools/lib/util.js +17 -1
  71. package/tools/lib/verify-runs.js +104 -0
  72. package/tools/lib/wake.js +8 -90
  73. package/tools/lib/workflow-triggers.js +48 -0
@@ -20,12 +20,16 @@
20
20
  * Everything here is pure (text in, text/verdict out); tools/colab does the IO.
21
21
  */
22
22
 
23
+ const scratchDirs = require('./scratch-dirs');
24
+
23
25
  /**
24
26
  * Paths hidden by `.git/info/exclude`, root-anchored (a leading `/`) so they match only at the
25
27
  * repo root — `CLAUDE.local.md` in a subdirectory the owner commits must stay visible.
26
- * `.claude/plans/` is the plan-file scratch dir code-start already excludes the same way.
28
+ * The session scratch dirs (plans, briefs — #488) are appended by `localExcludePaths` from
29
+ * scratch-dirs.js, so a configured COLAB_PLANS_DIR / COLAB_BRIEFS_DIR is hidden too; the legacy
30
+ * `.claude/plans/` stays among them.
27
31
  */
28
- const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.claude/plans/'];
32
+ const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md'];
29
33
 
30
34
  /**
31
35
  * LOCAL_EXCLUDE_PATHS plus the worktree subdir (`colab worktree new` creates worktrees INSIDE the
@@ -33,9 +37,9 @@ const LOCAL_EXCLUDE_PATHS = ['/.github/project.yml', '/CLAUDE.local.md', '/.clau
33
37
  * `.gitignore`; the owner's repo does not, so without this line every worktree shows up in the
34
38
  * main checkout's `git status` — measured on the #393 fixture the moment the first one was cut.
35
39
  */
36
- function localExcludePaths(worktreeSubdir) {
40
+ function localExcludePaths(worktreeSubdir, env = process.env) {
37
41
  const sub = String(worktreeSubdir || '.worktrees').replace(/^\/+|\/+$/g, '');
38
- return [...LOCAL_EXCLUDE_PATHS, `/${sub}/`];
42
+ return [...LOCAL_EXCLUDE_PATHS, ...scratchDirs.excludeLines(env), `/${sub}/`];
39
43
  }
40
44
 
41
45
  const EXCLUDE_HEADER = '# colab-handbook: local-only adoption (#393) — handbook files this clone keeps out of the owner\'s history';
@@ -41,29 +41,26 @@
41
41
  * this branch and this issue may rely on.
42
42
  */
43
43
 
44
- /** The two comment markers. STABLE WIRE FORMAT — do not reword casually; `tools/colab` and any
45
- * vendored reader parse these verbatim, the same posture as CLAIM_MARK/RELEASE_MARK in tools/colab. */
46
- const GRANT_MARK = '🛢 Migration grant';
47
- const REVOKE_MARK = '🚫 Migration grant revoked';
48
-
49
- // Deliberately DIFFERENT leading emoji (not just different trailing text) so neither `startsWith`
50
- // nor either regex can ever match the other mark's body — a revoke mark that merely suffixed the
51
- // grant mark would make every revoke parse as a fresh grant, silently reopening exactly the door
52
- // it was posted to close. Covered by a dedicated test (grant-revoke-mark-collision).
53
- const GRANT_RE = /^🛢 Migration grant — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
54
- const REVOKE_RE = /^🚫 Migration grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
55
-
56
- /** The exact grant-comment body. Keep in lockstep with GRANT_RE. */
44
+ // The wire format — both marks, both regexes, and the encode/decode pairs — lives in
45
+ // codec/grants.js (#498, epic #496). Re-exported below under the names this module always had.
46
+ // Mark design (distinct leading emoji, so neither regex can match the other mark's body) is
47
+ // documented there; the grant-revoke-mark-collision test still pins it here.
48
+ const crypto = require('crypto');
49
+ const codec = require('./codec/grants');
50
+ const GRANT_MARK = codec.MIGRATION_GRANT_MARK;
51
+ const REVOKE_MARK = codec.MIGRATION_REVOKE_MARK;
52
+ const GRANT_RE = codec.MIGRATION_GRANT_RE;
53
+ const REVOKE_RE = codec.MIGRATION_REVOKE_RE;
54
+
55
+ /** The exact grant-comment body (codec `encodeMigrationGrant`, canonical tail). */
57
56
  function grantCommentBody(branch, host, iso) {
58
- return `${GRANT_MARK} — branch \`${branch}\` · host \`${host}\` · ${iso}`
59
- + ' — this exempts THIS BRANCH only, and expires when this issue closes.';
57
+ return codec.encodeMigrationGrant({ branch, host, at: iso });
60
58
  }
61
59
 
62
- /** The exact revoke-comment body. Keep in lockstep with REVOKE_RE. `branch` is the branch named in
60
+ /** The exact revoke-comment body (codec `encodeMigrationRevoke`). `branch` is the branch named in
63
61
  * the record for the audit trail — revocation itself is NOT branch-scoped (see evaluateIssue doc). */
64
62
  function revokeCommentBody(branch, host, iso) {
65
- return `${REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${iso}`
66
- + ' — every grant on this issue up to this point is cancelled.';
63
+ return codec.encodeMigrationRevoke({ branch, host, at: iso });
67
64
  }
68
65
 
69
66
  /**
@@ -198,13 +195,15 @@ function evaluateIssue(record, branch, issueNum, labelName, opts) {
198
195
  * read (the caller's job, not this function's — see tools/colab's shipMigrationGate).
199
196
  *
200
197
  * `ctx` (#401) — OPTIONAL, and absent means exactly the pre-#401 behaviour (human grants only,
201
- * byte-identical output). Given, it is `{ policy, headSha, roundtrip }` and the ONE rule every
198
+ * byte-identical output). Given, it is `{ policy, headSha, contentId, roundtrip }` and the ONE rule every
202
199
  * ship path shares (`--dry`, `--dry --json`, a real/auto-trunk ship, and batch — which reads
203
200
  * through `--dry --json`) — so no path can accept a grant another refuses. Per issue:
204
201
  * 1. a live human grant passes, unchanged — it wins where both roles exist;
205
202
  * 2. otherwise a reviewer grant passes only when ALL of: P policy is `reviewer` · M a valid,
206
- * passing, trusted, branch-bound reviewer marker + record · HEAD the record's head equals
207
- * `headSha` · R `roundtrip()` says the live CI round-trip passed on that HEAD.
203
+ * passing, trusted, branch-bound reviewer marker + record · HEAD the grant binds the shipped
204
+ * head — the record's head equals `headSha`, or (#508) the record's migration content id
205
+ * equals `contentId`, the id at `headSha` · R `roundtrip()` says the live CI round-trip passed
206
+ * on the SHIPPED head (never the reviewed one).
208
207
  * R is a THUNK, called at most once per set and only once some issue has cleared P, M and HEAD —
209
208
  * so a no-migration, human-granted or already-failing ship pays for no CI read. A thunk returning
210
209
  * anything but `{ ok: true }` (including `null`, a failed read) fails R closed.
@@ -242,23 +241,23 @@ function evaluateShipSet(issues, records, branch, labelName, ctx) {
242
241
  reason: policy === 'reviewer' ? `${h.reason}, and no live reviewer grant either` : h.reason });
243
242
  continue;
244
243
  }
245
- const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, issueNum: n, labelName, policy });
244
+ const r = evaluateReviewerGrant(rec, { branch, headSha: ctx.headSha, contentId: ctx.contentId, issueNum: n, labelName, policy });
246
245
  if (!r.ok) {
247
246
  const failed = !r.checks.policy ? 'policy' : !r.checks.marker ? 'marker' : 'head';
248
247
  missing.push({ issue: n, failed, reason: `reviewer grant [${SHIP_CONDITION_TAG[failed]}]: ${r.reason}` });
249
248
  continue;
250
249
  }
251
- pending.push({ n, g: r.grant });
250
+ pending.push({ n, g: r.grant, via: r.via });
252
251
  }
253
252
  if (pending.length > 0) {
254
253
  let rt = null;
255
254
  try { rt = typeof ctx.roundtrip === 'function' ? ctx.roundtrip() : null; } catch (_) { rt = null; }
256
255
  const ok = !!rt && rt.ok === true;
257
256
  const why = rt && rt.reason ? rt.reason : 'the CI round-trip could not be read — an unread result is never a pass';
258
- for (const { n, g } of pending) {
257
+ for (const { n, g, via } of pending) {
259
258
  if (ok) {
260
- granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head,
261
- branch: g.branch, by: g.login, at: g.at });
259
+ granted.push({ issue: n, role: 'reviewer', reviewer: g.reviewer, head: g.head, via,
260
+ migrations: (g.record && g.record.migrations) || null, branch: g.branch, by: g.login, at: g.at });
262
261
  } else {
263
262
  missing.push({ issue: n, failed: 'roundtrip',
264
263
  reason: `reviewer grant [${SHIP_CONDITION_TAG.roundtrip}]: #${n}: ${why}` });
@@ -345,6 +344,61 @@ function roundtripVerdict(jobs, opts) {
345
344
  return { ok: true, legs, reason: '' };
346
345
  }
347
346
 
347
+ /**
348
+ * #457 — the MINT-time half of R. `colab ship` re-reads the round-trip at the head (roundtripVerdict
349
+ * above, through shipMigrationCtx), so a false `ci-roundtrip: pass` never opened the gate — but the
350
+ * grant record itself could still assert a fact its cited run does not contain, and the issue then
351
+ * sat looking "granted" until a ship pass measured it. This applies the same verdict when the record
352
+ * is WRITTEN, so a record that says `pass` is refused unless CI agrees at `rec.head`.
353
+ *
354
+ * Pure: `runs` is every run at the head — `[{ databaseId, workflowName, jobs }]`, `jobs` being
355
+ * git.ghRunJobs rows — or null when the run list could not be read (a run with `jobs: null` is an
356
+ * unread run). Checks, in order:
357
+ * - the run list and every run's jobs were read (an unread result is never a pass);
358
+ * - roundtripVerdict over all their jobs is ok — the exact rule ship applies, workflows guard
359
+ * included, so a record mint can never accept what ship would refuse;
360
+ * - `ci-run`, when given, resolves to a run id (bare digits, or a `/runs/<id>` URL), names one of
361
+ * those runs, and that run itself carries a round-trip job — a record must not cite a run that
362
+ * does not contain the evidence it is cited for, even when a sibling run does.
363
+ * A record whose `ci-roundtrip` is not `pass` is not this function's to judge (it never mints).
364
+ * Returns { ok, reason, verdict }.
365
+ */
366
+ function mintRoundtripCheck(rec, runs, opts) {
367
+ const o = opts || {};
368
+ const r = rec || {};
369
+ if (r['ci-roundtrip'] !== 'pass') return { ok: true, reason: '', verdict: null };
370
+ const sha = r.head ? String(r.head).slice(0, 7) : 'the head';
371
+ const no = (reason, verdict = null) => ({ ok: false, reason, verdict });
372
+ let jobs = null;
373
+ if (Array.isArray(runs) && runs.every((x) => x && Array.isArray(x.jobs))) {
374
+ jobs = [];
375
+ for (const x of runs) for (const j of x.jobs) jobs.push({ ...j, workflowName: x.workflowName || null });
376
+ }
377
+ const verdict = roundtripVerdict(jobs, { headSha: r.head, workflowsTouched: !!o.workflowsTouched });
378
+ if (!verdict.ok) {
379
+ const hint = verdict.reason.startsWith('no "') ? ` — this repo's CI must run the template's migrations job before a reviewer grant can record a pass` : '';
380
+ return no(`the record says ci-roundtrip: pass, but ${verdict.reason}${hint}`, verdict);
381
+ }
382
+ if (r['ci-run'] !== undefined && r['ci-run'] !== null && String(r['ci-run']) !== '') {
383
+ const id = parseRunId(r['ci-run']);
384
+ if (id === null) return no(`ci-run "${r['ci-run']}" does not name a run id (digits, or a URL ending /runs/<id>) — a cited run nobody can look up proves nothing`, verdict);
385
+ const cited = runs.find((x) => String(x.databaseId) === id);
386
+ if (!cited) return no(`ci-run ${id} is not a run at ${sha} — the record must cite the run that graded the head it binds`, verdict);
387
+ if (!cited.jobs.some((j) => j && typeof j.name === 'string' && j.name.startsWith(ROUNDTRIP_JOB_PREFIX))) {
388
+ return no(`ci-run ${id} has no "${ROUNDTRIP_JOB_PREFIX}" job — cite the run that carries the round-trip`, verdict);
389
+ }
390
+ }
391
+ return { ok: true, reason: '', verdict };
392
+ }
393
+
394
+ /** A run id from a `ci-run` value — bare digits, or the `/runs/<id>` segment of a run URL — or null. */
395
+ function parseRunId(v) {
396
+ const s = String(v).trim();
397
+ if (/^\d+$/.test(s)) return s;
398
+ const m = s.match(/\/runs\/(\d+)(?:[/?#]|$)/);
399
+ return m ? m[1] : null;
400
+ }
401
+
348
402
  /** A step that reached a terminal conclusion other than skipped/cancelled — ci-cure.js stepRan. */
349
403
  function stepRanOk(s) {
350
404
  return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
@@ -373,37 +427,18 @@ function stepRanOk(s) {
373
427
  // `head` itself rather than rely on the recorded value.
374
428
  // ============================================================================================
375
429
 
376
- /** The reviewer grant's first-line mark. STABLE WIRE FORMAT. Distinct leading emoji on purpose:
377
- * GRANT_RE (the human marker, the one today's ship gate reads) must never match a reviewer grant. */
378
- const REVIEW_GRANT_MARK = '🔎 Migration review grant';
379
- const REVIEWER_ROLE = 'migration-reviewer';
430
+ // The reviewer grant's wire format — mark, regex, fence, field table — lives in codec/grants.js
431
+ // (#498). GRANT_RE (the human marker, the one today's ship gate reads) never matches it: distinct
432
+ // leading emoji, on purpose.
433
+ const REVIEW_GRANT_MARK = codec.REVIEW_GRANT_MARK;
434
+ const REVIEWER_ROLE = codec.REVIEWER_ROLE;
380
435
  const GRANT_ROLES = Object.freeze(['human', REVIEWER_ROLE]);
381
-
382
- const REVIEW_GRANT_RE = /^🔎 Migration review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · host `([^`]*)` · (\S+)/;
383
-
384
- /** The fenced block's info string — the record is found by it, never by position. */
385
- const REVIEW_RECORD_FENCE = 'migration-review';
386
- const REVIEW_RECORD_VERSION = '1';
387
-
436
+ const REVIEW_GRANT_RE = codec.REVIEW_GRANT_RE;
437
+ const REVIEW_RECORD_FENCE = codec.REVIEW_RECORD_FENCE;
438
+ const REVIEW_RECORD_VERSION = codec.REVIEW_RECORD_VERSION;
388
439
  const SHA40_RE = /^[0-9a-f]{40}$/;
389
- const REVIEWER_ID_RE = /^[A-Za-z0-9._@-]+$/;
390
- const CONDITION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
391
-
392
- /** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
393
- * Order here is the order reviewGrantCommentBody() writes them in. */
394
- const REVIEW_RECORD_FIELDS = Object.freeze([
395
- { key: 'v', required: true, values: [REVIEW_RECORD_VERSION] },
396
- { key: 'role', required: true, values: [REVIEWER_ROLE] },
397
- { key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
398
- { key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
399
- { key: 'verdict', required: true, values: ['approve', 'reject'] },
400
- { key: 'checklist', required: true, values: ['pass', 'fail'] },
401
- { key: 'checklist-items', required: false, re: /^\d+\/\d+$/, hint: 'N/M, e.g. 7/7' },
402
- { key: 'escalation', required: true, re: CONDITION_ID_RE, hint: 'a condition id, lowercase-hyphenated' },
403
- { key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
404
- { key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
405
- { key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
406
- ]);
440
+ /** Every key a v1 record may carry, and what each accepts (codec/grants.js). */
441
+ const REVIEW_RECORD_FIELDS = codec.REVIEW_RECORD_FIELDS;
407
442
  const REVIEW_RECORD_KEYS = new Set(REVIEW_RECORD_FIELDS.map((f) => f.key));
408
443
 
409
444
  /**
@@ -448,6 +483,37 @@ function validateReviewRecord(rec, marker) {
448
483
  return { valid, passing, problems };
449
484
  }
450
485
 
486
+ /** #457 — the checklist the migration-review skill walks has this many items, so a record's
487
+ * `checklist-items` is `<passed>/10`. Kept in step with skills/migration-review/SKILL.md (a test
488
+ * reads the skill and pins it). */
489
+ const REVIEW_CHECKLIST_ITEMS = 10;
490
+
491
+ /**
492
+ * #457 — record checks that apply only when a grant is MINTED, never when one is read. They are
493
+ * kept out of validateReviewRecord on purpose: that function is also ship's read path, and a
494
+ * grant recorded under an older, shorter checklist must not change meaning after the fact (ship
495
+ * re-verifies everything that matters — HEAD and the live round-trip — on its own). A new record,
496
+ * though, must be counted against the checklist that exists today:
497
+ * - `checklist-items`, when given, has denominator REVIEW_CHECKLIST_ITEMS;
498
+ * - `checklist: pass` with `checklist-items` N/M needs N = M — a pass with an item failing is a
499
+ * contradiction, the same way a grant carrying a failing review is.
500
+ * Returns a list of problems ([] = fine).
501
+ */
502
+ function mintRecordProblems(rec) {
503
+ const r = rec || {};
504
+ const problems = [];
505
+ const items = r['checklist-items'];
506
+ if (items === undefined || items === null || !/^\d+\/\d+$/.test(String(items))) return problems;
507
+ const [a, b] = String(items).split('/').map(Number);
508
+ if (b !== REVIEW_CHECKLIST_ITEMS) {
509
+ problems.push(`"checklist-items" is ${items} — the migration-review checklist has ${REVIEW_CHECKLIST_ITEMS} items, so the record is <passed>/${REVIEW_CHECKLIST_ITEMS}`);
510
+ }
511
+ if (r.checklist === 'pass' && a !== b) {
512
+ problems.push(`"checklist" is pass but "checklist-items" is ${items} — a pass means every item passed`);
513
+ }
514
+ return problems;
515
+ }
516
+
451
517
  /** Why a VALID record is not passing, as one line — or '' when it passes. */
452
518
  function reviewRecordFailure(rec) {
453
519
  const why = [];
@@ -464,48 +530,25 @@ function reviewRecordFailure(rec) {
464
530
  * caller (tools/colab) validates it with validateReviewRecord BEFORE calling this.
465
531
  */
466
532
  function reviewGrantCommentBody(branch, host, iso, rec) {
467
- const head = `${REVIEW_GRANT_MARK} — role \`${rec.role}\` · reviewer \`${rec.reviewer}\` · branch \`${branch}\``
468
- + ` · head \`${rec.head}\` · host \`${host}\` · ${iso}`
469
- + ' — bound to this HEAD: any new commit voids it; expires when this issue closes.';
470
- const lines = [];
471
- for (const f of REVIEW_RECORD_FIELDS) {
472
- const v = rec[f.key];
473
- if (v === undefined || v === null || String(v) === '') continue;
474
- lines.push(`${f.key}: ${v}`);
475
- }
476
- return `${head}\n\n\`\`\`${REVIEW_RECORD_FENCE}\n${lines.join('\n')}\n\`\`\``;
533
+ // Only the v1 fields are written — an unknown key on `rec` never reaches the comment.
534
+ const record = {};
535
+ for (const f of REVIEW_RECORD_FIELDS) if (Object.prototype.hasOwnProperty.call(rec, f.key)) record[f.key] = rec[f.key];
536
+ return codec.encodeReviewGrant({ role: rec.role, reviewer: rec.reviewer, branch, head: rec.head, host, at: iso, record });
477
537
  }
478
538
 
479
539
  /**
480
540
  * Parse a reviewer-grant comment body → { marker, record, problems } or null when the first line
481
- * is not a reviewer-grant marker at all. The record is the FIRST fenced block whose info string is
482
- * exactly `migration-review`; text outside it is ignored. A marker with no such block, or a block
483
- * with a malformed line, returns problems — never a record silently missing fields.
541
+ * is not a reviewer-grant marker at all. The codec (`decodeReviewGrant`) reads the syntax; this adds
542
+ * validateReviewRecord's findings. A marker with no record block, or a block with a malformed line,
543
+ * returns problems — never a record silently missing fields.
484
544
  */
485
545
  function parseReviewGrant(body) {
486
- const text = String(body || '').replace(/\r\n/g, '\n').trim();
487
- const m = text.match(REVIEW_GRANT_RE);
488
- if (!m) return null;
489
- const marker = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6] };
490
- const problems = [];
491
- const fence = new RegExp('^```' + REVIEW_RECORD_FENCE + '[ \\t]*\\n([\\s\\S]*?)^```[ \\t]*$', 'm');
492
- const fm = text.match(fence);
493
- if (!fm) {
494
- problems.push(`no \`\`\`${REVIEW_RECORD_FENCE} block — a reviewer grant without its review record is not a grant`);
495
- return { marker, record: null, problems };
496
- }
497
- const record = {};
498
- for (const raw of fm[1].split('\n')) {
499
- const line = raw.trim();
500
- if (line === '') continue;
501
- const kv = line.match(/^([a-z][a-z-]*):\s*(.*)$/);
502
- if (!kv) { problems.push(`record line ${JSON.stringify(line)} is not "key: value"`); continue; }
503
- if (Object.prototype.hasOwnProperty.call(record, kv[1])) { problems.push(`"${kv[1]}" appears twice`); continue; }
504
- record[kv[1]] = kv[2].trim();
505
- }
506
- const v = validateReviewRecord(record, marker);
507
- problems.push(...v.problems);
508
- return { marker, record, problems };
546
+ const d = codec.decodeReviewGrant(body);
547
+ if (!d) return null;
548
+ const marker = { role: d.role, reviewer: d.reviewer, branch: d.branch, head: d.head, host: d.host, at: d.at };
549
+ if (!d.record) return { marker, record: null, problems: d.problems };
550
+ const v = validateReviewRecord(d.record, marker);
551
+ return { marker, record: d.record, problems: [...d.problems, ...v.problems] };
509
552
  }
510
553
 
511
554
  /**
@@ -546,22 +589,76 @@ function liveGrantRecords(comments) {
546
589
  }
547
590
 
548
591
  /**
549
- * HEAD binding. A human grant is branch-bound, not HEAD-bound (unchanged since #98) → unbound, ok.
550
- * A reviewer grant covers exactly the commit it reviewed: ok only when `branchHeadSha` is a full
551
- * 40-hex sha equal (case-insensitively) to the grant's head. A short or missing sha is NOT ok —
552
- * "could not confirm the HEAD" is never read as "the HEAD matches", and never a prefix match.
592
+ * #508 — the CONTENT ID of a branch's migration files: what a reviewer actually reviewed. Pure:
593
+ * `entries` is `[{ path, blob }]`, one per migration path the branch changes against its base
594
+ * (tools/colab newMigrations — the same rule the gate fires on), `blob` the git blob id of that
595
+ * path at the head, or null when the head deletes it. The id is a sha256 over the SORTED
596
+ * `path<TAB>blob` lines, so it is independent of listing order and of everything outside those
597
+ * files: a merge-of-trunk sync, or any commit that leaves every migration byte-identical, keeps
598
+ * it; editing, adding, removing or renaming a migration changes it. Returns null for an empty or
599
+ * unreadable set — there is nothing to bind, and null never equals a recorded id.
600
+ */
601
+ function migrationContentId(entries) {
602
+ if (!Array.isArray(entries) || entries.length === 0) return null;
603
+ const lines = [];
604
+ for (const e of entries) {
605
+ if (!e || typeof e.path !== 'string' || e.path === '') return null;
606
+ const blob = e.blob == null ? '-' : String(e.blob).toLowerCase();
607
+ if (blob !== '-' && !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(blob)) return null;
608
+ lines.push(`${e.path}\t${blob}\n`);
609
+ }
610
+ lines.sort();
611
+ return crypto.createHash('sha256').update(lines.join('')).digest('hex');
612
+ }
613
+
614
+ /**
615
+ * #508 — `git ls-tree -z <sha> -- <paths…>` output → migrationContentId's entries, one per path in
616
+ * `paths` (a path the tree lacks is a deletion: blob null). Pure, so the parse is testable without
617
+ * the CLI; tools/colab migrationContentAt runs the git half.
618
+ */
619
+ function migrationEntriesFromLsTree(stdout, paths) {
620
+ const blobs = new Map();
621
+ for (const rec of String(stdout || '').split('\0')) {
622
+ const m = rec.match(/^\d+ blob ([0-9a-f]+)\t([\s\S]+)$/);
623
+ if (m) blobs.set(m[2], m[1]);
624
+ }
625
+ return (paths || []).map((p) => ({ path: p, blob: blobs.get(p) || null }));
626
+ }
627
+
628
+ const SHA256_RE = /^[0-9a-f]{64}$/;
629
+
630
+ /**
631
+ * The binding of a grant to what the branch now is. A human grant is branch-bound, not HEAD-bound
632
+ * (unchanged since #98) → unbound, ok. A reviewer grant needs `branchHeadSha` to be a full 40-hex
633
+ * sha (R reads CI there; "could not confirm the HEAD" is never read as a match, never a prefix
634
+ * match), and then binds one of two ways:
635
+ * - its record names `migrations` (#508) → CONTENT-bound: ok when the head IS the reviewed head,
636
+ * or when `contentId` — migrationContentId at the head — equals the recorded id. A sync that
637
+ * only merges trunk in keeps the grant; any change to a migration file voids it.
638
+ * - no `migrations` (a record minted before #508) → HEAD-bound, exactly as before: only the
639
+ * reviewed commit itself.
640
+ * Returns { bound, ok, via: 'head' | 'content' | null, reason }.
553
641
  */
554
- function grantHeadBinding(grant, branchHeadSha) {
555
- if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, reason: '' };
642
+ function grantHeadBinding(grant, branchHeadSha, contentId) {
643
+ if (!grant || grant.role === 'human' || grant.role === undefined) return { bound: false, ok: true, via: null, reason: '' };
556
644
  const want = String(grant.head || '').toLowerCase();
557
645
  const have = String(branchHeadSha || '').toLowerCase();
558
646
  if (!SHA40_RE.test(have)) {
559
- return { bound: true, ok: false, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is bound to one commit` };
647
+ return { bound: true, ok: false, via: null, reason: `cannot confirm the branch HEAD (${have ? `"${have}" is not a full sha` : 'no sha given'}) — a reviewer grant is judged at one commit` };
648
+ }
649
+ if (want === have) return { bound: true, ok: true, via: 'head', reason: '' };
650
+ const recorded = grant.record && grant.record.migrations ? String(grant.record.migrations).toLowerCase() : '';
651
+ if (!recorded) {
652
+ return { bound: true, ok: false, via: null, reason: `reviewer grant is bound to ${want.slice(0, 7)}, branch is at ${have.slice(0, 7)} — a new commit voids it (the record names no migration content id, so it binds the HEAD alone)` };
653
+ }
654
+ const now = String(contentId || '').toLowerCase();
655
+ if (!SHA256_RE.test(now)) {
656
+ return { bound: true, ok: false, via: null, reason: `reviewer grant covers migration content ${recorded.slice(0, 12)}, and the content at ${have.slice(0, 7)} could not be read — an unread id is never a match` };
560
657
  }
561
- if (want !== have) {
562
- return { bound: true, ok: false, reason: `reviewer grant is bound to ${want.slice(0, 7)}, branch is at ${have.slice(0, 7)} — a new commit voids it` };
658
+ if (now !== recorded) {
659
+ return { bound: true, ok: false, via: null, reason: `reviewer grant covers migration content ${recorded.slice(0, 12)} (reviewed at ${want.slice(0, 7)}), the branch at ${have.slice(0, 7)} carries ${now.slice(0, 12)} — a migration file changed since the review, which voids it` };
563
660
  }
564
- return { bound: true, ok: true, reason: '' };
661
+ return { bound: true, ok: true, via: 'content', reason: '' };
565
662
  }
566
663
 
567
664
  /** `migration-grant:` values, in project.yml (#398). Absent = human, today's behaviour. */
@@ -590,7 +687,8 @@ function parseGrantPolicy(doc) {
590
687
 
591
688
  /**
592
689
  * The reviewer-grant verdict for one issue — P, M and HEAD of the ship rule; evaluateShipSet()
593
- * (#401) calls it and adds R. `ctx` = { branch, headSha, issueNum, labelName, policy } where
690
+ * (#401) calls it and adds R. `ctx` = { branch, headSha, contentId, issueNum, labelName, policy } where
691
+ * `contentId` (#508) is migrationContentId at `headSha` (grantHeadBinding), and
594
692
  * `policy` is parseGrantPolicy(...).policy. Checks, cheapest/most-fundamental first, each with its
595
693
  * own reason: read failed · not open · no label · policy not `reviewer` · no live reviewer grant ·
596
694
  * branch mismatch · untrusted author · record invalid · record not passing · HEAD binding.
@@ -618,10 +716,10 @@ function evaluateReviewerGrant(record, ctx) {
618
716
  if (!g.valid) return no(`#${issue}'s reviewer grant has an invalid review record: ${(g.problems || []).join('; ') || 'unreadable'}`, g);
619
717
  if (!g.passing) return no(`#${issue}'s review record does not pass: ${reviewRecordFailure(g.record)}`, g);
620
718
  checks.marker = true;
621
- const hb = grantHeadBinding(g, c.headSha);
719
+ const hb = grantHeadBinding(g, c.headSha, c.contentId);
622
720
  if (!hb.ok) return no(`#${issue}: ${hb.reason}`, g);
623
721
  checks.head = true;
624
- return { issue, ok: true, grant: g, reason: '', checks };
722
+ return { issue, ok: true, grant: g, via: hb.via, reason: '', checks };
625
723
  }
626
724
 
627
725
  module.exports = {
@@ -634,8 +732,12 @@ module.exports = {
634
732
  REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS,
635
733
  validateReviewRecord, reviewRecordFailure, reviewGrantCommentBody, parseReviewGrant,
636
734
  liveGrantRecords, grantHeadBinding, evaluateReviewerGrant,
735
+ // #508 — bind to the reviewed migration content, not the HEAD
736
+ migrationContentId, migrationEntriesFromLsTree,
637
737
  // #398 — repo policy
638
738
  GRANT_POLICIES, parseGrantPolicy,
639
739
  // #401 — ship honours a reviewer grant
640
740
  ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
741
+ // #457 — the mint-time checks
742
+ REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
641
743
  };
@@ -592,7 +592,7 @@ function ownsHold(rec, session) {
592
592
  * (#317.)
593
593
  *
594
594
  * WHY THIS EXISTS. A ship session recovered an issue with a no-worktree claim, which minted a
595
- * checkout hold under the identity string `coding-dashboard-1545`. It then shipped, and every later
595
+ * checkout hold under the identity string `example-orchestrator-1545`. It then shipped, and every later
596
596
  * squash-merge was refused by ITS OWN hold: the identity `colab ship` resolves comes from the
597
597
  * worktree record or a branch-keyed claim, and a no-worktree claim carries `branch: null`, so the
598
598
  * session presented a blank one. `ownsHold` is exact string equality and blank never matches, so a
@@ -663,7 +663,7 @@ function ownsPlace(rec, session, anchorOpts = {}) {
663
663
  * no two consumers disagree (#317). Returns `{cls, rec, live, reason, remedy, conflict}`.
664
664
  *
665
665
  * The live specimen this closes was not a wrong answer; it was an UNCLASSIFIED one. `colab ship`
666
- * printed `place "…" is held by session "coding-dashboard-1545"` and stopped — true, and useless:
666
+ * printed `place "…" is held by session "example-orchestrator-1545"` and stopped — true, and useless:
667
667
  * the reader could not tell from it whether the holder was itself, a corpse, or a live sibling, and
668
668
  * those three need three different next moves. The refusal now names the class and the exact next
669
669
  * command, and two of the six classes are not refusals at all.