@futurelastic/colab-handbook 1.19.0 → 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.0"
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}`);
@@ -11991,6 +12049,7 @@ function readForgeCiVerdict(repoAbs, fc, target, trunk) {
11991
12049
  if (!run) return unread(`${engine} commit-status read failed for ${target}@${shortSha(sha)} — cannot confirm CI`);
11992
12050
  const at = `${via}@${shortSha(run.sha || sha)} (${engine} commit status)`;
11993
12051
  let verdict = classifyCiRun(repoAbs, run, at);
12052
+ if (!verdict.ok) verdict = { ...verdict, detail: verdict.detail + notGreenNote(run) }; // #682: name the contexts
11994
12053
  if (run.status === 'none' && target === trunk) {
11995
12054
  const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
11996
12055
  if (fresh.fresh) {
@@ -12066,6 +12125,12 @@ function classifyCiRun(repoAbs, run, at) {
12066
12125
  return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) + readViaNote(run) };
12067
12126
  }
12068
12127
 
12128
+ /** #682: a forge verdict's not-green contexts, named — '' on GitHub, or when every context is green. */
12129
+ function notGreenNote(run) {
12130
+ const ng = run && Array.isArray(run.notGreen) ? run.notGreen : [];
12131
+ return ng.length ? ` — not green: ${ng.map((x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`).join(', ')}` : '';
12132
+ }
12133
+
12069
12134
  /**
12070
12135
  * #651: the runs were read from the unfiltered `actions/runs` listing because the forge's filtered
12071
12136
  * queries (`head_sha=` / `branch=`) answered nothing. The verdict is judged as usual. The note says
@@ -12278,9 +12343,16 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12278
12343
  if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
12279
12344
  else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
12280
12345
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12281
- return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha };
12346
+ // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
12347
+ // row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
12348
+ // the head has no run to judge (the stale-base row speaks for those).
12349
+ const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
12350
+ return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
12282
12351
  }
12283
12352
 
12353
+ /** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
12354
+ const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
12355
+
12284
12356
  /**
12285
12357
  * #294: WHICH paths are dirty in the trunk checkout, and — where the signal is strong enough — a
12286
12358
  * likely owner. Never a precondition: it enriches the ALREADY-COMPUTED "trunk checkout ready"
@@ -13102,6 +13174,8 @@ function cmdShipDryJson(opts) {
13102
13174
  } else {
13103
13175
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
13104
13176
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
13177
+ const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
13178
+ if (hc) checks.push({ name: BRANCH_HEAD_CI_ROW, ok: hc.ok, class: hc.ok ? null : (hc.selfClearing ? SELF_CLEARING : HUMAN_GATED), verdict: hc.verdict, detail: hc.detail });
13105
13179
  }
13106
13180
  // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
13107
13181
  // its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
@@ -14353,7 +14427,9 @@ function cmdShip(argv) {
14353
14427
  docsRowOk = row.ok && docsCi.scan.ok;
14354
14428
  } else {
14355
14429
  checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
14430
+ if (staleResult.headCi) checks.push([staleResult.headCi.ok ? '✓' : '✗', BRANCH_HEAD_CI_ROW, staleResult.headCi.detail]); // #682
14356
14431
  }
14432
+ const headCiOk = docsCi.applies || !staleResult.headCi || staleResult.headCi.ok;
14357
14433
  // #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
14358
14434
  // heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
14359
14435
  // heavy lane at all, fails the table.
@@ -14385,7 +14461,7 @@ function cmdShip(argv) {
14385
14461
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
14386
14462
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
14387
14463
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
14388
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
14464
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && headCiOk && coreOk && recOk && heavyOk;
14389
14465
 
14390
14466
  // ---- report the table ----
14391
14467
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -16556,9 +16632,13 @@ Exit codes — branch on these, never on the text:
16556
16632
  5 UNKNOWN a read failed or returned a state it cannot classify
16557
16633
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
16558
16634
 
16635
+ On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
16636
+ combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
16637
+ is a usage error there. RED and --json name the contexts that are not green (\`notGreen\`).
16638
+
16559
16639
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
16560
16640
  --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
16561
- detail, status, conclusion, url }`;
16641
+ detail, status, conclusion, url, notGreen? }`;
16562
16642
 
16563
16643
  function cmdCiWait(argv) {
16564
16644
  const opts = parseArgs(argv, {
@@ -16587,9 +16667,16 @@ function cmdCiWait(argv) {
16587
16667
  }
16588
16668
  opts.sha = full;
16589
16669
  }
16590
- if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
16670
+ // #682: a remote the engine map names as a forge (#678) is read from its commit statuses, never
16671
+ // through gh — which would answer `no known GitHub host` (exit 5) for every wait there.
16672
+ const fc = forgeCi(repoAbs);
16673
+ if (fc && runId) {
16674
+ warn(`the remote is a ${fc.kind} forge — a commit status has no run id to wait on; pass --sha <sha> [--branch <b>]`);
16675
+ return ciWait.EXIT.USAGE;
16676
+ }
16677
+ if (!fc && !git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
16591
16678
 
16592
- const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
16679
+ const target = (runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`) + (fc ? ` (${fc.kind} commit status)` : '');
16593
16680
  const apiPath = runId
16594
16681
  ? `repos/{owner}/{repo}/actions/runs/${runId}`
16595
16682
  : `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
@@ -16619,7 +16706,7 @@ function cmdCiWait(argv) {
16619
16706
  }
16620
16707
 
16621
16708
  const verifyPolicy = verifyingPolicy(repoAbs);
16622
- const poll = (etag) => {
16709
+ const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null }), fc.kind) : (etag) => {
16623
16710
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
16624
16711
  if (r.kind !== 'ok') return r;
16625
16712
  let summary;
@@ -16665,11 +16752,12 @@ function cmdCiWait(argv) {
16665
16752
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
16666
16753
  ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
16667
16754
  ...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
16755
+ ...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
16668
16756
  };
16669
16757
  if (opts.json) print(JSON.stringify(out, null, 2));
16670
16758
  else {
16671
16759
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
16672
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}`);
16760
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}${notGreenNote(s)}`);
16673
16761
  }
16674
16762
  return code;
16675
16763
  }
@@ -17902,7 +17990,9 @@ Commands:
17902
17990
  labels --ensure [--repo P] create every missing convention label (§9 step 3, #206) —
17903
17991
  idempotent, reports created vs already-there, and names every
17904
17992
  label whose description drifted (#364); --refresh-descriptions
17905
- [--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)
17906
17996
  config [show|add-repo P|rm-repo P|set K V]
17907
17997
 
17908
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) {
@@ -122,9 +122,22 @@ function create(repoAbs, eng) {
122
122
  if (page === MAX_PAGES) return null; // more statuses than we read: never a partial verdict
123
123
  }
124
124
  const rows = rowsFromPages(full, pages);
125
- return rows === null ? null : require('./git').summarizeRunsForCommit(rows, full);
125
+ if (rows === null) return null;
126
+ const summary = require('./git').summarizeRunsForCommit(rows, full);
127
+ // #682: additive — the contexts that keep this sha from green, so a refusal can name them.
128
+ const ng = notGreen(rows);
129
+ return ng.length ? { ...summary, notGreen: ng } : summary;
126
130
  },
127
131
  };
128
132
  }
129
133
 
130
- module.exports = { create, withFetcher, statusRow, rowsFromPages, PAGE_LIMIT };
134
+ /**
135
+ * #682: every context that is not `success` — still pending, or finished red — in the compact
136
+ * `{name, status, conclusion}` shape a verdict detail names them by. Pure; [] when all are green.
137
+ */
138
+ function notGreen(rows) {
139
+ return (rows || []).filter((x) => !(x.status === 'completed' && x.conclusion === 'success'))
140
+ .map((x) => ({ name: x.workflowName || 'unnamed', status: x.status, conclusion: x.conclusion || null }));
141
+ }
142
+
143
+ module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, PAGE_LIMIT };
@@ -118,6 +118,17 @@ function runState(s) {
118
118
  return 'unknown';
119
119
  }
120
120
 
121
+ /**
122
+ * #682: one poll on a forge the engine map names, from its `ciVerdict` summary (tools/lib/ci-forgejo.js)
123
+ * — the waitLoop result shape, with no ETag (a forge read is never conditional, so no 304 can pin a
124
+ * stale state). A null summary is a failed read: `error`, which ends the wait UNKNOWN, never "keep
125
+ * waiting". Pure.
126
+ */
127
+ function forgePoll(summary, engine = 'forge') {
128
+ if (!summary) return { kind: 'error', status: null, detail: `${engine} commit-status read failed` };
129
+ return { kind: 'ok', status: 200, etag: null, summary, state: runState(summary) };
130
+ }
131
+
121
132
  /**
122
133
  * #505: how many 304s in a row may stand for the state before the next poll re-reads without
123
134
  * `If-None-Match`. Measured: the runs-list read kept answering 304 for ten minutes while every run
@@ -223,6 +234,6 @@ function sleepSync(ms) {
223
234
 
224
235
  module.exports = {
225
236
  EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC, DEFAULT_MAX_NOT_MODIFIED,
226
- delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
237
+ delayFor, parseHttp, classifyResponse, restRow, runState, forgePoll, waitLoop, fmtDuration, parseDuration,
227
238
  acquireLock, sleepSync,
228
239
  };
@@ -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 : {};
@@ -77,4 +77,50 @@ function staleBaseVerdict(a) {
77
77
  'push, wait on the new run (15-minute bound), then re-run ship' };
78
78
  }
79
79
 
80
- module.exports = { staleBaseVerdict };
80
+ /**
81
+ * #682: is the branch head's OWN CI green? Read on a forge the engine map names (#678), where no
82
+ * `colab ci-wait` used to exist for code-ship B1a to classify the branch with — so a red or running
83
+ * branch head passed `colab ship --dry` as READY on the stale-base row alone (that row asks only
84
+ * whether the run saw the base). The forge's summary is the same `ciVerdict` the trunk row reads.
85
+ *
86
+ * completed / success -> green, passes
87
+ * completed / other -> red, human-gated: a branch lands only on its own green (C7.contract.03);
88
+ * whether it is red:infra (one re-run) or red:finding (send back) is B1a's
89
+ * anything unfinished -> pending, self-clearing: wait (`colab ci-wait`), then ship again
90
+ *
91
+ * Returns null where this row says nothing: no head on the remote, an unread run (the stale-base
92
+ * row already refuses that as `unread`), or no status at all (the `none` row of Branch CI governs).
93
+ * `run.notGreen` (tools/lib/ci-forgejo.js) names the contexts that keep the sha from green.
94
+ *
95
+ * @param {object} a
96
+ * @param {string|null} a.headSha - the branch head on the remote
97
+ * @param {object|null} a.run - the forge's ciVerdict summary at headSha
98
+ * @param {string} a.branch
99
+ * @param {string} [a.engine] - for the detail line, e.g. 'forgejo'
100
+ * @returns {null|{ok:boolean, verdict:'green'|'red'|'pending', selfClearing:boolean, detail:string}}
101
+ */
102
+ function branchHeadCiVerdict(a) {
103
+ const run = a && a.run;
104
+ if (!a || !a.headSha || !run || run.status === 'none') return null;
105
+ const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (${a.engine || 'forge'} commit status)`;
106
+ const ng = Array.isArray(run.notGreen) ? run.notGreen : [];
107
+ const name = (x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`;
108
+ if (run.status === 'completed' && run.conclusion === 'success') {
109
+ const n = run.runCount == null ? 1 : run.runCount;
110
+ return { ok: true, verdict: 'green', selfClearing: false, detail: `${n} context${n === 1 ? '' : 's'} at ${at}: ${n === 1 ? 'success' : 'all success'}` };
111
+ }
112
+ if (run.status === 'completed') {
113
+ const red = ng.filter((x) => x.status === 'completed');
114
+ const still = ng.filter((x) => x.status !== 'completed');
115
+ return { ok: false, verdict: 'red', selfClearing: false,
116
+ detail: `${at} is red — failing: ${red.length ? red.map(name).join(', ') : `conclusion=${run.conclusion || 'none'}`}` +
117
+ `${still.length ? `; still running: ${still.map(name).join(', ')}` : ''}. A branch lands only on its own green (C7.contract.03): ` +
118
+ 'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
119
+ }
120
+ const still = ng.filter((x) => x.status !== 'completed');
121
+ return { ok: false, verdict: 'pending', selfClearing: true,
122
+ detail: `${at} has not finished — still running: ${still.length ? still.map(name).join(', ') : `status=${run.status}`}. ` +
123
+ `Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
124
+ }
125
+
126
+ module.exports = { staleBaseVerdict, branchHeadCiVerdict };