@futurelastic/colab-handbook 1.13.0-rc.12 → 1.13.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 +13 -13
- package/README.vi.md +14 -14
- package/package.json +1 -1
- package/tools/colab +20 -17
- package/tools/lib/codec/claim.js +6 -3
package/README.md
CHANGED
|
@@ -20,9 +20,9 @@ colab labels --ensure # creates the convention labels
|
|
|
20
20
|
colab register # adds the repo to this machine's fleet list
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
Then, in an agent session in that repo, run
|
|
24
|
-
|
|
25
|
-
agent at hand,
|
|
23
|
+
Then, in an agent session in that repo, run the `code-start` skill with an issue
|
|
24
|
+
number — each engine has its own way to invoke a skill, see [*Choose your engine*](#choose-your-engine).
|
|
25
|
+
With an agent at hand, the `handbook-sync` skill replaces the last three commands and also does
|
|
26
26
|
the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
|
|
27
27
|
You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
|
|
28
28
|
packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
|
|
@@ -95,19 +95,19 @@ with no agent and no other tool.
|
|
|
95
95
|
|
|
96
96
|
## Your first session
|
|
97
97
|
|
|
98
|
-
A unit of work goes round one loop. Each step is a skill, invoked in an
|
|
99
|
-
session
|
|
100
|
-
[`skills/`](skills/).
|
|
98
|
+
A unit of work goes round one loop. Each step is a skill, invoked by name in an
|
|
99
|
+
agent session (the syntax is the engine's — [*Choose your engine*](#choose-your-engine)),
|
|
100
|
+
or followed by hand from [`skills/`](skills/).
|
|
101
101
|
|
|
102
102
|
| Step | Skill | Who runs it | What it leaves behind |
|
|
103
103
|
|---|---|---|---|
|
|
104
|
-
| 1. Pick |
|
|
105
|
-
| 2. Open |
|
|
104
|
+
| 1. Pick | `code-triage` | coordinator | the ready work in order, `group:` labels on issues that must share a branch, `needs-plan` on hard ones, the start commands |
|
|
105
|
+
| 2. Open | `code-start <N>` | implementer | the issue claimed, a branch cut from trunk and pushed, a worktree, a short plan file |
|
|
106
106
|
| 3. Work | — | implementer | commits on the branch |
|
|
107
|
-
| 4. Hand off |
|
|
108
|
-
| 5. Merge |
|
|
109
|
-
| 6. Clean up |
|
|
110
|
-
| 7. Release | release workflow, or
|
|
107
|
+
| 4. Hand off | `code-wrap` | implementer | what was learned written onto the Issue, the repo's gate run, the branch pushed — then it **stops** |
|
|
108
|
+
| 5. Merge | `code-ship` | coordinator, after a human go | one squash commit on trunk with `Closes #N`, evidence on each issue, claims released, the worktree removed |
|
|
109
|
+
| 6. Clean up | `code-sweep` | coordinator | finished work shipped, stale claims and worktrees cleared |
|
|
110
|
+
| 7. Release | release workflow, or `release-rung` | automatic, or a human where a tag deploys | a candidate tag, then the final after a test period — only where the repo's `exposure` has releases |
|
|
111
111
|
|
|
112
112
|
Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
|
|
113
113
|
`code-start` when flagged), `handbook-sync` (bring one repo up to the current
|
|
@@ -166,7 +166,7 @@ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
|
|
|
166
166
|
|
|
167
167
|
## Adopting it into a repo
|
|
168
168
|
|
|
169
|
-
**The default route: run
|
|
169
|
+
**The default route: run the `handbook-sync` skill in an agent session inside the repo.**
|
|
170
170
|
It sees that nothing is adopted yet and drives adoption to the end — the
|
|
171
171
|
descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
|
|
172
172
|
the templates, and registration on this machine. Run later, the same skill
|
package/README.vi.md
CHANGED
|
@@ -19,9 +19,9 @@ colab labels --ensure # tạo các label quy ước
|
|
|
19
19
|
colab register # đưa repo vào danh sách fleet của máy này
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
Sau đó, trong một phiên agent ở repo đó, chạy
|
|
23
|
-
|
|
24
|
-
trong tay thì
|
|
22
|
+
Sau đó, trong một phiên agent ở repo đó, chạy skill `code-start` kèm số issue —
|
|
23
|
+
mỗi engine có cách gọi skill riêng, xem [*Chọn engine*](#chọn-engine). Có agent
|
|
24
|
+
trong tay thì skill `handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
|
|
25
25
|
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
26
26
|
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
27
27
|
hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
|
|
@@ -94,19 +94,19 @@ khác.
|
|
|
94
94
|
|
|
95
95
|
## Phiên làm việc đầu tiên
|
|
96
96
|
|
|
97
|
-
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi trong phiên
|
|
98
|
-
|
|
99
|
-
[`skills/`](skills/).
|
|
97
|
+
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
|
|
98
|
+
agent (cú pháp gọi là của engine — [*Chọn engine*](#chọn-engine)), hoặc tự làm
|
|
99
|
+
theo bằng tay từ [`skills/`](skills/).
|
|
100
100
|
|
|
101
101
|
| Bước | Skill | Ai chạy | Để lại gì |
|
|
102
102
|
|---|---|---|---|
|
|
103
|
-
| 1. Chọn |
|
|
104
|
-
| 2. Mở |
|
|
103
|
+
| 1. Chọn | `code-triage` | điều phối | việc sẵn sàng theo thứ tự, label `group:` trên các issue phải chung một nhánh, `needs-plan` trên việc khó, lệnh để bắt đầu |
|
|
104
|
+
| 2. Mở | `code-start <N>` | thợ | issue đã claim, nhánh cắt từ trunk và đã push, một worktree, một file plan ngắn |
|
|
105
105
|
| 3. Làm | — | thợ | commit trên nhánh |
|
|
106
|
-
| 4. Bàn giao |
|
|
107
|
-
| 5. Merge |
|
|
108
|
-
| 6. Dọn |
|
|
109
|
-
| 7. Release | release workflow, hoặc
|
|
106
|
+
| 4. Bàn giao | `code-wrap` | thợ | điều học được ghi lên Issue, gate của repo đã chạy, nhánh đã push — rồi **dừng** |
|
|
107
|
+
| 5. Merge | `code-ship` | điều phối, sau khi người đồng ý | một squash commit trên trunk kèm `Closes #N`, bằng chứng trên từng issue, claim đã nhả, worktree đã gỡ |
|
|
108
|
+
| 6. Dọn | `code-sweep` | điều phối | việc đã xong được ship, claim và worktree cũ được dọn |
|
|
109
|
+
| 7. Release | release workflow, hoặc `release-rung` | tự động, hoặc người khi tag là thứ deploy | một tag ứng viên, rồi bản final sau thời gian thử — chỉ khi `exposure` của repo có release |
|
|
110
110
|
|
|
111
111
|
Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
|
|
112
112
|
`code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
|
|
@@ -166,8 +166,8 @@ sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
|
|
|
166
166
|
|
|
167
167
|
## Adopt vào một repo
|
|
168
168
|
|
|
169
|
-
**Đường mặc định: chạy
|
|
170
|
-
đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
|
|
169
|
+
**Đường mặc định: chạy skill `handbook-sync` trong một phiên agent ngay trong
|
|
170
|
+
repo đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
|
|
171
171
|
`colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
|
|
172
172
|
này. Chạy lại về sau, chính skill đó kéo một repo đã adopt lên bản handbook mới
|
|
173
173
|
nhất mà không làm mất phần bạn đã sửa.
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -283,8 +283,9 @@ function commentHost(repoAbs) {
|
|
|
283
283
|
function myMachineId() { return machine.localMachine().id || null; }
|
|
284
284
|
|
|
285
285
|
/**
|
|
286
|
-
* Resolve the
|
|
287
|
-
* a DERIVED person identity (#528) > '' (absent, never an error). Free-form —
|
|
286
|
+
* Resolve the session id for this invocation: --session flag > COLAB_SESSION env >
|
|
287
|
+
* a DERIVED person identity (#528) > '' (absent, never an error). Free-form — any stable id for
|
|
288
|
+
* the session (a URL, a uuid…).
|
|
288
289
|
*
|
|
289
290
|
* The derived step exists for a person at a plain terminal, who has no session runtime and so no
|
|
290
291
|
* id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
|
|
@@ -390,7 +391,7 @@ function warnWeakIdentity(session, sessionName, what, ref) {
|
|
|
390
391
|
warn(`no --session or --session-name given — this ${what} will carry NO holder identity.`);
|
|
391
392
|
warn(` A live hold's refusal can then only point at its process id, and this acquire will`);
|
|
392
393
|
warn(` not be recognized as your own on a later re-acquire without one.`);
|
|
393
|
-
if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <
|
|
394
|
+
if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <id>`);
|
|
394
395
|
return;
|
|
395
396
|
}
|
|
396
397
|
// #326: a planner intent id is a deliberate, documented non-URL value — not a mistyped name.
|
|
@@ -401,16 +402,16 @@ function warnWeakIdentity(session, sessionName, what, ref) {
|
|
|
401
402
|
// refused the caller's own hold when they later presented their REAL url. Warn, never
|
|
402
403
|
// refuse: `requirePlaceIdentity` promises `<url-or-any-stable-id>`, so a bare stable id is
|
|
403
404
|
// a blessed value and rejecting it would break that contract and every adopter using one.
|
|
404
|
-
warn(`--session "${session}" does not look like a session URL
|
|
405
|
+
warn(`--session "${session}" does not look like a session id (a URL, a uuid, a session_… token) — this ${what}`);
|
|
405
406
|
warn(` will record it verbatim. That is allowed (any stable id works), but if this is your`);
|
|
406
407
|
warn(` session NAME you probably meant --session-name: a later 'colab place release'`);
|
|
407
|
-
warn(` presenting your real
|
|
408
|
+
warn(` presenting your real id will NOT match this value and will be refused (#306).`);
|
|
408
409
|
return;
|
|
409
410
|
}
|
|
410
411
|
if (!sessionName || session) return;
|
|
411
|
-
warn(`session name "${sessionName}" recorded with NO session
|
|
412
|
-
warn(` but cannot be traced to a session. The name is display text; the
|
|
413
|
-
if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <
|
|
412
|
+
warn(`session name "${sessionName}" recorded with NO session id — this ${what} will read as owned`);
|
|
413
|
+
warn(` but cannot be traced to a session. The name is display text; the id is the join key.`);
|
|
414
|
+
if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <id>`);
|
|
414
415
|
}
|
|
415
416
|
|
|
416
417
|
/**
|
|
@@ -469,8 +470,8 @@ function identityCell(sessionName, session) {
|
|
|
469
470
|
/** Print the `(!)` legend under a table, only when at least one row carries a half-identity. */
|
|
470
471
|
function identityLegend(entries) {
|
|
471
472
|
if (!entries.some((e) => e && e.sessionName && !e.session)) return;
|
|
472
|
-
print(' (!) session NAME with no session
|
|
473
|
-
print(' Repair: colab worktree tag <worktree> --session <
|
|
473
|
+
print(' (!) session NAME with no session id — reads as owned, links to nothing.');
|
|
474
|
+
print(' Repair: colab worktree tag <worktree> --session <id>');
|
|
474
475
|
}
|
|
475
476
|
|
|
476
477
|
/**
|
|
@@ -918,7 +919,8 @@ Options:
|
|
|
918
919
|
--branch <name> branch these claims are worked on. Default: none (null) — a claim held on
|
|
919
920
|
the trunk checkout has no branch. Never the word "trunk": that is a role,
|
|
920
921
|
and a record holding it resolves to no ref (refused, exit 1)
|
|
921
|
-
--session <
|
|
922
|
+
--session <id> any stable id for this session (a URL, a uuid…), recorded on the claim + comment
|
|
923
|
+
(default: COLAB_SESSION env).
|
|
922
924
|
MANDATORY when no --worktree is given (#242): a claim with no worktree takes
|
|
923
925
|
the trunk-checkout place-claim, and a blank session can never be recognized
|
|
924
926
|
as its own later re-acquire — refused (exit 1) before anything is read/written.
|
|
@@ -2798,7 +2800,7 @@ function cmdGateHermetic(argv) {
|
|
|
2798
2800
|
// neither, so there is nothing else in state.json a second solo attempt could collide with.
|
|
2799
2801
|
// ---------------------------------------------------------------------------
|
|
2800
2802
|
|
|
2801
|
-
const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <
|
|
2803
|
+
const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <id>] [--session-name <name>]
|
|
2802
2804
|
colab solo --done [--repo <path>]
|
|
2803
2805
|
|
|
2804
2806
|
Entry gate for solo flow (CONVENTIONS.md, Solo flow) — requires BOTH: this repo does not declare
|
|
@@ -3073,7 +3075,7 @@ function cmdSoloDone(repoAbs, doc) {
|
|
|
3073
3075
|
// exactly `writes: isolated` — see writes-authority.js's `trunkDirectVetoed`)
|
|
3074
3076
|
// ---------------------------------------------------------------------------
|
|
3075
3077
|
|
|
3076
|
-
const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session
|
|
3078
|
+
const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session ID] [--session-name N] [--force]
|
|
3077
3079
|
|
|
3078
3080
|
Path-scoped, machine-local hold on ONE checkout (CONVENTIONS.md, Place-claims) — what a shared
|
|
3079
3081
|
trunk checkout needs on any repo that does not declare \`writes: isolated\` (the veto), and a
|
|
@@ -5235,7 +5237,8 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
|
|
|
5235
5237
|
<type>/, prefix or not; else the branch after its first '/')
|
|
5236
5238
|
--trunk <name> override trunk branch
|
|
5237
5239
|
--repo <path> repo root (default: git root of cwd)
|
|
5238
|
-
--session <
|
|
5240
|
+
--session <id> any stable id for this session (a URL, a uuid…), recorded on the worktree +
|
|
5241
|
+
its claims (env COLAB_SESSION)
|
|
5239
5242
|
--session-name <s> short human label for tables/messages (env COLAB_SESSION_NAME)
|
|
5240
5243
|
--pid <n|none> the new worktree's place-claim liveness anchor (#288) — same meaning as
|
|
5241
5244
|
\`colab claim\`'s --pid; default: auto-detect (env COLAB_PLACE_PID too)
|
|
@@ -5262,7 +5265,7 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
|
|
|
5262
5265
|
and state record in place for a retry, unless --force. Refuses if there are
|
|
5263
5266
|
uncommitted TRACKED changes unless --force.
|
|
5264
5267
|
|
|
5265
|
-
colab worktree tag <name> --session <
|
|
5268
|
+
colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]
|
|
5266
5269
|
REPAIR session identity, and/or the recorded branch, on a worktree that already
|
|
5267
5270
|
exists — and on every claim attached to it (claims hold their own copy of each
|
|
5268
5271
|
field, and claims are what \`doctor\` reports and what \`ship\` unions by). Pass any
|
|
@@ -5886,7 +5889,7 @@ function cmdWorktreeRm(argv) {
|
|
|
5886
5889
|
}
|
|
5887
5890
|
|
|
5888
5891
|
/**
|
|
5889
|
-
* `colab worktree tag <name> --session <
|
|
5892
|
+
* `colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]` — repair
|
|
5890
5893
|
* session identity, and/or the recorded branch, on an ALREADY-created worktree. Before this, the
|
|
5891
5894
|
* only fix was hand-editing ~/.colab/state.json.
|
|
5892
5895
|
*
|
|
@@ -5920,7 +5923,7 @@ function cmdWorktreeTag(argv) {
|
|
|
5920
5923
|
const sessionName = String(opts.sessionName || '').trim();
|
|
5921
5924
|
const branch = String(opts.branch || '').trim();
|
|
5922
5925
|
if (!session && !sessionName && !branch) {
|
|
5923
|
-
throw new UserError('Nothing to tag — pass --session <
|
|
5926
|
+
throw new UserError('Nothing to tag — pass --session <id>, --session-name <s>, and/or --branch <b>');
|
|
5924
5927
|
}
|
|
5925
5928
|
if (!state.loadState().worktrees[name]) {
|
|
5926
5929
|
throw new UserError(`No worktree "${name}" in state (list them with: colab worktrees)`);
|
package/tools/lib/codec/claim.js
CHANGED
|
@@ -35,15 +35,18 @@ const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
|
|
|
35
35
|
const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
|
|
36
36
|
|
|
37
37
|
/**
|
|
38
|
-
* Does `v` look like a session URL
|
|
39
|
-
* (#306), not a gate — claim-identity.js re-exports this one copy of it.
|
|
38
|
+
* Does `v` look like a session id — a URL, a `session_…` token, a bare uuid — rather than a display
|
|
39
|
+
* name? A SHAPE heuristic (#306), not a gate — claim-identity.js re-exports this one copy of it.
|
|
40
|
+
* The uuid shape is #531: `--session` takes any stable id, and an engine whose session id is a bare
|
|
41
|
+
* uuid must not have it read back from a claim comment as a session NAME.
|
|
40
42
|
*/
|
|
41
43
|
function looksLikeSessionId(v) {
|
|
42
44
|
const s = String(v == null ? '' : v).trim();
|
|
43
45
|
if (!s) return false;
|
|
44
46
|
// #528: a derived person identity (`claim-identity.js` `derivePersonSession`) is a session id
|
|
45
47
|
// too — a stable join key, not a display name — so it reads back as one from a claim comment.
|
|
46
|
-
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s)
|
|
48
|
+
return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s)
|
|
49
|
+
|| /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
|
|
47
50
|
}
|
|
48
51
|
|
|
49
52
|
/**
|