@futurelastic/colab-handbook 1.19.1-rc.1 → 1.19.1-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.19.1-rc.1"
36
+ "version": "1.19.1-rc.2"
37
37
  }
package/tools/colab CHANGED
@@ -8022,7 +8022,7 @@ const DELIVERY_LABEL_COUNT = labels.conventionLabelNames()
8022
8022
  const DEFERRED_LABEL_COUNT = labels.conventionLabelNames()
8023
8023
  .filter((n) => n.startsWith(labels.DEFERRED_LABEL_PREFIX)).length;
8024
8024
 
8025
- const HELP_LABELS = `colab labels --ensure [--refresh-descriptions [--keep a,b]] [--repo P]
8025
+ const HELP_LABELS = `colab labels --ensure [--refresh-descriptions [--keep a,b]] [--relabel-deprecated] [--prune-deprecated] [--repo P]
8026
8026
 
8027
8027
  Create every convention label this repo is missing — CONVENTIONS.md §9 step 3, the ${labels.conventionLabelNames().length}-name set
8028
8028
  (${NON_DELIVERY_LABEL_NAMES.map((n) => `\`${n}\``).join(', ')}, the ${DELIVERY_LABEL_COUNT} \`delivery:*\` values, and the ${DEFERRED_LABEL_COUNT} \`deferred:*\` values),
@@ -8041,6 +8041,13 @@ used to be typed out by hand (#206).
8041
8041
  ${labels.MINIMAL_LABEL_NAMES.map((n) => `\`${n}\``).join(', ')}. For a repo the fleet does not own
8042
8042
  (CONVENTIONS.md §9, "Working in a repo you don't own") — every other
8043
8043
  label is opt-in by use there, not provisioned on someone else's tracker
8044
+ --relabel-deprecated move every OPEN issue carrying a deprecated label (${codec.DEPRECATED_LABELS.map((d) => `\`${d.name}\``).join(', ')})
8045
+ onto its replacement — add the new label, remove the old (#683). Closed
8046
+ issues keep the old label as history. Without this flag they are only reported
8047
+ --prune-deprecated delete a deprecated label from the tracker — only once its window has ended
8048
+ (${codec.HUMAN_WAIT_ALIAS_UNTIL}) AND a non-search read confirms no open issue still
8049
+ carries it. Deleting strips the label from closed issues too, so it is never
8050
+ implied by --relabel-deprecated
8044
8051
  --repo <path> repo root (default: git root of cwd)
8045
8052
 
8046
8053
  Idempotent: a label already present is never re-created and reported under "already there" —
@@ -8062,9 +8069,15 @@ rejects) — each failure is reported by name, not just a bare non-zero.
8062
8069
  function cmdLabels(argv) {
8063
8070
  const opts = parseArgs(argv, {
8064
8071
  values: { '--repo': 'repo', '--keep': 'keep' },
8065
- flags: { '--ensure': 'ensure', '--refresh-descriptions': 'refresh', '--minimal': 'minimal', '-h': 'help', '--help': 'help' },
8072
+ flags: {
8073
+ '--ensure': 'ensure', '--refresh-descriptions': 'refresh', '--minimal': 'minimal',
8074
+ '--relabel-deprecated': 'relabel', '--prune-deprecated': 'prune', '-h': 'help', '--help': 'help',
8075
+ },
8066
8076
  });
8067
8077
  if (opts.help || !opts.ensure) return print(HELP_LABELS);
8078
+ if (opts.minimal && (opts.relabel || opts.prune)) {
8079
+ throw new UserError('--relabel-deprecated / --prune-deprecated move issues onto a label --minimal does not provision — drop --minimal');
8080
+ }
8068
8081
  if (opts.keep !== undefined && !opts.refresh) {
8069
8082
  throw new UserError('--keep only means something with --refresh-descriptions — without it no description is rewritten, so there is nothing to keep');
8070
8083
  }
@@ -8135,6 +8148,51 @@ function cmdLabels(argv) {
8135
8148
  print('(CONVENTIONS.md §8, Upstream; skills/handbook-sync/SKILL.md §7).');
8136
8149
  }
8137
8150
  }
