@futurelastic/colab-handbook 1.12.0-rc.26 → 1.12.0-rc.28

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/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.26"
30
+ "version": "1.12.0-rc.28"
31
31
  }
package/tools/colab CHANGED
@@ -3660,7 +3660,13 @@ It is minted only when ALL of these hold, checked before any network call:
3660
3660
  - the record is well-formed AND passing (approve · checklist pass · escalation clear · CI pass) —
3661
3661
  a grant carrying a failing review is a contradiction, so it is refused, not recorded;
3662
3662
  - the branch is pushed, and --head (if given) equals origin's tip — the grant binds that tip;
3663
- - this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human).
3663
+ - this checkout's project.yml declares \`migration-grant: reviewer\` (#398; absent = human);
3664
+ - checklist-items, when given, is <passed>/${migrationGrant.REVIEW_CHECKLIST_ITEMS} and, with checklist pass, every item
3665
+ passed (#457) — the record counts against the checklist the migration-review skill walks today.
3666
+ Then, read from CI after the tracker read and before anything is written (#457):
3667
+ - ci-roundtrip pass is TRUE at the head: the "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job ran and
3668
+ passed there (the rule ship applies), and --ci-run, when given, is one of the runs at that
3669
+ head and carries the job. A repo whose CI has no such job cannot mint a reviewer grant at all.
3664
3670
  COLAB_HUMAN=1 is still required for every role. The reviewer identity is DECLARED, not attested.
3665
3671
  \`colab ship\` honours a reviewer grant only when ALL of (#401): P the target's project.yml says
3666
3672
  \`migration-grant: reviewer\` · M this record is live, trusted and passing · HEAD its head is the
@@ -3796,9 +3802,36 @@ function migrationGrantReviewRecord(repoAbs, opts) {
3796
3802
  if (!v.passing) {
3797
3803
  throw new UserError(`the review does not pass (${migrationGrant.reviewRecordFailure(rec)}) — a grant carrying a failing review is a contradiction; nothing was posted`);
3798
3804
  }
3805
+ // #457: checks only a NEW record faces (the checklist denominator) — local, so before the gh gate.
3806
+ const mintProblems = migrationGrant.mintRecordProblems(rec);
3807
+ if (mintProblems.length) throw new UserError(`the review record is invalid: ${mintProblems.join('; ')}`);
3799
3808
  return rec;
3800
3809
  }
3801
3810
 
3811
+ /**
3812
+ * #457: the record says `ci-roundtrip: pass` — read CI at its head and refuse unless the round-trip
3813
+ * job is really there and passed (tools/lib/migration-grant.js mintRoundtripCheck: the same
3814
+ * roundtripVerdict `colab ship` applies, plus the cited `ci-run` must carry the job). Needs gh, so
3815
+ * it runs in cmdMigrationGrantCreate after the tracker read and BEFORE the label is applied —
3816
+ * nothing is written when it refuses. The workflows guard diffs trunk against the reviewed head;
3817
+ * an unreadable diff counts as touched, failing closed exactly as shipMigrationCtx does.
3818
+ */
3819
+ function migrationGrantRoundtripCheck(repoAbs, branch, rec) {
3820
+ if (rec['ci-roundtrip'] !== 'pass') return;
3821
+ const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
3822
+ const remote = git.remoteInfo(repoAbs).name || 'origin';
3823
+ let d = trunk ? git.git(['diff', '--name-only', `${remote}/${trunk}...${rec.head}`], repoAbs) : { ok: false };
3824
+ if (!d.ok && trunk) d = git.git(['diff', '--name-only', `${trunk}...${rec.head}`], repoAbs);
3825
+ const workflowsTouched = !d.ok || d.stdout.split('\n').some((f) => f.startsWith('.github/workflows/'));
3826
+ let runs = null;
3827
+ const list = git.ghRunsForCommit(repoAbs, branch, rec.head, 20);
3828
+ if (Array.isArray(list)) {
3829
+ runs = list.map((r) => ({ databaseId: r.databaseId, workflowName: r.workflowName || null, jobs: git.ghRunJobs(repoAbs, r.databaseId) }));
3830
+ }
3831
+ const c = migrationGrant.mintRoundtripCheck(rec, runs, { workflowsTouched });
3832
+ if (!c.ok) throw new UserError(`${c.reason}; nothing was posted`);
3833
+ }
3834
+
3802
3835
  function cmdMigrationGrantCreate(repoAbs, num, opts) {
3803
3836
  // --branch and branch existence are already validated by cmdMigrationGrant, ahead of the
3804
3837
  // isGhUsable gate — see the comment there. Kept as a defensive re-check in case this function is
@@ -3822,6 +3855,9 @@ function cmdMigrationGrantCreate(repoAbs, num, opts) {
3822
3855
  || `this repo has no \`${labels.MIGRATION_GRANT_LABEL}\` label`);
3823
3856
  }
