@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 +19 -0
- package/README.vi.md +19 -0
- package/package.json +1 -1
- package/tools/lib/disposition.js +27 -10
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
package/tools/lib/disposition.js
CHANGED
|
@@ -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-
|
|
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-
|
|
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
|
-
|
|
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
|
|
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-
|
|
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,
|
|
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
|
};
|