@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.10

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 (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13790 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +259 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +521 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. package/bin/cli.js +0 -3
@@ -0,0 +1,653 @@
1
+ 'use strict';
2
+ /**
3
+ * The labels the conventions define, in one place — CONVENTIONS.md §9 (step 3) is the
4
+ * prose source; this is the machine copy the tooling reads, kept beside it the way the
5
+ * tier set lives in both the prose and the audit's VALID_TIERS.
6
+ *
7
+ * Why a single list matters here specifically: a repo that adopted at an OLDER handbook
8
+ * version — before one of these labels entered the set — silently never back-filled it,
9
+ * and the check that label powers can then never fire. The claim (`in-progress`) cannot
10
+ * land; the readiness column (`deps-checked`) can never leave "nobody looked"; provenance
11
+ * (`agent-filed`) reads every filed issue as human-approved. So adoption provisions the
12
+ * WHOLE set (not a subset marked optional), sync back-fills what a later version added,
13
+ * and the audit reports the gap — all three reading this one list, so they cannot drift
14
+ * about what "the full set" is.
15
+ *
16
+ * Each entry carries color + description so a provisioner (`gh label create`) and the
17
+ * audit's presence check share not just the names but how the label is meant to look.
18
+ *
19
+ * `epic` joined the set in #78: the scheduled-drivers model (#70) needs a driver to
20
+ * exclude tracking/umbrella records from what it starts unattended, exactly the way it
21
+ * already excludes `agent-filed` issues (CONVENTIONS.md §5, *Provenance*). An
22
+ * `epic`-labelled issue is informative — a container for sub-issues — never a start
23
+ * candidate and never claimed as a unit of work. It joins CONVENTION_LABELS rather than
24
+ * staying repo-local because an unattended decision now depends on it, the same bar the
25
+ * other three met; contrast `TRACKING_LABEL` below, which stays opt-in because nothing
26
+ * unattended reads it (yet).
27
+ *
28
+ * `needs-decision` (named `needs-ruling` before #122) joined the set in #75: a human must
29
+ * answer a blocking question before this issue can start — originally scoped to a
30
+ * designer's pre-approval, widened by #122 to the whole family a gate this shape actually
31
+ * covers (a design ruling, a business-logic call, a permission), because "ruling" read
32
+ * narrower than the gate. A readiness gate exactly like an open hard blocker or
33
+ * `in-progress`, not a softer advisory. Absent this label a repo cannot apply that gate at
34
+ * all, and a surface nobody has ruled on reads as a normal start candidate to a human
35
+ * session or a scheduled driver alike (CONVENTIONS.md §5, *Decision gate*). It joins
36
+ * CONVENTION_LABELS for the same reason `epic` did: an unattended decision (a scheduler's
37
+ * start-or-skip) depends on it.
38
+ *
39
+ * `decision-recorded` joined the set in #121, alongside the same rename: clearing
40
+ * `needs-decision` is not by itself evidence a human answered — a gate cleared by hand and
41
+ * a gate never applied read identically to a later reader, and #127 measured exactly that
42
+ * failure (a ruling sat live in a comment; a later triage pass, seeing no label, re-gated
43
+ * the issue). So recording a ruling is now a POSITIVE, machine-readable act — a
44
+ * `⚖ Decision recorded` comment (tools/lib/decision-record.js) plus this label, written
45
+ * together — never the mere absence of `needs-decision`. A consumer checking readiness
46
+ * must look for this label (or the live marker) before re-applying the gate, not just for
47
+ * the gate's absence.
48
+ *
49
+ * `needs-plan` joined the set in #94: `code-triage` flags an issue it judges genuinely
50
+ * hard — ambiguous scope, a novel design with no repo precedent, a coupling wider than
51
+ * file overlap — and `code-start` reads the flag to decide whether to run `code-plan`
52
+ * before coding, rather than the default 3-5-line stub. Unlike `needs-decision` it is NOT a
53
+ * readiness gate — a flagged issue is still startable now, it just should not go straight
54
+ * to code (CONVENTIONS.md §5, *Planning*). It is provisioned like the rest of this set,
55
+ * not created on demand the way `group:<key>` is, because its name is fixed and every
56
+ * adopting repo needs it before the first triage pass can flag anything.
57
+ *
58
+ * `migration-granted` joined the set in #98: a human-only, per-issue, branch-bound, expiring
59
+ * exemption to `colab ship`'s no-new-migrations precondition, for the one legitimate class of
60
+ * work that gate would otherwise make permanently un-shippable unattended — an issue whose
61
+ * entire deliverable IS a schema change (CONVENTIONS.md §5, *Migration exemption*). `colab ship`
62
+ * reads it, on EVERY issue a branch carries, when — and only when — that branch touches a
63
+ * migration path; absence is the ordinary, unexempted case and costs nothing. Its nearest
64
+ * neighbour is `needs-decision`, and the two point opposite directions: `needs-decision` *blocks* a
65
+ * start pending a human answer; `migration-granted` *unblocks* a ship because a
66
+ * human already reviewed the schema change. It joins `CONVENTION_LABELS` rather than staying
67
+ * repo-opt-in like `tracking`/`graph-empty` because its absence fails MALIGNANTLY, not benignly:
68
+ * a repo that adopted before this label existed cannot create a grant at all, so the schema-
69
+ * change issue parks forever under a scheduled driver — discovered only at the moment it hits
70
+ * the wall, with no prior signal — which is exactly the "silently never back-filled it, and the
71
+ * check that label powers can then never fire" failure this file's own opening paragraph names.
72
+ * The label alone authorizes nothing (the branch binding lives in a comment marker,
73
+ * tools/lib/migration-grant.js, and no automated path ever writes either half) — an unused label
74
+ * is inert, an absent one is a wall.
75
+ *
76
+ * `needs-migration-grant` joined the set in #230: the PLAN-TIME half of the same gate.
77
+ * `migration-granted` above is what `colab ship` reads at merge time; this one is what a
78
+ * consumer (the fleet dashboard) writes at plan/triage time, as soon as it can tell an
79
+ * issue's deliverable IS a schema migration — flagging the eventual grant request before
80
+ * `ship` has to refuse and discover it late. This repo's own tooling never reads it (unlike
81
+ * `needs-plan`, which `code-start` reads directly); it exists here purely to be
82
+ * PROVISIONABLE, on the same precedent `needs-plan` and `agent-filed` already set — a label
83
+ * whose semantics live in a downstream consumer, not in `colab` itself, can still belong to
84
+ * this set if leaving it repo-local would produce the identical malignant-absence failure
85
+ * `migration-granted` names: measured across four adopted repos, one lacked the label
86
+ * entirely and the plan-time flag silently did nothing there — no error, no audit finding,
87
+ * just a request that never surfaced until `ship` refused much later. It is explicitly never
88
+ * a substitute for `migration-granted` — it only widens detection of what might need a
89
+ * grant, it grants nothing itself, and only a human minting `migration-granted` still
90
+ * authorizes anything.
91
+ *
92
+ * `ci-granted` joined the set in #105: a human-only, per-issue, branch-bound, expiring
93
+ * exemption to `colab ship`'s trunk-CI-green precondition, for the one case that gate
94
+ * otherwise makes permanently un-shippable unattended — a GENUINELY red trunk, where the
95
+ * candidate branch IS the fix and cannot reach trunk without shipping, and shipping
96
+ * requires the green the fix would produce (CONVENTIONS.md §5, *Red-trunk exemption*). Its
97
+ * nearest neighbour is `migration-granted` (#98) — same shape, same write path
98
+ * (`COLAB_HUMAN=1`, label + branch-bound comment marker, tools/lib/ci-grant.js) — but this
99
+ * one is strictly more dangerous: a bad migration grant merges one reviewed schema change,
100
+ * a bad CI grant merges into a repo whose own test suite is known-failing. So unlike the
101
+ * migration grant it also carries a bound RED TRUNK SHA (the grant expires the instant
102
+ * trunk's head moves, granted or not) and requires MEASURED evidence — a real green run on
103
+ * the branch's own head — never a human's say-so alone. It joins `CONVENTION_LABELS` for
104
+ * the identical malignant-absence reason `migration-granted` did: a repo that adopted
105
+ * before this label existed cannot create a grant at all, so the fix for its own red trunk
106
+ * parks forever with no signal until the moment it hits the wall.
107
+ *
108
+ * `delivery:*` joined the set in #112: a tracker mixes issues whose delivery is NOT a code
109
+ * commit — a content push, an ops/production check, code for another repository — into a
110
+ * pipeline whose every stage (worktree, gate, mergeable, squash, `Closes #N`) assumes one. Such
111
+ * an issue can never reach a mergeable state, so it reads as eternally stuck, and — the expensive
112
+ * half — it looks STARTABLE to triage and a scheduled driver alike, because no existing readiness
113
+ * label says "this is real work, but not a diff" the way `epic` says "this is not a unit of work
114
+ * at all". Six labels (five in #112, `design` in #359), one classifier, deliberately (still) THREE-VALUED rather than boolean
115
+ * (CONVENTIONS.md §5, *Delivery type*): no `delivery:*` label at all reads as **not asked**, and
116
+ * must behave exactly as before this label set existed — every issue in every tracker is
117
+ * unlabelled the day this lands, so absence collapsing into "non-code" would freeze the start
118
+ * gate for everyone on day one. `delivery:code` is the explicit affirmative for a code issue;
119
+ * which values are non-code (route-not-start) and which are code-lane is spelled out in the
120
+ * #358/#359 paragraph below — the route rule itself is a companion to the `epic` rule and the
121
+ * `needs-decision` gate, not a merge of either. It joins `CONVENTION_LABELS` for the same reason
122
+ * `epic` did: an unattended decision (a scheduler's or triage's start-or-skip) depends on being
123
+ * able to tell the states apart, and a repo that adopted before this set existed cannot create
124
+ * the label at all — the malignant-absence failure this file's opening paragraph names.
125
+ *
126
+ * `delivery:elsewhere` joined the set in #274, after living un-provisioned on three separate
127
+ * trackers (21 issues, all hand-created — `colab labels --ensure` could never create a label
128
+ * absent from `CONVENTION_LABELS`). It names an issue whose deliverable IS code, but code that
129
+ * lands in a different repository than this tracker's own — so it belongs in the non-code-HERE
130
+ * bucket for exactly the reason `content`/`ops` do: this pipeline's worktree, gate,
131
+ * mergeable and squash machinery all assume the diff lands in the repo the issue lives in, and
132
+ * an `elsewhere` issue breaks that assumption the same way a content push does. Before this
133
+ * entry, `deliveryType()` returned `null` for it — byte-identical to an issue nobody ever
134
+ * labelled — so `isRouteNotStart()` read `false` and every one of those 21 issues reported
135
+ * STARTABLE to triage, the opposite of what applying the label was asking for.
136
+ *
137
+ * #358 and #359 settled the lanes. `delivery:docs-only` was provisioned in #112 as a non-code
138
+ * type ("a docs sync outside code review, not a commit"), but a docs-only deliverable in THIS
139
+ * repo is an in-repo commit like any other — worktree, gate, `colab ship` — and a consumer's
140
+ * scheduler already read it that way, so triage withheld `deps-checked` from issues the
141
+ * scheduler would have started and they sat with no park and no decision (one for 6 days). It
142
+ * is now a CODE-LANE value: classified (`deliveryType` returns `'docs-only'`, never `null`) and
143
+ * never route-not-start. It is not ship's #345 docs-only exception either — that is measured
144
+ * from the diff (`docs-only.js`), never read from this label. `delivery:design` (#359) is the
145
+ * deliverable-is-a-design-artifact value for a new surface: never a code start, so it joins
146
+ * NON_CODE_DELIVERY_TYPES and `isRouteNotStart()` reads true for it; keeping it apart from the
147
+ * route bucket is a REPORTING job (code-triage's own design bucket), not a second classifier
148
+ * nobody in this repo would read. Before #359 two consumers hand-created it and `deliveryType()`
149
+ * returned `null` for it — the #274 failure again. So the value list `deliveryType()` walks is
150
+ * now DERIVED from CONVENTION_LABELS (`DELIVERY_TYPES`), never hand-typed: any provisioned
151
+ * `delivery:*` value is classified by construction, and a partition test forces each new one
152
+ * into exactly one lane (`CODE_LANE_DELIVERY_TYPES` or `NON_CODE_DELIVERY_TYPES`) on purpose.
153
+ *
154
+ * `low-priority` joined the set in #268: it orders a queue, it does not remove work from
155
+ * one — unlike `epic` and a non-code `delivery:*` value above, a `low-priority` issue IS a start candidate,
156
+ * only ranked behind every other ready group (CONVENTIONS.md §5, *Priority*). It joins
157
+ * CONVENTION_LABELS for the same reason `epic` and `delivery:*` did: a scheduled driver's
158
+ * ordering decision depends on seeing the label, and a repo that adopted before it existed
159
+ * cannot create it at all — the identical malignant-absence failure. Before #268 the label
160
+ * was read three different, undocumented ways across one adopting fleet (a hard veto by one
161
+ * driver, a sort key nothing enforced by a sibling tool, and invisible to `code-triage`
162
+ * entirely, which reported `low-priority` groups READY with no distinguishing signal) —
163
+ * this entry, plus the matching `code-triage` verdict, is what makes those readings
164
+ * reconcilable instead of silently contradictory.
165
+ *
166
+ * `deferred:date` / `deferred:measurement` / `deferred:external-party` joined the set in
167
+ * #279: `deps-checked` was being asked to carry two orthogonal facts at once — "has a
168
+ * reasoning session evaluated this?" (process state, monotonic — the label's own
169
+ * definition above) and "is it startable right now?" (readiness, volatile) — and
170
+ * `code-triage` runs in practice sacrificed the first to express the second, by clearing
171
+ * the label on work it judged not startable for a reason that was never a blocker.
172
+ * Measured on one adopting fleet: one repo with 83 open issues had 40 carrying
173
+ * `deps-checked`, 9 genuinely untriaged, and 11 triaged-work-reporting-as-untriaged —
174
+ * more than half of the untriaged-looking backlog; a second, smaller repo had 4 such
175
+ * cases. `deps-checked` is now monotonic (CONVENTIONS.md §5, *Disposition*) and these
176
+ * three labels are the machine-readable carrier for the displaced fact: an issue is
177
+ * ready, but parked on a date, a measurement, or someone outside this repo, rather than
178
+ * on another issue (`blockedBy`, unchanged) or a human ruling (`needs-decision`,
179
+ * unchanged). They join `CONVENTION_LABELS` for the identical malignant-absence reason
180
+ * `delivery:*` did: a repo that adopted before this landed cannot create the label at
181
+ * all, so a park it wants to record instead reports as an unexamined issue — the exact
182
+ * confusion #279 measured. **Vocabulary only, deliberately inert on landing:** nothing in
183
+ * this repo's own tooling writes or reads these three yet (no `code-triage` write, no
184
+ * readiness wiring, no audit finding) — the sequencing hazard #279 itself names is that
185
+ * emitting the label before a consumer renders the disposition distinctly produces a
186
+ * label nothing reads, which is worse than the silent park it replaces. An unused label
187
+ * is inert; see `migration-granted`'s own paragraph above for the same argument.
188
+ *
189
+ * `review-by:<date>` is the wake condition a `deferred:*` park should usually name,
190
+ * deliberately NOT in `CONVENTION_LABELS` — same treatment as `group:<key>`: the date
191
+ * varies per issue, so there is no fixed set to provision up front, and it is created on
192
+ * demand by whoever applies the park. "A defer must name its wake condition" (#279): a
193
+ * `deferred:*` label with no `review-by:<date>`, no `blockedBy` edge and no checkable `wake:`
194
+ * (the closed vocabulary in tools/lib/wake.js, #382) is not a defer at all — it is a
195
+ * deprioritisation or a `wontfix` that should be said plainly, because an unbounded park is a
196
+ * silent `wontfix`.
197
+ *
198
+ * `release-hold` joined the set in #339: the human veto on a release candidate (CONVENTIONS.md
199
+ * §6, *The release rung*). It sits on a release TRACKING issue (`release: vX.Y.Z`, marker
200
+ * `<!-- colab:release version=vX.Y.Z -->`), and while it is present `colab release finalize`
201
+ * does not tag that version's final. Provisioned, not opt-in, for the sharpest form of the
202
+ * malignant-absence reason above: the moment a human wants to veto is a test period that is
203
+ * already counting down, and a label the repo never created cannot be applied in that moment —
204
+ * the veto would silently not exist. Only a human removes it; no command in this repo does.
205
+ */
206
+
207
+ const CONVENTION_LABELS = [
208
+ { name: 'in-progress', color: 'FBCA04', description: 'Claimed by an active session' },
209
+ { name: 'deps-checked', color: '0E8A16', description: 'Dependencies verified — no open blocker' },
210
+ { name: 'agent-filed', color: 'C5DEF5', description: 'Filed by an agent on its own initiative — not human-approved' },
211
+ { name: 'epic', color: '3E4B9E', description: 'Container for sub-issues — informative, never a start candidate, never claimed as a unit of work' },
212
+ { name: 'needs-decision', color: 'B60205', description: 'A human must answer a blocking question before this can start' },
213
+ { name: 'decision-recorded', color: '006B75', description: 'A human answered here — ask a new question via colab decision --reopen, never a hand-added label' },
214
+ { name: 'needs-plan', color: '0052CC', description: 'Triage judged this hard — code-start should run code-plan before coding' },
215
+ { name: 'migration-granted', color: 'D93F0B', description: "A human granted this issue's branch an exemption from ship's no-new-migrations gate" },
216
+ { name: 'needs-migration-grant', color: 'D4C5F9', description: 'Agent-flagged: deliverable is a schema migration; surfaces the grant request for a human to Accept' },
217
+ { name: 'ci-granted', color: 'D73A4A', description: "A human granted this branch a one-shot exemption from ship's trunk-CI-green gate" },
218
+ { name: 'low-priority', color: 'C2E0C6', description: 'Throttle, not a veto — startable, but code-triage ranks it behind every other ready group' },
219
+ { name: 'delivery:code', color: '1D76DB', description: 'Delivery is a code commit — the ordinary code pipeline applies' },
220
+ { name: 'delivery:content', color: 'FEF2C0', description: 'Delivery is a content push, not a code commit — route, do not start in the code pipeline' },
221
+ { name: 'delivery:ops', color: 'D4C5F9', description: 'Delivery is an ops/production check, not a code commit — route, do not start in the code pipeline' },
222
+ { name: 'delivery:docs-only', color: 'BFD4F2', description: 'Delivery is a docs-only commit in this repo — the ordinary code pipeline applies' },
223
+ { name: 'delivery:elsewhere', color: 'F9D0C4', description: 'Delivery is code, but lands in a different repository — route, do not start here' },
224
+ { name: 'delivery:design', color: 'C39BD3', description: 'Delivery is a design artifact for a new surface — a design session works it, never a code start' },
225
+ { name: 'deferred:date', color: 'B08800', description: 'Parked until a specific date — pair with a review-by:<date> label naming it' },
226
+ { name: 'deferred:measurement', color: '7C6F57', description: 'Parked until a metric crosses a threshold — name the metric and the threshold on the issue' },
227
+ { name: 'deferred:external-party', color: '6E5494', description: 'Parked until someone outside this repo acts — name who, and pair with review-by:<date>' },
228
+ { name: 'release-hold', color: 'E11D21', description: 'Human veto on a release tracking issue: its candidate is not finalized while this is present' },
229
+ ];
230
+
231
+ // The DELIVERY label prefix (CONVENTIONS.md §5, Delivery type). Six fixed values, unlike
232
+ // `group:<key>` — provisioned up front in CONVENTION_LABELS above, not created on demand.
233
+ const DELIVERY_LABEL_PREFIX = 'delivery:';
234
+
235
+ // Every provisioned delivery value, in CONVENTION_LABELS order — DERIVED, never hand-typed
236
+ // (#358/#359): a value provisioned above is classified by `deliveryType()` by construction,
237
+ // so a new one can never read as "not asked" the way `elsewhere` did before #274.
238
+ const DELIVERY_TYPES = CONVENTION_LABELS
239
+ .map((l) => l.name)
240
+ .filter((n) => n.startsWith(DELIVERY_LABEL_PREFIX))
241
+ .map((n) => n.slice(DELIVERY_LABEL_PREFIX.length));
242
+
243
+ // The code-lane delivery types — an in-repo commit through worktree, gate and `colab ship`.
244
+ // `docs-only` is here since #358: a docs-only deliverable is still a commit. (It is NOT ship's
245
+ // #345 docs-only exception, which is measured from the diff, never read from this label.)
246
+ const CODE_LANE_DELIVERY_TYPES = ['code', 'docs-only'];
247
+
248
+ // The four non-code delivery types — the ones triage and the readiness gate treat as
249
+ // route-not-start. `design` (#359) is here because it is never a code start; code-triage
250
+ // reports it in its own design bucket rather than the route bucket.
251
+ const NON_CODE_DELIVERY_TYPES = ['content', 'ops', 'elsewhere', 'design'];
252
+
253
+ /**
254
+ * The three-valued delivery classifier (CONVENTIONS.md §5, *Delivery type*).
255
+ *
256
+ * Returns one of:
257
+ * - `null` — NOT ASKED. No `delivery:*` label present, or only a value the handbook does
258
+ * not define (a consumer-local one, e.g. `delivery:elsewhere-partial`, #366 —
259
+ * handbook-sync reports those as `value` drift; this classifier guesses no
260
+ * meaning for them). Must read identically to how the issue behaved before
261
+ * this label set existed — never as non-code.
262
+ * - `'code' | 'docs-only'` — a code-lane value present (CODE_LANE_DELIVERY_TYPES).
263
+ * - `'content' | 'ops' | 'elsewhere' | 'design'` — a non-code value present
264
+ * (NON_CODE_DELIVERY_TYPES).
265
+ *
266
+ * Tolerant of label objects or bare strings, the same shape every other helper in this file
267
+ * accepts. If more than one `delivery:*` label is somehow present (a tracker mistake, not a
268
+ * state this repo's tooling ever writes), the first match in CONVENTION_LABELS order wins —
269
+ * deterministic, and it is a contradiction worth surfacing rather than silently averaging.
270
+ */
271
+ function deliveryType(present) {
272
+ const have = new Set(
273
+ (present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).map((n) => String(n)),
274
+ );
275
+ for (const type of DELIVERY_TYPES) {
276
+ if (have.has(`${DELIVERY_LABEL_PREFIX}${type}`)) return type;
277
+ }
278
+ return null;
279
+ }
280
+
281
+ // Is this issue's delivery type one triage/the readiness gate should route rather than start?
282
+ // `null` (not asked) and a code-lane value (`'code'`, `'docs-only'`) read false here — only an
283
+ // explicit non-code type routes.
284
+ function isRouteNotStart(present) {
285
+ return NON_CODE_DELIVERY_TYPES.includes(deliveryType(present));
286
+ }
287
+
288
+ // The DEFERRED label prefix (CONVENTIONS.md §5, Disposition — #279). Three fixed values,
289
+ // same treatment as DELIVERY_LABEL_PREFIX: provisioned up front in CONVENTION_LABELS above,
290
+ // not created on demand.
291
+ const DEFERRED_LABEL_PREFIX = 'deferred:';
292
+
293
+ // The three park kinds a ready-but-not-started issue can carry — a date, a measurement, or
294
+ // a party outside this repo. Distinct from `blockedBy` (waiting on another issue) and from
295
+ // `needs-decision` (waiting on a human ruling), which are unchanged by this set.
296
+ const DEFERRED_KINDS = ['date', 'measurement', 'external-party'];
297
+
298
+ /**
299
+ * The deferred-kind classifier (CONVENTIONS.md §5, *Disposition*, #279) — same shape as
300
+ * `deliveryType()` above, deliberately: tolerant of label objects or bare strings, first
301
+ * match in canonical order wins if more than one is somehow present.
302
+ *
303
+ * Returns one of:
304
+ * - `null` — no `deferred:*` label present.
305
+ * - `'date' | 'measurement' | 'external-party'` — the matching `deferred:*` label present.
306
+ *
307
+ * Nothing in this repo's own tooling calls this yet (#279 ships the vocabulary only) — see
308
+ * the doc comment above CONVENTION_LABELS for why that is the deliberate end state, not an
309
+ * oversight.
310
+ */
311
+ function deferredKind(present) {
312
+ const have = new Set(
313
+ (present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).map((n) => String(n)),
314
+ );
315
+ for (const kind of DEFERRED_KINDS) {
316
+ if (have.has(`${DEFERRED_LABEL_PREFIX}${kind}`)) return kind;
317
+ }
318
+ return null;
319
+ }
320
+
321
+ // Is this issue carrying a deferred:* park? Same shape as isRouteNotStart(): a thin,
322
+ // readable wrapper over the classifier for a caller that only needs the boolean.
323
+ function isDeferred(present) {
324
+ return deferredKind(present) !== null;
325
+ }
326
+
327
+ // The REVIEW-BY label prefix (CONVENTIONS.md §5, Disposition — #279). Deliberately NOT in
328
+ // CONVENTION_LABELS, same reasoning as GROUP_LABEL_PREFIX below: the date varies per issue,
329
+ // so there is no fixed set to provision up front — created on demand by whoever applies the
330
+ // park, and it is the wake condition a `deferred:*` label should usually be paired with.
331
+ const REVIEW_BY_LABEL_PREFIX = 'review-by:';
332
+
333
+ // Is this label name a review-by marker? Guards against the bare prefix itself
334
+ // ("review-by:" with no date) reading as one, same shape as isGroupLabel below.
335
+ function isReviewByLabel(name) {
336
+ return typeof name === 'string' && name.length > REVIEW_BY_LABEL_PREFIX.length && name.startsWith(REVIEW_BY_LABEL_PREFIX);
337
+ }
338
+
339
+ // The review-by label names carried by a label list — same tolerant shape as
340
+ // groupLabelNames below (bare strings or {name} objects), order-preserving, deduplicated.
341
+ function reviewByLabelNames(present) {
342
+ const out = [];
343
+ const seen = new Set();
344
+ for (const n of (present || [])) {
345
+ const name = n && typeof n === 'object' ? n.name : n;
346
+ const s = name === undefined || name === null ? '' : String(name);
347
+ if (isReviewByLabel(s) && !seen.has(s)) { seen.add(s); out.push(s); }
348
+ }
349
+ return out;
350
+ }
351
+
352
+ /**
353
+ * Parse a `review-by:<date>` label's date, strictly — the sole purpose of this function is
354
+ * to make "is this actually a valid calendar date" checkable without a caller reaching for
355
+ * lenient `Date` parsing, which silently accepts what this must reject: `new Date('2026-02-30')`
356
+ * does not throw, it rolls over to March 2nd, and `Date.parse` accepts forms (two-digit
357
+ * years, unpadded months/days) this label was never meant to carry.
358
+ *
359
+ * Returns the `YYYY-MM-DD` string unchanged if it names a real calendar day, or `null` for
360
+ * anything else (wrong shape, out-of-range month/day, or not a review-by label at all).
361
+ *
362
+ * Pure, deliberately: no `Date.now()`, no "is this overdue" — that is a consumer's decision
363
+ * to make once one exists (#279 ships the vocabulary only), not this function's.
364
+ */
365
+ function parseReviewByDate(name) {
366
+ const s = name && typeof name === 'object' ? name.name : name;
367
+ if (typeof s !== 'string') return null;
368
+ const m = /^review-by:(\d{4})-(\d{2})-(\d{2})$/.exec(s);
369
+ if (!m) return null;
370
+ const [, ys, ms, ds] = m;
371
+ const y = Number(ys), mo = Number(ms), d = Number(ds);
372
+ const asUtc = new Date(Date.UTC(y, mo - 1, d));
373
+ // Round-trip check: Date.UTC normalises out-of-range components (month 13 rolls into the
374
+ // next year, day 30 of February rolls into March) instead of rejecting them, so read the
375
+ // parts back and require an exact match.
376
+ if (asUtc.getUTCFullYear() !== y || asUtc.getUTCMonth() !== mo - 1 || asUtc.getUTCDate() !== d) return null;
377
+ return `${ys}-${ms}-${ds}`;
378
+ }
379
+
380
+ function conventionLabelNames() {
381
+ return CONVENTION_LABELS.map((l) => l.name);
382
+ }
383
+
384
+ // The LOAD-BEARING subset (#393) — the labels a session's own start/claim/file path writes, and
385
+ // therefore the only ones a repo the fleet does not own has to carry for code-start → code-wrap →
386
+ // colab ship to work there: `in-progress` (the claim's tracker mirror), `deps-checked` (readiness
387
+ // — without it no issue ever leaves "nobody looked"), `agent-filed` (provenance), `epic` (a
388
+ // container is never a start candidate). Everything else in CONVENTION_LABELS is opt-in by USE:
389
+ // it only has to exist where its mechanic is used, and creating 20+ labels on someone else's
390
+ // tracker is noise its owner never asked for. `colab labels --ensure --minimal` reads this list.
391
+ const MINIMAL_LABEL_NAMES = ['in-progress', 'deps-checked', 'agent-filed', 'epic'];
392
+
393
+ /** The CONVENTION_LABELS entries for MINIMAL_LABEL_NAMES, canonical order and definitions. */
394
+ function minimalConventionLabels() {
395
+ const want = new Set(MINIMAL_LABEL_NAMES);
396
+ return CONVENTION_LABELS.filter((l) => want.has(l.name));
397
+ }
398
+
399
+ // The readiness marker, named once. CONVENTIONS.md §5 (Readiness) is the prose source; the
400
+ // audit, the provisioner and now `colab readiness` all read the name from HERE rather than
401
+ // spelling the string themselves — a second literal is a second thing to typo, and a readiness
402
+ // write that targets `deps_checked` while the audit checks `deps-checked` fails silently, which
403
+ // is the whole class of bug this single list exists to make impossible.
404
+ const READINESS_LABEL = 'deps-checked';
405
+
406
+ // The marker for a long-lived MEMORY / TRACKING issue (CONVENTIONS.md §5, Tracking issues).
407
+ // A tracking issue is external memory for a whole domain — accumulated decisions and gotchas plus
408
+ // a checklist of still-open items — that a hygiene session legitimately CLAIMS (to signal work in
409
+ // the area) and REFERENCES, but does not complete. `colab ship` reads this name and emits `Refs #N`
410
+ // instead of `Closes #N` for any claimed issue that carries it, so shipping a small fix in the
411
+ // domain does not bury the memory behind a closed-issue lookup.
412
+ //
413
+ // Deliberately NOT in CONVENTION_LABELS: those are the labels whose absence makes a check silently
414
+ // impossible (a claim that cannot land, a readiness column that can never fill). This one is opt-in
415
+ // per repo and per issue — its absence just means every issue closes as before, which is the
416
+ // correct default. So adoption/sync do not force-provision it and the audit does not report its
417
+ // absence. A repo that wants the behaviour creates the label and applies it to its tracking issues.
418
+ const TRACKING_LABEL = 'tracking';
419
+
420
+ // The marker for a MECHANICAL readiness check (CONVENTIONS.md §5, Mechanical readiness — #69).
421
+ // `deps-checked` asserts a reasoning session looked and judged the issue clear — a claim a bare
422
+ // API read cannot make, because a blocker described only in prose is invisible to it. This label
423
+ // asserts the strictly weaker thing a mechanical read CAN prove honestly: the recorded graph
424
+ // (`blockedBy`) reads empty as of that read. It is a distinct name on purpose, never a synonym or
425
+ // a second color for `deps-checked` — the whole point of #69's resolution is that the two claims
426
+ // must not be allowed to collapse into one label a consumer cannot tell apart.
427
+ //
428
+ // Deliberately NOT in CONVENTION_LABELS, same reasoning as TRACKING_LABEL above: nothing
429
+ // unattended reads it (yet), so adoption/sync do not force-provision it and the audit does not
430
+ // report its absence. A repo that wants the faster, weaker lane creates the label itself and
431
+ // opts a consumer into `readiness.isStartableMechanical()`.
432
+ const MECHANICAL_READINESS_LABEL = 'graph-empty';
433
+
434
+ // The `gh issue edit` label arguments for owning the readiness marker. Pure, so the mapping
435
+ // "set ⇒ add, clear ⇒ remove" is pinned by a test without a network call: the command is a thin
436
+ // shell around ghIssueEdit(repo, num, readinessLabelArgs(...)), and the part worth getting right
437
+ // is exactly this arg vector.
438
+ function readinessLabelArgs({ clear } = {}) {
439
+ return clear
440
+ ? ['--remove-label', READINESS_LABEL]
441
+ : ['--add-label', READINESS_LABEL];
442
+ }
443
+
444
+ // #388: the success line `colab readiness <N>` prints after ADDING deps-checked. It used to say
445
+ // "verified: no open blocker" unconditionally — a claim the default path never checked (only
446
+ // --mechanical reads blockedBy), printed verbatim even on issues with open blockers, and the one
447
+ // line operators copy into reports. It now says what was DONE (the review was recorded) and what
448
+ // the graph holds, from one blockedBy read (`summary` = blocked-by.js openBlockerSummary, or
449
+ // null/{ok:false} when the read failed). It never says "verified" and never "no open blocker":
450
+ // deps-checked is a review record, and an open edge carries the block on its own (§5, #279).
451
+ function readinessMarkedMessage({ num, repo, summary } = {}) {
452
+ const head = `Marked #${num} in ${repo} ${READINESS_LABEL} — dependencies reviewed`;
453
+ if (!summary || !summary.ok) {
454
+ return `${head}; blockedBy: unread (the label records your review, not a graph read)`;
455
+ }
456
+ const { total, read, open, unknownState } = summary;
457
+ const truncated = read < total;
458
+ let tail = `blockedBy: ${truncated ? '≥' : ''}${open} open`;
459
+ if (total > 0) tail += ` of ${total}`;
460
+ if (unknownState > 0) tail += `, ${unknownState} with unread state`;
461
+ if (truncated) tail += `, only ${read} read`;
462
+ if (open > 0) tail += ' (an open edge carries the block — this label does not lift it)';
463
+ return `${head}; ${tail}`;
464
+ }
465
+
466
+ // The `gh issue edit` label arguments for owning the MECHANICAL readiness marker. Same shape as
467
+ // readinessLabelArgs, kept as a separate function rather than a parameter on that one: the two
468
+ // markers must never be writable through the same call site, or a caller could flip one when it
469
+ // meant the other. See MECHANICAL_READINESS_LABEL above for what the label asserts.
470
+ function mechanicalReadinessLabelArgs({ clear } = {}) {
471
+ return clear
472
+ ? ['--remove-label', MECHANICAL_READINESS_LABEL]
473
+ : ['--add-label', MECHANICAL_READINESS_LABEL];
474
+ }
475
+
476
+ // The migration-grant marker, named once (#98). CONVENTIONS.md §5 (Migration exemption) is the
477
+ // prose source; `colab migration-grant`, `colab ship`'s grant read, and the provisioner all read
478
+ // the name from HERE — the identical reason READINESS_LABEL is a shared constant, not a literal
479
+ // repeated at each call site.
480
+ const MIGRATION_GRANT_LABEL = 'migration-granted';
481
+
482
+ // The `gh issue edit` label arguments for owning the migration-grant marker. Pure, same shape and
483
+ // same reason as readinessLabelArgs: the write is a thin shell around
484
+ // ghIssueEdit(repo, num, migrationGrantLabelArgs(...)), and the arg vector is the part worth
485
+ // pinning with a test that makes no network call.
486
+ function migrationGrantLabelArgs({ clear } = {}) {
487
+ return clear
488
+ ? ['--remove-label', MIGRATION_GRANT_LABEL]
489
+ : ['--add-label', MIGRATION_GRANT_LABEL];
490
+ }
491
+
492
+ // Given the label names a repo actually has, return the convention labels it is missing,
493
+ // in the canonical order. Tolerant of null/undefined (a repo whose labels could not be
494
+ // read is handled by the caller, not here) and of label objects vs bare strings.
495
+ function missingConventionLabels(present) {
496
+ const have = new Set(
497
+ (present || []).map((n) => (n && typeof n === 'object' ? n.name : n)).map((n) => String(n)),
498
+ );
499
+ return conventionLabelNames().filter((n) => !have.has(n));
500
+ }
501
+
502
+ // Given the labels a repo actually has, WITH their descriptions, return every convention label
503
+ // whose tracker description differs from CONVENTION_LABELS' text, in canonical order:
504
+ // [{ name, have, want }]. #364: `colab labels --ensure` creates a missing label and never touches
505
+ // an existing one, so a label created before the handbook reworded it keeps the old text for good
506
+ // — and a human or agent reading the tracker sees a meaning the handbook has since changed.
507
+ // An entry with no readable description — a bare name string, or an object whose `description`
508
+ // is not a string — is SKIPPED, never reported: a caller that only fetched names cannot know the
509
+ // text, and "could not read" must never surface as "differs" (the same contract as a null set).
510
+ // An empty-string description IS read, and differs, since every CONVENTION_LABELS entry has text.
511
+ // Labels outside the convention set are ignored (#364 out of scope), as are colours.
512
+ function staleConventionDescriptions(present) {
513
+ const want = new Map(CONVENTION_LABELS.map((l) => [l.name, l.description]));
514
+ const have = new Map();
515
+ for (const l of present || []) {
516
+ if (!l || typeof l !== 'object' || typeof l.description !== 'string') continue;
517
+ have.set(String(l.name), l.description);
518
+ }
519
+ return CONVENTION_LABELS
520
+ .filter((l) => have.has(l.name) && have.get(l.name) !== want.get(l.name))
521
+ .map((l) => ({ name: l.name, have: have.get(l.name), want: l.description }));
522
+ }
523
+
524
+ // A readiness ADD (`gh issue edit --add-label deps-checked`) fails for one recurring, diagnosable
525
+ // reason: the repo adopted the conventions before `deps-checked` entered the set and never
526
+ // back-filled it, so the label the write targets does not exist. Given the labels the repo
527
+ // actually has, return an actionable message naming that cause and its fix — or null, meaning
528
+ // "not this cause, use the generic error". Two nulls, deliberately different:
529
+ // - `present` is null → the label set could not be READ (no gh, no remote, network). We must
530
+ // not guess the cause from a read we did not get; fall back to the raw gh error.
531
+ // - the readiness label IS present → the ADD failed for some other reason; not ours to explain.
532
+ // This is where the doubly-silent failure of #49 is made loud: never report success on a write
533
+ // that did not land, and when it did not land for this reason, say precisely why and what fixes it.
534
+ function readinessMissingLabelHint(present) {
535
+ if (!present) return null;
536
+ if (!missingConventionLabels(present).includes(READINESS_LABEL)) return null;
537
+ return `this repo has no \`${READINESS_LABEL}\` label, so readiness cannot be marked — it adopted `
538
+ + `the conventions before that label entered the set and never back-filled it. Run handbook-sync `
539
+ + `(§7) to create the convention label set, then re-run the command.`;
540
+ }
541
+
542
+ // Same diagnosis as readinessMissingLabelHint, for the migration-grant marker (#98): a repo that
543
+ // adopted before `migration-granted` entered the set has no such label, so a grant ADD hits a
544
+ // label that does not exist. Same two-null contract: `present` null means the read itself failed
545
+ // (fall back to the raw gh error), the label being present means the ADD failed for some other
546
+ // reason — this function is not the one to explain that.
547
+ function migrationGrantMissingLabelHint(present) {
548
+ if (!present) return null;
549
+ if (!missingConventionLabels(present).includes(MIGRATION_GRANT_LABEL)) return null;
550
+ return `this repo has no \`${MIGRATION_GRANT_LABEL}\` label, so a migration grant cannot be marked — it `
551
+ + `adopted the conventions before that label entered the set and never back-filled it. Run `
552
+ + `handbook-sync (§7) to create the convention label set, then re-run the command.`;
553
+ }
554
+
555
+ // The ci-grant marker, named once (#105). CONVENTIONS.md §5 (Red-trunk exemption) is the prose
556
+ // source; `colab ci-grant`, `colab ship`'s grant read, and the provisioner all read the name from
557
+ // HERE — the identical reason MIGRATION_GRANT_LABEL is a shared constant, not a literal repeated
558
+ // at each call site.
559
+ const CI_GRANT_LABEL = 'ci-granted';
560
+
561
+ // The `gh issue edit` label arguments for owning the ci-grant marker. Pure, same shape and same
562
+ // reason as migrationGrantLabelArgs: the write is a thin shell around
563
+ // ghIssueEdit(repo, num, ciGrantLabelArgs(...)), and the arg vector is the part worth pinning
564
+ // with a test that makes no network call. A DIFFERENT function from migrationGrantLabelArgs on
565
+ // purpose — two grants that share a call site could let a caller flip one when it meant the
566
+ // other, exactly the reason mechanicalReadinessLabelArgs stays split from readinessLabelArgs.
567
+ function ciGrantLabelArgs({ clear } = {}) {
568
+ return clear
569
+ ? ['--remove-label', CI_GRANT_LABEL]
570
+ : ['--add-label', CI_GRANT_LABEL];
571
+ }
572
+
573
+ // Same diagnosis as migrationGrantMissingLabelHint, for the ci-grant marker (#105): a repo that
574
+ // adopted before `ci-granted` entered the set has no such label, so a grant ADD hits a label that
575
+ // does not exist. Same two-null contract: `present` null means the read itself failed (fall back
576
+ // to the raw gh error), the label being present means the ADD failed for some other reason — this
577
+ // function is not the one to explain that.
578
+ function ciGrantMissingLabelHint(present) {
579
+ if (!present) return null;
580
+ if (!missingConventionLabels(present).includes(CI_GRANT_LABEL)) return null;
581
+ return `this repo has no \`${CI_GRANT_LABEL}\` label, so a CI grant cannot be marked — it `
582
+ + `adopted the conventions before that label entered the set and never back-filled it. Run `
583
+ + `handbook-sync (§7) to create the convention label set, then re-run the command.`;
584
+ }
585
+
586
+ // The decision-gate marker, named once (#75, renamed #122). CONVENTIONS.md §5 (Decision gate)
587
+ // is the prose source; `colab decision`, code-triage's readiness check, and the provisioner
588
+ // all read the name from HERE — the identical reason READINESS_LABEL is a shared constant.
589
+ const NEEDS_DECISION_LABEL = 'needs-decision';
590
+
591
+ // The positive decision-record marker, named once (#121). Paired with NEEDS_DECISION_LABEL:
592
+ // clearing the gate and recording the answer are ONE act (`colab decision --record`), never
593
+ // two — see the doc comment above CONVENTION_LABELS for why a cleared gate alone is not
594
+ // evidence anything was answered.
595
+ const DECISION_RECORDED_LABEL = 'decision-recorded';
596
+
597
+ // Same diagnosis as migrationGrantMissingLabelHint, for the decision-recorded marker (#121): a
598
+ // repo that adopted before this label entered the set has no such label, so `colab decision
599
+ // --record` cannot apply it. Same two-null contract as the others: `present` null means the
600
+ // read itself failed (fall back to the raw gh error), the label being present means the ADD
601
+ // failed for some other reason — this function is not the one to explain that.
602
+ function decisionRecordedMissingLabelHint(present) {
603
+ if (!present) return null;
604
+ if (!missingConventionLabels(present).includes(DECISION_RECORDED_LABEL)) return null;
605
+ return `this repo has no \`${DECISION_RECORDED_LABEL}\` label, so a decision cannot be recorded — it `
606
+ + `adopted the conventions before that label entered the set and never back-filled it. Run `
607
+ + `handbook-sync (§7) to create the convention label set, then re-run the command.`;
608
+ }
609
+
610
+ // The GROUP label prefix (CONVENTIONS.md §5, Grouping). `group:<key>` records that a set of
611
+ // issues must share one branch — the key is the branch slug minus its trailing issue numbers.
612
+ // Deliberately NOT in CONVENTION_LABELS: it is per-group (one label PER key, not one fixed
613
+ // name), created on demand by whoever computes the grouping (`code-triage`), not provisioned
614
+ // up front the way the fixed convention set is.
615
+ const GROUP_LABEL_PREFIX = 'group:';
616
+
617
+ // Is this label name a group marker? Guards against the bare prefix itself ("group:" with no
618
+ // key) reading as one — that string names no group and nothing should ever try to delete it.
619
+ function isGroupLabel(name) {
620
+ return typeof name === 'string' && name.length > GROUP_LABEL_PREFIX.length && name.startsWith(GROUP_LABEL_PREFIX);
621
+ }
622
+
623
+ // The group label names carried by a label list — same tolerant shape as missingConventionLabels
624
+ // (bare strings or {name} objects), so a caller can hand this `info.labels` straight off
625
+ // `gh issue view` / `gh issue list` without mapping first. Order-preserving, deduplicated: a
626
+ // caller unioning group labels across several issues (colab ship's B4, per #82) must not visit
627
+ // the same key twice.
628
+ function groupLabelNames(present) {
629
+ const out = [];
630
+ const seen = new Set();
631
+ for (const n of (present || [])) {
632
+ const name = n && typeof n === 'object' ? n.name : n;
633
+ const s = name === undefined || name === null ? '' : String(name);
634
+ if (isGroupLabel(s) && !seen.has(s)) { seen.add(s); out.push(s); }
635
+ }
636
+ return out;
637
+ }
638
+
639
+ module.exports = {
640
+ CONVENTION_LABELS, conventionLabelNames, missingConventionLabels, staleConventionDescriptions,
641
+ MINIMAL_LABEL_NAMES, minimalConventionLabels,
642
+ READINESS_LABEL, readinessLabelArgs, readinessMissingLabelHint, readinessMarkedMessage,
643
+ TRACKING_LABEL,
644
+ MECHANICAL_READINESS_LABEL, mechanicalReadinessLabelArgs,
645
+ MIGRATION_GRANT_LABEL, migrationGrantLabelArgs, migrationGrantMissingLabelHint,
646
+ CI_GRANT_LABEL, ciGrantLabelArgs, ciGrantMissingLabelHint,
647
+ NEEDS_DECISION_LABEL, DECISION_RECORDED_LABEL, decisionRecordedMissingLabelHint,
648
+ GROUP_LABEL_PREFIX, isGroupLabel, groupLabelNames,
649
+ DELIVERY_LABEL_PREFIX, DELIVERY_TYPES, CODE_LANE_DELIVERY_TYPES, NON_CODE_DELIVERY_TYPES,
650
+ deliveryType, isRouteNotStart,
651
+ DEFERRED_LABEL_PREFIX, DEFERRED_KINDS, deferredKind, isDeferred,
652
+ REVIEW_BY_LABEL_PREFIX, isReviewByLabel, reviewByLabelNames, parseReviewByDate,
653
+ };