3824
3857
 
3858
+ // #457: a record claiming a CI round-trip pass is checked against CI BEFORE anything is written.
3859
+ if (opts.reviewRecord) migrationGrantRoundtripCheck(repoAbs, opts.branch, opts.reviewRecord);
3860
+
3825
3861
  const editR = git.ghIssueEdit(repoAbs, num, labels.migrationGrantLabelArgs({}));
3826
3862
  if (!editR.ok) throw new UserError(`gh edit #${num} failed (${editR.stderr.split('\n')[0] || editR.code})`);
3827
3863
 
@@ -345,6 +345,61 @@ function roundtripVerdict(jobs, opts) {
345
345
  return { ok: true, legs, reason: '' };
346
346
  }
347
347
 
348
+ /**
349
+ * #457 — the MINT-time half of R. `colab ship` re-reads the round-trip at the head (roundtripVerdict
350
+ * above, through shipMigrationCtx), so a false `ci-roundtrip: pass` never opened the gate — but the
351
+ * grant record itself could still assert a fact its cited run does not contain, and the issue then
352
+ * sat looking "granted" until a ship pass measured it. This applies the same verdict when the record
353
+ * is WRITTEN, so a record that says `pass` is refused unless CI agrees at `rec.head`.
354
+ *
355
+ * Pure: `runs` is every run at the head — `[{ databaseId, workflowName, jobs }]`, `jobs` being
356
+ * git.ghRunJobs rows — or null when the run list could not be read (a run with `jobs: null` is an
357
+ * unread run). Checks, in order:
358
+ * - the run list and every run's jobs were read (an unread result is never a pass);
359
+ * - roundtripVerdict over all their jobs is ok — the exact rule ship applies, workflows guard
360
+ * included, so a record mint can never accept what ship would refuse;
361
+ * - `ci-run`, when given, resolves to a run id (bare digits, or a `/runs/<id>` URL), names one of
362
+ * those runs, and that run itself carries a round-trip job — a record must not cite a run that
363
+ * does not contain the evidence it is cited for, even when a sibling run does.
364
+ * A record whose `ci-roundtrip` is not `pass` is not this function's to judge (it never mints).
365
+ * Returns { ok, reason, verdict }.
366
+ */
367
+ function mintRoundtripCheck(rec, runs, opts) {
368
+ const o = opts || {};
369
+ const r = rec || {};
370
+ if (r['ci-roundtrip'] !== 'pass') return { ok: true, reason: '', verdict: null };
371
+ const sha = r.head ? String(r.head).slice(0, 7) : 'the head';
372
+ const no = (reason, verdict = null) => ({ ok: false, reason, verdict });
373
+ let jobs = null;
374
+ if (Array.isArray(runs) && runs.every((x) => x && Array.isArray(x.jobs))) {
375
+ jobs = [];
376
+ for (const x of runs) for (const j of x.jobs) jobs.push({ ...j, workflowName: x.workflowName || null });
377
+ }
378
+ const verdict = roundtripVerdict(jobs, { headSha: r.head, workflowsTouched: !!o.workflowsTouched });
379
+ if (!verdict.ok) {
380
+ 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` : '';
381
+ return no(`the record says ci-roundtrip: pass, but ${verdict.reason}${hint}`, verdict);
382
+ }
383
+ if (r['ci-run'] !== undefined && r['ci-run'] !== null && String(r['ci-run']) !== '') {
384
+ const id = parseRunId(r['ci-run']);
385
+ 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);
386
+ const cited = runs.find((x) => String(x.databaseId) === id);
387
+ 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);
388
+ if (!cited.jobs.some((j) => j && typeof j.name === 'string' && j.name.startsWith(ROUNDTRIP_JOB_PREFIX))) {
389
+ return no(`ci-run ${id} has no "${ROUNDTRIP_JOB_PREFIX}" job — cite the run that carries the round-trip`, verdict);
390
+ }
391
+ }
392
+ return { ok: true, reason: '', verdict };
393
+ }
394
+
395
+ /** A run id from a `ci-run` value — bare digits, or the `/runs/<id>` segment of a run URL — or null. */
396
+ function parseRunId(v) {
397
+ const s = String(v).trim();
398
+ if (/^\d+$/.test(s)) return s;
399
+ const m = s.match(/\/runs\/(\d+)(?:[/?#]|$)/);
400
+ return m ? m[1] : null;
401
+ }
402
+
348
403
  /** A step that reached a terminal conclusion other than skipped/cancelled — ci-cure.js stepRan. */
349
404
  function stepRanOk(s) {
350
405
  return !!s && s.status === 'completed' && s.conclusion !== 'skipped' && s.conclusion !== 'cancelled';
@@ -448,6 +503,37 @@ function validateReviewRecord(rec, marker) {
448
503
  return { valid, passing, problems };
449
504
  }
450
505
 
506
+ /** #457 — the checklist the migration-review skill walks has this many items, so a record's
507
+ * `checklist-items` is `<passed>/10`. Kept in step with skills/migration-review/SKILL.md (a test
508
+ * reads the skill and pins it). */
509
+ const REVIEW_CHECKLIST_ITEMS = 10;
510
+
511
+ /**
512
+ * #457 — record checks that apply only when a grant is MINTED, never when one is read. They are
513
+ * kept out of validateReviewRecord on purpose: that function is also ship's read path, and a
514
+ * grant recorded under an older, shorter checklist must not change meaning after the fact (ship
515
+ * re-verifies everything that matters — HEAD and the live round-trip — on its own). A new record,
516
+ * though, must be counted against the checklist that exists today:
517
+ * - `checklist-items`, when given, has denominator REVIEW_CHECKLIST_ITEMS;
518
+ * - `checklist: pass` with `checklist-items` N/M needs N = M — a pass with an item failing is a
519
+ * contradiction, the same way a grant carrying a failing review is.
520
+ * Returns a list of problems ([] = fine).
521
+ */
522
+ function mintRecordProblems(rec) {
523
+ const r = rec || {};
524
+ const problems = [];
525
+ const items = r['checklist-items'];
526
+ if (items === undefined || items === null || !/^\d+\/\d+$/.test(String(items))) return problems;
527
+ const [a, b] = String(items).split('/').map(Number);
528
+ if (b !== REVIEW_CHECKLIST_ITEMS) {
529
+ problems.push(`"checklist-items" is ${items} — the migration-review checklist has ${REVIEW_CHECKLIST_ITEMS} items, so the record is <passed>/${REVIEW_CHECKLIST_ITEMS}`);
530
+ }
531
+ if (r.checklist === 'pass' && a !== b) {
532
+ problems.push(`"checklist" is pass but "checklist-items" is ${items} — a pass means every item passed`);
533
+ }
534
+ return problems;
535
+ }
536
+
451
537
  /** Why a VALID record is not passing, as one line — or '' when it passes. */
452
538
  function reviewRecordFailure(rec) {
453
539
  const why = [];
@@ -638,4 +724,6 @@ module.exports = {
638
724
  GRANT_POLICIES, parseGrantPolicy,
639
725
  // #401 — ship honours a reviewer grant
640
726
  ROUNDTRIP_JOB_PREFIX, roundtripVerdict, SHIP_CONDITION_TAG,
727
+ // #457 — the mint-time checks
728
+ REVIEW_CHECKLIST_ITEMS, mintRecordProblems, mintRoundtripCheck, parseRunId,
641
729
  };
@@ -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.
@@ -9,8 +9,8 @@
9
9
  * PURE BY CONSTRUCTION, the release-cut.js posture: no git, no network, no `gh`, no clock (`now` is
10
10
  * passed in). The CLI in tools/colab is the measuring half.
11
11
  *
12
- * WHERE PER-CANDIDATE STATE LIVES (the contract futurelastic/hangar#125 reads — change it and every
13
- * consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
12
+ * WHERE PER-CANDIDATE STATE LIVES (the contract a downstream dashboard's release view reads — change
13
+ * it and every consumer breaks, so it is frozen here and documented in tools/README.md, *Release finalize*):
14
14
  *
15
15
  * - the candidates are the annotated `vX.Y.Z-rc.N` tags on origin that `colab release cut` made
16
16
  * (first line of the tag message ends `(colab release cut)`); nothing else stores them;