@futurelastic/colab-handbook 1.20.2-rc.2 → 1.20.2-rc.3

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
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.20.2-rc.2"
36
+ "version": "1.20.2-rc.3"
37
37
  }
package/tools/colab CHANGED
@@ -11119,7 +11119,11 @@ Sequence (each step gated; any failure aborts before the push — the target is
11119
11119
  head (workflows that cannot fire for a branch ref) → nothing to be stale
11120
11120
  (an integration line with NO runs at all borrows trunk's verdict, advisory —
11121
11121
  an ungated line is a normal early state; a RED line still blocks; the cure
11122
- rule and ci-grant both cover trunk only, never a line)
11122
+ rule and ci-grant both cover trunk only, never a line) · no carried issue
11123
+ (closing or --refs) with an OPEN needs-decision (#695), read at ship time
11124
+ through the same pair rule as \`colab decision\` — clears with \`colab decision
11125
+ <N> --record\`; a person may pass it at the human door only WITH --answered-by
11126
+ <name>, and the 🚢/✅ comment names them (a --batch member never passes it)
11123
11127
  b4. core-path review (#350) the TARGET's CODEOWNERS (.github/, root, docs/) ∩ the branch's changed
11124
11128
  paths. Inert when there is no CODEOWNERS or it names only the author's forge
11125
11129
  login. Otherwise a core-touching branch is pushed, a PR is opened (or the open
@@ -11902,6 +11906,32 @@ function resolveCloseRefsSplit(repoAbs, gh, issues, refsFromFlag, declaredHolds
11902
11906
  return { closeIssues, refsIssues, refsSet, gateFindings, brakeFindings };
11903
11907
  }
11904
11908
 
11909
+ /**
11910
+ * #695: the open-question row, read AT SHIP TIME over every issue the ship carries (closing and
11911
+ * --refs alike — a kept-open issue's decision is taken by the merge just the same). `needs-decision`
11912
+ * is resolved through decisionPairFor, the reader `colab decision --record/--list` use, so ship and
11913
+ * the decision inbox agree on whether the question is open; the label timeline is read only for an
11914
+ * issue carrying the both-labels pair. `gh` unusable → no row (nothing can be read, and the CI row
11915
+ * already refuses without gh); one issue unreadable → the row fails closed, self-clearing.
11916
+ * `door` / `answeredBy`: the human door and its name (decisionRecord.shipDecisionRow).
11917
+ */
11918
+ function shipDecisionCheck(repoAbs, gh, issues, door = null, answeredBy = null) {
11919
+ if (!gh || !issues.length) return null;
11920
+ const trust = decisionTrust(repoAbs);
11921
+ const findings = [];
11922
+ const unread = [];
11923
+ for (const num of issues) {
11924
+ const info = git.ghIssueView(repoAbs, num, ['url', 'labels', 'comments']);
11925
+ if (!info) { unread.push(num); continue; }
11926
+ const names = (info.labels || []).map((l) => (l && typeof l === 'object' ? l.name : l));
11927
+ if (!names.includes(labels.NEEDS_DECISION_LABEL)) continue; // the ordinary case: one read, no events
11928
+ const pair = decisionPairFor(repoAbs, num, { labels: info.labels || [], comments: info.comments || [] }, trust);
11929
+ const f = decisionRecord.shipOpenQuestion({ issue: num, url: info.url, labels: info.labels, pair });
11930
+ if (f) findings.push(f);
11931
+ }
11932
+ return decisionRecord.shipDecisionRow({ findings, unread, door, answeredBy });
11933
+ }
11934
+
11905
11935
  /** `holds:` from a parsed descriptor, as a list of label names — anything malformed reads as none. */
11906
11936
  function descriptorHolds(doc) {
11907
11937
  const h = doc && doc.holds;
@@ -13195,6 +13225,16 @@ function cmdShipDryJson(opts) {
13195
13225
  : `${checklistFindings.map((f) => `#${f.issue} (${f.unchecked}/${f.total} unticked)`).join(', ')} — ` +
13196
13226
  'tick what shipped, file `Remainder: #M` for the rest, or pass --refs to keep it open deliberately' });
13197
13227
 
13228
+ // #695: an open needs-decision on any carried issue refuses — the same producer as the prose and
13229
+ // --direct paths. A batch member passes no human door: the batch has no per-member 🚢 clause to
13230
+ // name the person on, so such a member lands serially through the door instead.
13231
+ const decisionJson = shipDecisionCheck(repoAbs, gh, sess.issues,
13232
+ opts._batchMember ? null : humanDoor.humanDoorFromProcess(process, opts.answeredBy), opts.answeredBy);
13233
+ if (decisionJson) {
13234
+ checks.push({ name: decisionRecord.SHIP_DECISION_ROW, ok: decisionJson.ok, class: decisionJson.class, detail: decisionJson.detail,
13235
+ ...(decisionJson.findings.length ? { questions: decisionJson.findings.map((f) => ({ issue: f.issue, url: f.url, verdict: f.verdict, clear: f.clear })) } : {}) });
13236
+ }
13237
+
13198
13238
  const migGate = shipMigrationGate(repoAbs, gh, target, sess.branch, sess.issues);
13199
13239
  const migOk = migGate.ok;
13200
13240
  migrationGrantPayload = migGate.payload;
@@ -13577,7 +13617,7 @@ function shipEvidenceClose({ repoAbs, st, sess, target, trunk, gh, closeIssues,
13577
13617
  `The deliverable is recorded on this issue (see the comment(s) above), which is what authorised ` +
13578
13618
  `the close — colab closes a zero-diff issue only when it already carries a comment colab did not ` +
13579
13619
  `write. The zero-diff fact was measured from git: ${mode.why}.${shipSess}`;
13580
- const c = git.ghIssueComment(repoAbs, num, body + (opts.humanDoorEvidence || '')); // #525
13620
+ const c = git.ghIssueComment(repoAbs, num, body + (opts.humanDoorEvidence || '') + (opts.decisionDoorEvidence || '')); // #525, #695
13581
13621
  if (!c.ok) warn(`could not post the evidence-close comment on #${num} — closing anyway`);
13582
13622
  const r = tracker.forRepo(repoAbs).issueClose(num, { reason: 'completed' });
13583
13623
  if (!r.ok) { skipped.push({ num, why: `gh issue close failed: ${(r.stderr || '').split('\n')[0]}` }); continue; }
@@ -13780,6 +13820,13 @@ function cmdShipDirect(opts) {
13780
13820
  ? 'no unticked Plan checklist item(s) without a declared remainder'
13781
13821
  : `${checklistFindings.map((f) => `#${f.issue} (${f.unchecked}/${f.total} unticked)`).join(', ')} — no declared remainder` });
13782
13822
 
13823
+ // #695: an open needs-decision on any claimed issue refuses the close — same producer as a branch ship.
13824
+ const decisionDirect = shipDecisionCheck(repoAbs, gh, issues, humanDoor.humanDoorFromProcess(process, opts.answeredBy), opts.answeredBy);
13825
+ if (decisionDirect) {
13826
+ checks.push({ name: decisionRecord.SHIP_DECISION_ROW, ok: decisionDirect.ok, class: decisionDirect.class, detail: decisionDirect.detail });
13827
+ opts.decisionDoorEvidence = decisionRecord.shipDecisionEvidence(decisionDirect);
13828
+ }
13829
+
13783
13830
  // ---- the work is committed on trunk … ----
13784
13831
  const headBranch = git.git(['rev-parse', '--abbrev-ref', 'HEAD'], repoAbs).stdout;
13785
13832
  const onTrunk = headBranch === trunk;
@@ -14458,6 +14505,15 @@ function cmdShip(argv) {
14458
14505
  ? 'no unticked Plan checklist item(s) without a declared remainder'
14459
14506
  : `${gateFindings.map((f) => `#${f.issue} (${f.unchecked}/${f.total} unticked)`).join(', ')} — no declared remainder`]);
14460
14507
 
14508
+ // #695: an open needs-decision on any carried issue refuses before the push — the same producer as
14509
+ // --dry --json, read now, whatever the coordinator read earlier in its pass.
14510
+ const decisionResult = shipDecisionCheck(repoAbs, gh, sess.issues, humanDoor.humanDoorFromProcess(process, opts.answeredBy), opts.answeredBy);
14511
+ const decisionOk = !decisionResult || decisionResult.ok;
14512
+ if (decisionResult) {
14513
+ checks.push([decisionOk ? '✓' : '✗', decisionRecord.SHIP_DECISION_ROW, decisionResult.detail]);
14514
+ opts.decisionDoorEvidence = decisionRecord.shipDecisionEvidence(decisionResult);
14515
+ }
14516
+
14461
14517
  // ---- B1b's cross-check, run by the tool rather than by the reader (#87) ----
14462
14518
  // The claim registry is read AT SHIP TIME, so a claim a co-tenant session wrote onto this branch
14463
14519
  // minutes ago is indistinguishable from one this session made. Ask git whether the branch
@@ -14540,7 +14596,7 @@ function cmdShip(argv) {
14540
14596
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
14541
14597
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
14542
14598
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
14543
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && headCiOk && coreOk && recOk && heavyOk;
14599
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && decisionOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && headCiOk && coreOk && recOk && heavyOk;
14544
14600
 
14545
14601
  // ---- report the table ----
14546
14602
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -15368,7 +15424,7 @@ function cmdShip(argv) {
15368
15424
  // same block, and re-assigning the collector here would silently discard them.
15369
15425
  shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
15370
15426
  skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
15371
- evidenceExtra: (opts.humanDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606
15427
+ evidenceExtra: (opts.humanDoorEvidence || '') + (opts.decisionDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606, #695
15372
15428
 
15373
15429
  print('');
15374
15430
  print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
@@ -341,7 +341,73 @@ function openAsks(comments) {
341
341
  .map(({ id, version, at, ns }) => ({ id, version, at, ns }));
342
342
  }
343
343
 
344
+ /**
345
+ * #695: the ship door's read of one carried issue. Measured: on an `auto-trunk` repo a reviewer
346
+ * escalated an issue to its owner, `colab decision --reopen` put `needs-decision` back, and 22
347
+ * minutes later `colab ship` squashed the branch onto trunk and closed the issue — no precondition
348
+ * row read the label, so the merge took a decision that was the owner's. A ship pass can run for an
349
+ * hour; a question raised mid-pass is the ordinary case, so the label is read AT SHIP TIME.
350
+ *
351
+ * Same verdict as `colab decision` (the caller passes decisionPairFor's result, so ship and
352
+ * `--list` cannot disagree): `needs-decision` absent → null; present with the pair resolving to an
353
+ * interrupted write → null (the question is answered); anything else — no record, a newer ask,
354
+ * UNDETERMINED — is an open question. Pure: `labels` + `pair` in, a finding or null out.
355
+ *
356
+ * Returns null or `{ issue, url, verdict, askAt, decidedAt, why, clear }`; `clear` is the command
357
+ * that settles it.
358
+ */
359
+ function shipOpenQuestion({ issue, url = null, labels, pair = null } = {}) {
360
+ const names = new Set((labels || []).map((l) => (l && typeof l === 'object' ? l.name : l)));
361
+ if (!names.has('needs-decision')) return null;
362
+ if (pair && pair.verdict === PAIR_VERDICTS.INTERRUPTED_WRITE) return null;
363
+ const clear = `colab decision ${issue} --record --ruled-by "<name>"${pair ? ' --answers <ask id>' : ''}`;
364
+ return {
365
+ issue, url: url || null,
366
+ verdict: pair ? pair.verdict : PAIR_VERDICTS.OPEN_QUESTION,
367
+ askAt: pair ? pair.askAt : null, decidedAt: pair ? pair.decidedAt : null,
368
+ why: pair ? pair.why : 'needs-decision is applied and no ⚖ decision is recorded',
369
+ clear,
370
+ };
371
+ }
372
+
373
+ const SHIP_DECISION_ROW = 'no open decision on carried issues (#695)';
374
+
375
+ /**
376
+ * #695: the precondition row from the per-issue findings. `unread` lists issues whose labels could
377
+ * not be read — fail closed, self-clearing (the read, not the issue, failed). `door` is the human
378
+ * door verdict (lib/ship-human-door.js) and `answeredBy` the name given with it: an open question
379
+ * passes ONLY through an open door WITH a name, so the person who took the decision is on the
380
+ * record (ruling on #695: the issue's stated default). A batch member passes no door (`door` null).
381
+ *
382
+ * Returns `{ ok, class: null|'human-gated'|'self-clearing', detail, passedBy, findings, unread }`;
383
+ * `passedBy` is the name when the door carried an open question through, else null.
384
+ */
385
+ function shipDecisionRow({ findings = [], unread = [], door = null, answeredBy = null } = {}) {
386
+ const where = (f) => (f.url ? `#${f.issue} (${f.url})` : `#${f.issue}`);
387
+ if (findings.length && door && door.open && answeredBy) {
388
+ return { ok: true, class: null, passedBy: answeredBy, findings, unread,
389
+ detail: `open question on ${findings.map(where).join(', ')} — passed by the human door: ${answeredBy} takes this decision, named on the 🚢 record` };
390
+ }
391
+ if (findings.length) {
392
+ const rows = findings.map((f) => `${where(f)}: ${f.why} — clears with \`${f.clear}\``).join('; ');
393
+ return { ok: false, class: 'human-gated', passedBy: null, findings, unread,
394
+ detail: `${rows}. The question is the owner's: this ship would take it. A person may take it at the human door with --answered-by "<name>"` };
395
+ }
396
+ if (unread.length) {
397
+ return { ok: false, class: 'self-clearing', passedBy: null, findings, unread,
398
+ detail: `could not read ${unread.map((n) => '#' + n).join(' ')} from the tracker — an open needs-decision cannot be ruled out; re-run` };
399
+ }
400
+ return { ok: true, class: null, passedBy: null, findings, unread, detail: 'no carried issue has an open needs-decision' };
401
+ }
402
+
403
+ /** #695: the clause the 🚢 / ✅ evidence comment carries when the human door passed an open question. */
404
+ function shipDecisionEvidence(row) {
405
+ if (!row || !row.passedBy) return '';
406
+ return ` · open needs-decision on ${row.findings.map((f) => '#' + f.issue).join(' ')} passed by the human door (#695): decided by ${row.passedBy}`;
407
+ }
408
+
344
409
  module.exports = {
410
+ shipOpenQuestion, SHIP_DECISION_ROW, shipDecisionRow, shipDecisionEvidence,
345
411
  DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
346
412
  decisionCommentBody, reopenCommentBody,
347
413
  liveDecisions, TRUSTED_ASSOCIATIONS, trustedDecisions,