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