@futurelastic/colab-handbook 1.14.0-rc.12 → 1.14.0-rc.14

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/README.md CHANGED
@@ -93,6 +93,25 @@ with no agent and no other tool.
93
93
  - **Not a maturity model.** No answer here ranks a repo above another. A repo
94
94
  with no production is not a worse repo; it is a repo with fewer gates.
95
95
 
96
+ ### Scope — and what is frozen
97
+
98
+ The handbook's scope is **how code lands on git**: tiers and exposure,
99
+ `project.yml`, branches and commits, branch CI, worktrees and ports, the git
100
+ claim ref, ship and release mechanics, CI templates, conformance, adoption and
101
+ `solo`. Since 2026-10-14
102
+ ([#604](https://github.com/futurelastic/colab-handbook/issues/604)), the surface
103
+ that decides *who holds an issue, what was decided, what may start, and who may
104
+ do an act* is **frozen**: claims recorded on the issue, readiness, `Filed-by`
105
+ provenance, decision records, and every `COLAB_HUMAN=1` gate except `solo`. It
106
+ will move to a separate decision, work and gate layer that adopters run. It
107
+ keeps working, bug fixes still land, and nothing is removed before its
108
+ replacement has run in production for 7 days. The notice heads
109
+ [`CONVENTIONS.md` §5](CONVENTIONS.md#5-claiming-work--how-to-say-im-on-this); the full
110
+ list is in [ADR 604](docs/adr/604-scope-freeze.md).
111
+
112
+ **Contributing:** a proposal for a new feature in a frozen area is refused,
113
+ with a pointer to [#604](https://github.com/futurelastic/colab-handbook/issues/604).
114
+
96
115
  ## Your first session
97
116
 
98
117
  A unit of work goes round one loop. Each step is a skill, invoked by name in an
package/README.vi.md CHANGED
@@ -92,6 +92,25 @@ khác.
92
92
  này trên repo kia. Một repo chưa có production không phải repo tệ hơn; nó là
93
93
  repo có ít cổng hơn.
94
94
 
95
+ ### Phạm vi — và phần bị đóng băng
96
+
97
+ Phạm vi của handbook là **cách code vào git**: tier và exposure,
98
+ `project.yml`, branch và commit, CI của branch, worktree và port, claim ref
99
+ trên git, cơ chế ship và release, template CI, kiểm tra tuân thủ, adopt và
100
+ `solo`. Từ 2026-10-14
101
+ ([#604](https://github.com/futurelastic/colab-handbook/issues/604)), phần quyết
102
+ định *ai giữ issue, đã quyết gì, việc gì được bắt đầu, và ai được làm một hành
103
+ động* bị **đóng băng**: claim ghi trên issue, readiness, provenance `Filed-by`,
104
+ decision record, và mọi cổng `COLAB_HUMAN=1` trừ `solo`. Phần này sẽ chuyển
105
+ sang một lớp quyết định, công việc và cổng riêng do bên adopt tự chạy. Nó vẫn
106
+ chạy, bug fix vẫn được nhận, và không gì bị gỡ trước khi phần thay thế đã chạy
107
+ production đủ 7 ngày. Thông báo nằm ở đầu
108
+ [`CONVENTIONS.md` §5](CONVENTIONS.md#5-claiming-work--how-to-say-im-on-this); danh sách
109
+ đầy đủ ở [ADR 604](docs/adr/604-scope-freeze.md).
110
+
111
+ **Đóng góp:** đề xuất tính năng mới trong vùng bị đóng băng sẽ bị từ chối, kèm
112
+ đường dẫn tới [#604](https://github.com/futurelastic/colab-handbook/issues/604).
113
+
95
114
  ## Phiên làm việc đầu tiên
96
115
 
97
116
  Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi theo tên trong phiên
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.0-rc.12"
36
+ "version": "1.14.0-rc.14"
37
37
  }
@@ -69,7 +69,19 @@ 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-boss', 'not planned', 'leave']);
72
+ const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-owner', 'not planned', 'leave']);
73
+
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).
82
+ */
83
+ const LEGACY_KINDS = Object.freeze({ 'needs-boss': 'needs-owner' });
84
+ const LEGACY_TOKENS = Object.freeze({ 'needs-boss': 'needs-owner' });
73
85
 
74
86
  /**
75
87
  * The same seven by MARKER TOKEN. No token is a prefix or a decorated variant of another — the
@@ -82,13 +94,14 @@ const TOKEN_BY_KIND = Object.freeze({
82
94
  split: 'split',
83
95
  'routed-out': 'routed-out',
84
96
  hold: 'hold',
85
- 'needs-boss': 'needs-boss',
97
+ 'needs-owner': 'needs-owner',
86
98
  'not planned': 'not-planned',
87
99
  leave: 'leave',
88
100
  });
89
- const KIND_BY_TOKEN = Object.freeze(
90
- Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind]))
91
- );
101
+ const KIND_BY_TOKEN = Object.freeze({
102
+ ...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)
104
+ });
92
105
  const TOKENS = Object.freeze(Object.values(TOKEN_BY_KIND));
93
106
 
94
107
  /**
@@ -149,7 +162,10 @@ function parseMarker(text) {
149
162
  if (typeof text !== 'string' || text === '') return null;
150
163
  const tokens = [...text.matchAll(new RegExp(MARKER_PATTERN, 'g'))].map((m) => m[1]);
151
164
  if (tokens.length === 0) return null;
152
- const distinct = [...new Set(tokens)];
165
+ // Distinct by the KIND a token reads as, so a legacy token and its current spelling (#609) are
166
+ // one proposal, not two; an unrecognised token stays distinct by its own spelling.
167
+ const distinct = [...new Set(tokens.map((t) => (
168
+ Object.prototype.hasOwnProperty.call(LEGACY_TOKENS, t) ? TOKEN_BY_KIND[LEGACY_TOKENS[t]] : t)))];
153
169
  if (distinct.length > 1) {
154
170
  return { token: null, kind: null, recognised: false, why: `${distinct.length} markers proposing different dispositions` };
155
171
  }
@@ -251,9 +267,10 @@ function verdict(kind, authority, applicable, why, blockers, extra) {
251
267
  */
252
268
  function classify(facts) {
253
269
  const f = facts && typeof facts === 'object' ? facts : {};
254
- const kind = f.kind !== undefined && f.kind !== null
270
+ const named = f.kind !== undefined && f.kind !== null
255
271
  ? f.kind
256
272
  : (f.token !== undefined && f.token !== null ? KIND_BY_TOKEN[f.token] : undefined);
273
+ const kind = Object.prototype.hasOwnProperty.call(LEGACY_KINDS, named) ? LEGACY_KINDS[named] : named;
257
274
 
258
275
  if (!KINDS.includes(kind)) {
259
276
  return verdict(null, HUMAN, false, 'not a recognised disposition — not cleared, never a default', []);
@@ -331,11 +348,11 @@ function classify(facts) {
331
348
  : verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
332
349
  }
333
350
 
334
- case 'needs-boss':
351
+ case 'needs-owner':
335
352
  // Record-first: the pass writes the question down with the apply lever pre-filled and moves
336
353
  // on. It does not stop and wait, and it never applies this itself.
337
354
  return verdict(kind, HUMAN, true,
338
- 'never applied by an agent — the agent records the question, Boss answers, the issue returns to intake', []);
355
+ 'never applied by an agent — the agent records the question, the owner answers, the issue returns to intake', []);
339
356
 
340
357
  case 'not planned': {
341
358
  const sup = f.supersededBy && typeof f.supersededBy === 'object' ? f.supersededBy : {};
@@ -375,7 +392,7 @@ function classify(facts) {
375
392
 
376
393
  module.exports = {
377
394
  AGENT, HUMAN,
378
- KINDS, TOKENS, TOKEN_BY_KIND, KIND_BY_TOKEN,
395
+ KINDS, TOKENS, TOKEN_BY_KIND, KIND_BY_TOKEN, LEGACY_KINDS, LEGACY_TOKENS,
379
396
  ASSERTS_AN_OUTCOME, SKIP_FENCE_CLASSES, EVIDENCE_FIELDS, HOLD_STALE_DAYS, MARKER_PATTERN,
380
397
  parseMarker, formatMarker, evidenceShape, axisPermits, classify,
381
398
  };