8151
+ // #683: deprecated aliases (codec.DEPRECATED_LABELS). Only a label the tracker actually has is
8152
+ // read, so a repo that never carried an old spelling costs no extra call. --minimal skips this:
8153
+ // the replacement is outside the subset it provisions.
8154
+ if (!opts.minimal) {
8155
+ const have = new Set(present.map((l) => l.name));
8156
+ const target = (name) => have.has(name) || created.includes(name);
8157
+ const day = today();
8158
+ for (const d of codec.DEPRECATED_LABELS) {
8159
+ if (!have.has(d.name)) continue;
8160
+ const v = codec.deprecatedLabelDecision(d, { today: day, open: git.ghOpenIssueNumbersByLabel(repoAbs, d.name) });
8161
+ if (v.action === 'move') {
8162
+ const list = v.open.map((n) => `#${n}`).join(', ');
8163
+ if (!opts.relabel) {
8164
+ print(`Deprecated label in use: ${d.name} on ${list} — replaced by ${d.replacedBy} (alias window ends ${d.until}).`);
8165
+ print(' Move them: colab labels --ensure --relabel-deprecated');
8166
+ continue;
8167
+ }
8168
+ if (!target(d.replacedBy)) {
8169
+ failed.push({ name: d.name, error: `${d.replacedBy} is not on the tracker, so ${list} cannot move onto it` });
8170
+ continue;
8171
+ }
8172
+ const moved = [];
8173
+ for (const n of v.open) {
8174
+ const r = git.ghIssueEdit(repoAbs, n, ['--add-label', d.replacedBy, '--remove-label', d.name]);
8175
+ if (r.ok) moved.push(`#${n}`);
8176
+ else failed.push({ name: `${d.name} on #${n}`, error: (r.stderr || '').trim() || 'gh issue edit failed' });
8177
+ }
8178
+ if (moved.length) print(`Relabelled ${d.name} → ${d.replacedBy}: ${moved.join(', ')}`);
8179
+ } else if (v.action === 'delete') {
8180
+ if (!opts.prune) {
8181
+ print(`Deprecated label ${d.name}: no open issue carries it and its window ended ${d.until} — delete it: colab labels --ensure --prune-deprecated`);
8182
+ continue;
8183
+ }
8184
+ const r = git.ghLabelDelete(repoAbs, d.name);
8185
+ if (r.ok) print(`Deleted deprecated label: ${d.name}`);
8186
+ else failed.push({ name: d.name, error: (r.stderr || '').trim() || 'gh label delete failed' });
8187
+ } else if (v.reason === 'unread') {
8188
+ const why = `could not read the open issues carrying ${d.name} — left as it is`;
8189
+ if (opts.relabel || opts.prune) failed.push({ name: d.name, error: why });
8190
+ else print(`Deprecated label ${d.name}: ${why}`);
8191
+ } else {
8192
+ print(`Deprecated label ${d.name}: no open issue carries it; kept until its window ends ${d.until}${opts.prune ? ' (--prune-deprecated deletes it only after that)' : ''}.`);
8193
+ }
8194
+ }
8195
+ }
8138
8196
  if (failed.length) {
8139
8197
  print('Failed:');
8140
8198
  for (const f of failed) print(` ${f.name} — ${f.error}`);
@@ -17932,7 +17990,9 @@ Commands:
17932
17990
  labels --ensure [--repo P] create every missing convention label (§9 step 3, #206) —
17933
17991
  idempotent, reports created vs already-there, and names every
17934
17992
  label whose description drifted (#364); --refresh-descriptions
17935
- [--keep a,b] rewrites those to the handbook's text
17993
+ [--keep a,b] rewrites those to the handbook's text;
17994
+ --relabel-deprecated moves open issues off a deprecated
17995
+ label, --prune-deprecated deletes it after its window (#683)
17936
17996
  config [show|add-repo P|rm-repo P|set K V]
17937
17997
 
17938
17998
  State is machine-local at ~/.colab/ (override with COLAB_HOME). Run any command with
@@ -34,6 +34,7 @@ const yaml = require('./yaml.js');
34
34
  const { consumerEvidence, describeEvidence } = require('./consumer-evidence.js');
35
35
  const { evaluateExposure } = require('./exposure-shape.js');
36
36
  const { UserError } = require('./util.js');
37
+ const labels = require('./codec/labels.js');
37
38
 
38
39
  const ROW_NAMES = ['tier', 'room', 'exposure', 'writes', 'channels'];
39
40
 
@@ -397,7 +398,7 @@ function remainingSteps(ctx = {}) {
397
398
  const steps = [];
398
399
  if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
399
400
  steps.push(
400
- { n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
401
+ { n: 3, text: `Create the full label set (${labels.conventionLabelNames().length} names) — \`colab labels --ensure\`, CONVENTIONS.md §9 step 3 (#206)` },
401
402
  { n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
402
403
  );
403
404
  if (ctx.fork) {
@@ -22,6 +22,15 @@ export const CONVENTION_LABELS: ConventionLabel[];
22
22
  export function conventionLabelNames(): string[];
23
23
  export function missingConventionLabels(present: LabelLike[] | null | undefined): string[];
24
24
  export function staleConventionDescriptions(present: LabelLike[] | null | undefined): { name: string; have: string; want: string }[];
25
+ /** #683: a deprecated spelling, the label replacing it, and the last day (YYYY-MM-DD) of its window. */
26
+ export interface DeprecatedLabel { name: string; replacedBy: string; until: string; }
27
+ export const HUMAN_WAIT_ALIAS_UNTIL: string;
28
+ export const DEPRECATED_LABELS: ReadonlyArray<DeprecatedLabel>;
29
+ export function deprecatedLabel(name: LabelLike): DeprecatedLabel | null;
30
+ export function deprecatedLabelDecision(entry: DeprecatedLabel, facts?: { today?: string; open?: number[] | null }):
31
+ | { action: 'move'; reason: 'open'; open: number[] }
32
+ | { action: 'delete'; reason: 'spent'; open: [] }
33
+ | { action: 'keep'; reason: 'unread' | 'window' | 'bad-date'; open: [] };
25
34
  export const MINIMAL_LABEL_NAMES: string[];
26
35
  export function minimalConventionLabels(): ConventionLabel[];
27
36
 
@@ -213,6 +213,15 @@
213
213
  * malignant-absence reason above: the moment a human wants to veto is a test period that is
214
214
  * already counting down, and a label the repo never created cannot be applied in that moment —
215
215
  * the veto would silently not exist. Only a human removes it; no command in this repo does.
216
+ *
217
+ * `blocked:needs-human` joined the set in #683: the park label for "waits until a person decides
218
+ * or acts" — the label form of the `needs-human` disposition (tools/lib/disposition.js). Before
219
+ * it the wait had two role-named spellings (DEPRECATED_LABELS below), neither provisioned, so
220
+ * adopters hand-created them with different colours and descriptions, and on an install where
221
+ * the person who lifts the park is not the install's owner the name pointed at someone else.
222
+ * Provisioned for the malignant-absence reason above: a park a session wants to record must be
223
+ * appliable at that moment. Not in MINIMAL_LABEL_NAMES — a session's start → wrap → ship path
224
+ * does not write it.
216
225
  */
217
226
 
218
227
  const CONVENTION_LABELS = [
@@ -239,8 +248,55 @@ const CONVENTION_LABELS = [
239
248
  { name: 'deferred:measurement', color: '7C6F57', description: 'Parked until a metric crosses a threshold — name the metric and the threshold on the issue' },
240
249
  { name: 'deferred:external-party', color: '6E5494', description: 'Parked until someone outside this repo acts — name who, and pair with review-by:<date>' },
241
250
  { name: 'release-hold', color: 'E11D21', description: 'Human veto on a release tracking issue: its candidate is not finalized while this is present' },
251
+ { name: 'blocked:needs-human', color: 'D93F0B', description: 'Parked until a person decides or acts — a decision or an act only a person can give' },
242
252
  ];
243
253
 
254
+ // The label alias table (#683) — deprecated spellings of a convention label, each with the label
255
+ // that replaces it and the last day of its migration window (YYYY-MM-DD). Read, never written:
256
+ // nothing in this repo applies one. `colab labels --ensure` reports open issues still carrying
257
+ // one, `--relabel-deprecated` moves them, and `--prune-deprecated` deletes the old label once the
258
+ // window is over (deprecatedLabelDecision below). The window is a DATE, not a release count:
259
+ // minor releases here ship days apart, so a release-counted window would close before most
260
+ // adopters had synced once. Dropping an entry is a separate change, made after its date.
261
+ const HUMAN_WAIT_ALIAS_UNTIL = '2027-01-06';
262
+ const DEPRECATED_LABELS = Object.freeze([
263
+ Object.freeze({ name: 'blocked:needs-owner', replacedBy: 'blocked:needs-human', until: HUMAN_WAIT_ALIAS_UNTIL }),
264
+ Object.freeze({ name: 'blocked:needs-boss', replacedBy: 'blocked:needs-human', until: HUMAN_WAIT_ALIAS_UNTIL }),
265
+ ]);
266
+
267
+ /** The DEPRECATED_LABELS entry for `name`, or null. Tolerant of a label object or a bare string. */
268
+ function deprecatedLabel(name) {
269
+ const s = name && typeof name === 'object' ? name.name : name;
270
+ return DEPRECATED_LABELS.find((d) => d.name === s) || null;
271
+ }
272
+
273
+ /**
274
+ * What to do with one deprecated label on one tracker — pure, so the clock and the tracker read
275
+ * are both inputs (#683). `entry` is a DEPRECATED_LABELS row, `today` a YYYY-MM-DD string, `open`
276
+ * the open issue numbers carrying the label from a NON-search read (null = could not read).
277
+ *
278
+ * Returns { action, reason, open }:
279
+ * - `move` — open issues carry it: relabel them onto `entry.replacedBy`. Moving is always
280
+ * allowed, inside the window or after it.
281
+ * - `delete` — the window is over (today is after `until`) AND the read confirms no open issue
282
+ * carries it: the label object may be deleted.
283
+ * - `keep` — anything else: `unread` (the read failed — never read as "none open"), `window`
284
+ * (still inside the window; aliases are guaranteed until `until`), `bad-date`.
285
+ *
286
+ * Deleting a label object strips it from closed issues too and cannot be undone from the tracker,
287
+ * so every unclear input keeps — the same posture as group-labels.js's spent-label teardown.
288
+ */
289
+ function deprecatedLabelDecision(entry, { today, open } = {}) {
290
+ if (!Array.isArray(open)) return { action: 'keep', reason: 'unread', open: [] };
291
+ if (open.length) return { action: 'move', reason: 'open', open: [...open] };
292
+ const day = /^\d{4}-\d{2}-\d{2}$/;
293
+ if (!entry || !day.test(String(entry.until)) || !day.test(String(today))) {
294
+ return { action: 'keep', reason: 'bad-date', open: [] };
295
+ }
296
+ if (today <= entry.until) return { action: 'keep', reason: 'window', open: [] };
297
+ return { action: 'delete', reason: 'spent', open: [] };
298
+ }
299
+
244
300
  // The DELIVERY label prefix (CONVENTIONS.md §5, Delivery type). Six fixed values, unlike
245
301
  // `group:<key>` — provisioned up front in CONVENTION_LABELS above, not created on demand.
246
302
  const DELIVERY_LABEL_PREFIX = 'delivery:';
@@ -707,6 +763,7 @@ function encodeLabel(label) {
707
763
 
708
764
  module.exports = {
709
765
  CONVENTION_LABELS, conventionLabelNames, missingConventionLabels, staleConventionDescriptions,
766
+ HUMAN_WAIT_ALIAS_UNTIL, DEPRECATED_LABELS, deprecatedLabel, deprecatedLabelDecision,
710
767
  MINIMAL_LABEL_NAMES, minimalConventionLabels,
711
768
  READINESS_LABEL, readinessLabelArgs, readinessMissingLabelHint, readinessMarkedMessage,
712
769
  TRACKING_LABEL,
@@ -105,6 +105,14 @@
105
105
  "known": true
106
106
  }
107
107
  },
108
+ {
109
+ "wire": "blocked:needs-human",
110
+ "decoded": {
111
+ "kind": "convention",
112
+ "value": "blocked:needs-human",
113
+ "known": true
114
+ }
115
+ },
108
116
  {
109
117
  "wire": "graph-empty",
110
118
  "decoded": {
@@ -69,19 +69,21 @@ const HUMAN = 'human';
69
69
  * GitHub's close reason takes. Frozen and closed: a kind outside this list is not a disposition
70
70
  * with an unknown authority, it is not a disposition.
71
71
  */
72
- const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-owner', 'not planned', 'leave']);
72
+ const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-human', 'not planned', 'leave']);
73
73
 
74
74
  /**
75
- * #609 — names this module still READS but never writes. `needs-owner` replaced `needs-boss`
76
- * ("Boss" named one deployment's human; the standard is for any owner). During the switch a
77
- * reader must accept both, or an issue marked under the old name reads as unrecognised — "not
78
- * cleared" — to a tool that only knows the new one. Each legacy name classifies exactly like the
79
- * kind it maps to. Kept out of KINDS / TOKENS / TOKEN_BY_KIND on purpose: those are what a writer
80
- * may emit, and `formatMarker` refuses a legacy kind. Drop an entry once the old name has had no
81
- * open use for its window (a separate issue, filed then).
75
+ * #609, #683 — the alias table: names this module still READS but never writes. The person-wait
76
+ * kind is `needs-human` — it names the wait, not a role, so it reads right on any install,
77
+ * whoever lifts the park. Both older names are deprecated aliases of it. During the switch a
78
+ * reader must accept them, or an issue marked under an old name reads as unrecognised — "not
79
+ * cleared" — to a tool that only knows the new one. Each alias classifies exactly like the kind
80
+ * it maps to. Kept out of KINDS / TOKENS / TOKEN_BY_KIND on purpose: those are what a writer may
81
+ * emit, and `formatMarker` refuses an alias. The window the aliases are guaranteed for is the
82
+ * label alias table's date (`HUMAN_WAIT_ALIAS_UNTIL`, tools/lib/codec/labels.js). Reading does
83
+ * not stop at that date; dropping an entry is a separate change, made after it.
82
84
  */
83
- const LEGACY_KINDS = Object.freeze({ 'needs-boss': 'needs-owner' });
84
- const LEGACY_TOKENS = Object.freeze({ 'needs-boss': 'needs-owner' });
85
+ const LEGACY_KINDS = Object.freeze({ 'needs-owner': 'needs-human', 'needs-boss': 'needs-human' });
86
+ const LEGACY_TOKENS = Object.freeze({ 'needs-owner': 'needs-human', 'needs-boss': 'needs-human' });
85
87
 
86
88
  /**
87
89
  * The same seven by MARKER TOKEN. No token is a prefix or a decorated variant of another — the
@@ -94,13 +96,13 @@ const TOKEN_BY_KIND = Object.freeze({
94
96
  split: 'split',
95
97
  'routed-out': 'routed-out',
96
98
  hold: 'hold',
97
- 'needs-owner': 'needs-owner',
99
+ 'needs-human': 'needs-human',
98
100
  'not planned': 'not-planned',
99
101
  leave: 'leave',
100
102
  });
101
103
  const KIND_BY_TOKEN = Object.freeze({
102
104
  ...Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind])),
103
- ...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609)
105
+ ...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609, #683)
104
106
  });
105
107
  const TOKENS = Object.freeze(Object.values(TOKEN_BY_KIND));
106
108
 
@@ -348,11 +350,11 @@ function classify(facts) {
348
350
  : verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
349
351
  }
350
352
 
351
- case 'needs-owner':
353
+ case 'needs-human':
352
354
  // Record-first: the pass writes the question down with the apply lever pre-filled and moves
353
355
  // on. It does not stop and wait, and it never applies this itself.
354
356
  return verdict(kind, HUMAN, true,
355
- 'never applied by an agent — the agent records the question, the owner answers, the issue returns to intake', []);
357
+ 'never applied by an agent — the agent records the question, a person answers, the issue returns to intake', []);
356
358
 
357
359
  case 'not planned': {
358
360
  const sup = f.supersededBy && typeof f.supersededBy === 'object' ? f.supersededBy : {};