@futurelastic/colab-handbook 1.13.0-rc.9 → 1.13.0
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 +50 -20
- package/README.vi.md +53 -23
- package/audit/audit.mjs +116 -15
- package/package.json +1 -1
- package/templates/README.md +1 -1
- package/templates/ci-laravel.yml +72 -5
- package/templates/ci-node.yml +74 -6
- package/templates/ci-python.yml +74 -6
- package/templates/release-auto.yml +68 -4
- package/tools/colab +784 -91
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +277 -0
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +6 -1
- package/tools/lib/codec/claim.js +6 -3
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/git.js +70 -15
- package/tools/lib/install-check.js +77 -5
- package/tools/lib/journal.js +3 -0
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
- package/tools/lib/release-cut.js +39 -3
- package/tools/lib/release-finalize.js +110 -15
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/ship-batch.js +109 -2
- package/tools/lib/shipguard.js +12 -1
- package/tools/lib/thresholds.js +110 -0
- package/tools/lib/verify-runs.js +117 -4
package/README.md
CHANGED
|
@@ -13,15 +13,16 @@ This file is for humans.
|
|
|
13
13
|
|
|
14
14
|
```sh
|
|
15
15
|
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
16
|
-
cd ~/code/colab-handbook && ./install.sh --all # skills + colab CLI + hooks, from the newest release; --dry shows it first
|
|
16
|
+
cd ~/code/colab-handbook && ./install.sh --all # asks which coding agent gets the skills; + colab CLI + hooks, from the newest release; --dry shows it first
|
|
17
17
|
cd /path/to/your-repo
|
|
18
18
|
colab adopt # asks only what it cannot detect, writes .github/project.yml
|
|
19
19
|
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
|
-
|
|
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
|
|
25
26
|
the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
|
|
26
27
|
You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
|
|
27
28
|
packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
|
|
@@ -94,19 +95,19 @@ with no agent and no other tool.
|
|
|
94
95
|
|
|
95
96
|
## Your first session
|
|
96
97
|
|
|
97
|
-
A unit of work goes round one loop. Each step is a skill, invoked in an
|
|
98
|
-
session
|
|
99
|
-
[`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/).
|
|
100
101
|
|
|
101
102
|
| Step | Skill | Who runs it | What it leaves behind |
|
|
102
103
|
|---|---|---|---|
|
|
103
|
-
| 1. Pick |
|
|
104
|
-
| 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 |
|
|
105
106
|
| 3. Work | — | implementer | commits on the branch |
|
|
106
|
-
| 4. Hand off |
|
|
107
|
-
| 5. Merge |
|
|
108
|
-
| 6. Clean up |
|
|
109
|
-
| 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 |
|
|
110
111
|
|
|
111
112
|
Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
|
|
112
113
|
`code-start` when flagged), `handbook-sync` (bring one repo up to the current
|
|
@@ -165,7 +166,7 @@ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
|
|
|
165
166
|
|
|
166
167
|
## Adopting it into a repo
|
|
167
168
|
|
|
168
|
-
**The default route: run
|
|
169
|
+
**The default route: run the `handbook-sync` skill in an agent session inside the repo.**
|
|
169
170
|
It sees that nothing is adopted yet and drives adoption to the end — the
|
|
170
171
|
descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
|
|
171
172
|
the templates, and registration on this machine. Run later, the same skill
|
|
@@ -243,8 +244,9 @@ migration hold with or without it.
|
|
|
243
244
|
| [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
|
|
244
245
|
| [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. Nothing is called remotely — copy it, edit it, own it. |
|
|
245
246
|
| [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Command reference: [`tools/README.md`](tools/README.md). |
|
|
246
|
-
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. What each check means: [`audit/README.md`](audit/README.md). |
|
|
247
|
-
| [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session).
|
|
247
|
+
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. What each check means: [`audit/README.md`](audit/README.md). |
|
|
248
|
+
| [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Plain `SKILL.md` folders; `install.sh` links them into each coding agent you choose. |
|
|
249
|
+
| [`engines/`](engines/) | One small data file per coding agent: where its user-level skills go, how a skill is invoked, what it supports. Adding an engine is adding a file — [`engines/README.md`](engines/README.md). |
|
|
248
250
|
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
|
|
249
251
|
|
|
250
252
|
## Setting up a machine
|
|
@@ -268,14 +270,41 @@ Later moves are explicit:
|
|
|
268
270
|
A clone with uncommitted changes is never moved, and a re-run without either
|
|
269
271
|
flag keeps whatever is checked out.
|
|
270
272
|
|
|
273
|
+
### Choose your engine
|
|
274
|
+
|
|
275
|
+
The skills are plain `SKILL.md` folders that call `git`, `gh` and `colab`; any
|
|
276
|
+
coding agent that reads skills can run them. What differs is **where each
|
|
277
|
+
agent looks for them**, so the install asks. At a terminal, `./install.sh`
|
|
278
|
+
lists the engines it knows and lets you pick one or more, with *other: give a
|
|
279
|
+
path* last. Unattended, say it with a flag:
|
|
280
|
+
|
|
281
|
+
```sh
|
|
282
|
+
./install.sh --engine claude # Claude Code → ~/.claude/skills
|
|
283
|
+
./install.sh --engine claude,codex # both
|
|
284
|
+
./install.sh --skills-dir ~/my-agent/skills # any other agent: you give its folder
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
| Engine | Skills folder | Invoke | Before the skills work there |
|
|
288
|
+
|---|---|---|---|
|
|
289
|
+
| Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Nothing. This user-level install **wins** over a repo's own `.claude/skills/<name>` of the same name (precedence is enterprise > personal > project), so rename a repo variant you want used. |
|
|
290
|
+
| OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Its default sandbox has no network, so `gh` fails: set `[sandbox_workspace_write] network_access = true` in `~/.codex/config.toml`. Values from Codex's docs; not yet verified by a clean-machine run. |
|
|
291
|
+
| anything else | `--skills-dir <path>` | the agent's own way | The agent's shell needs network access for `gh`. The folder is remembered in `~/.colab/skills-dirs`. |
|
|
292
|
+
|
|
293
|
+
A re-run with no flag and no terminal keeps every engine it finds already
|
|
294
|
+
linked, so an existing machine changes nothing. Finding none, it installs for
|
|
295
|
+
Claude Code and says so. The per-engine facts live in [`engines/`](engines/),
|
|
296
|
+
one file each — that folder is the source for the table above.
|
|
297
|
+
|
|
271
298
|
| Flag | What it does |
|
|
272
299
|
|---|---|
|
|
273
|
-
| *(none)* | Symlink `skills/` into
|
|
300
|
+
| *(none)* | Symlink `skills/` into each chosen engine's user-level folder, so they are available in every repo you open. Asks at a terminal; otherwise keeps what is linked (see [*Choose your engine*](#choose-your-engine)). |
|
|
301
|
+
| `--engine <id>[,<id>]` | Install for these engines (`claude`, `codex` — the files in `engines/`), no question asked. |
|
|
302
|
+
| `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
|
|
274
303
|
| `--tools` | The `colab` CLI twice: a **symlink** at `~/.local/bin/colab` for your sessions (it prints the `PATH` line if needed), and a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services. Also creates an empty `~/.colab/state.json` if there is none. |
|
|
275
304
|
| `--hooks` | Point this clone's git at `.githooks/`: a gitleaks secret scan and an identity scan whose vocabulary you keep outside every repo (see [`templates/README.md`](templates/README.md)). |
|
|
276
305
|
| `--fleet` | Seed `~/.colab/repos.txt` with format notes only, if absent. It stays machine-local because it names your private repos; `colab register` fills it. |
|
|
277
306
|
| `--all` | `--tools --hooks --fleet`. |
|
|
278
|
-
| `--notify-url <url>` |
|
|
307
|
+
| `--notify-url <url>` | Add `<url>` to `notifyUrl` in `~/.colab/config.json` if the key lacks it; an existing entry is never removed or rewritten. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
279
308
|
| `--release` | Check this clone out at the newest final release tag, then install. The default for a first install from a fresh clone. |
|
|
280
309
|
| `--trunk` | Check out `main` and install it, unreleased work included — the clone's `@next`. |
|
|
281
310
|
| `--dry` | Print what would happen, change nothing. Combines with the flags above. |
|
|
@@ -294,7 +323,7 @@ yet, so the default `latest` tag holds only a placeholder; install from
|
|
|
294
323
|
**`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
|
|
295
324
|
<command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
|
|
296
325
|
still `colab`. The skills are not in the package; they install from a
|
|
297
|
-
clone, because they
|
|
326
|
+
clone, because they are symlinks into its working tree.
|
|
298
327
|
|
|
299
328
|
### Checking an install
|
|
300
329
|
|
|
@@ -305,10 +334,11 @@ node audit/audit.mjs # a conformance report across every registered repo
|
|
|
305
334
|
colab update # stamped copies that fell behind, the frozen CLI included
|
|
306
335
|
```
|
|
307
336
|
|
|
308
|
-
`--check` reports
|
|
337
|
+
`--check` reports, per engine, how many skills are linked, missing or broken,
|
|
338
|
+
plus that engine's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
|
|
309
339
|
which commands it does not dispatch, whether the state file exists, whether
|
|
310
340
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
311
|
-
`notifyUrl` is unset while a local observer declared
|
|
341
|
+
`notifyUrl` is unset, or lacks a URL, while a local observer declared one. ✗ means
|
|
312
342
|
something installed is stale or unusable; ⚠ means something was never set up,
|
|
313
343
|
which may be deliberate or just not done yet — so a correct fresh install, with
|
|
314
344
|
no repo registered and no identity vocabulary, reports ⚠ rows and exits 0. It
|
package/README.vi.md
CHANGED
|
@@ -12,15 +12,16 @@ File này dành cho con người.
|
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
14
|
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
15
|
-
cd ~/code/colab-handbook && ./install.sh --all #
|
|
15
|
+
cd ~/code/colab-handbook && ./install.sh --all # hỏi agent nào nhận skill; + CLI colab + hook, từ bản phát hành mới nhất; --dry để xem trước
|
|
16
16
|
cd /duong-dan/toi/repo-cua-ban
|
|
17
17
|
colab adopt # chỉ hỏi những gì không tự dò ra được, rồi ghi .github/project.yml
|
|
18
18
|
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
|
-
|
|
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
|
|
24
25
|
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
25
26
|
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
26
27
|
hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
|
|
@@ -93,19 +94,19 @@ khác.
|
|
|
93
94
|
|
|
94
95
|
## Phiên làm việc đầu tiên
|
|
95
96
|
|
|
96
|
-
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi trong phiên
|
|
97
|
-
|
|
98
|
-
[`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/).
|
|
99
100
|
|
|
100
101
|
| Bước | Skill | Ai chạy | Để lại gì |
|
|
101
102
|
|---|---|---|---|
|
|
102
|
-
| 1. Chọn |
|
|
103
|
-
| 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 |
|
|
104
105
|
| 3. Làm | — | thợ | commit trên nhánh |
|
|
105
|
-
| 4. Bàn giao |
|
|
106
|
-
| 5. Merge |
|
|
107
|
-
| 6. Dọn |
|
|
108
|
-
| 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 |
|
|
109
110
|
|
|
110
111
|
Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
|
|
111
112
|
`code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
|
|
@@ -165,8 +166,8 @@ sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
|
|
|
165
166
|
|
|
166
167
|
## Adopt vào một repo
|
|
167
168
|
|
|
168
|
-
**Đường mặc định: chạy
|
|
169
|
-
đó.** 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
|
|
170
171
|
`colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
|
|
171
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
|
|
172
173
|
nhất mà không làm mất phần bạn đã sửa.
|
|
@@ -242,8 +243,9 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
242
243
|
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
243
244
|
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. Không có gì được gọi từ xa — copy, sửa, sở hữu. |
|
|
244
245
|
| [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu các lệnh: [`tools/README.md`](tools/README.md). |
|
|
245
|
-
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
246
|
-
| [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). `install.sh`
|
|
246
|
+
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
247
|
+
| [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). Là các thư mục `SKILL.md` thuần; `install.sh` link chúng vào từng coding agent bạn chọn. |
|
|
248
|
+
| [`engines/`](engines/) | Mỗi coding agent một file dữ liệu nhỏ: skill cấp user đặt ở đâu, gọi skill thế nào, agent hỗ trợ gì. Thêm engine là thêm một file — [`engines/README.md`](engines/README.md). |
|
|
247
249
|
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
|
|
248
250
|
|
|
249
251
|
## Cài đặt máy
|
|
@@ -267,14 +269,41 @@ sau đều phải chủ động:
|
|
|
267
269
|
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
268
270
|
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
269
271
|
|
|
272
|
+
### Chọn engine
|
|
273
|
+
|
|
274
|
+
Các skill là thư mục `SKILL.md` thuần, chỉ gọi `git`, `gh` và `colab`; coding
|
|
275
|
+
agent nào đọc được skill thì chạy được chúng. Khác nhau là **mỗi agent tìm
|
|
276
|
+
skill ở đâu**, nên bản cài sẽ hỏi. Ở terminal, `./install.sh` liệt kê các
|
|
277
|
+
engine nó biết và cho bạn chọn một hoặc nhiều, lựa chọn cuối là *other: give a
|
|
278
|
+
path*. Chạy không người trông thì nói bằng flag:
|
|
279
|
+
|
|
280
|
+
```sh
|
|
281
|
+
./install.sh --engine claude # Claude Code → ~/.claude/skills
|
|
282
|
+
./install.sh --engine claude,codex # cả hai
|
|
283
|
+
./install.sh --skills-dir ~/my-agent/skills # agent khác: bạn đưa thư mục của nó
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
| Engine | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
|
|
287
|
+
|---|---|---|---|
|
|
288
|
+
| Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Không cần gì. Bản cài cấp user này **thắng** `.claude/skills/<name>` cùng tên của repo (thứ tự ưu tiên là enterprise > personal > project), nên muốn dùng bản của repo thì đổi tên nó. |
|
|
289
|
+
| OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Sandbox mặc định không có mạng nên `gh` lỗi: đặt `[sandbox_workspace_write] network_access = true` trong `~/.codex/config.toml`. Số liệu lấy từ tài liệu của Codex; chưa được xác minh bằng một lần chạy trên máy sạch. |
|
|
290
|
+
| agent khác | `--skills-dir <path>` | theo cách của agent | Shell của agent cần có mạng cho `gh`. Thư mục được ghi nhớ trong `~/.colab/skills-dirs`. |
|
|
291
|
+
|
|
292
|
+
Chạy lại không flag và không có terminal thì giữ mọi engine đã thấy được link
|
|
293
|
+
sẵn, nên máy đã cài không thay đổi gì. Không thấy engine nào thì cài cho Claude
|
|
294
|
+
Code và nói rõ điều đó. Thông tin từng engine nằm trong [`engines/`](engines/),
|
|
295
|
+
mỗi engine một file — thư mục đó là nguồn của bảng trên.
|
|
296
|
+
|
|
270
297
|
| Flag | Làm gì |
|
|
271
298
|
|---|---|
|
|
272
|
-
| *(không có)* | Symlink `skills/` vào
|
|
299
|
+
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng engine đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn engine*](#chọn-engine)). |
|
|
300
|
+
| `--engine <id>[,<id>]` | Cài cho các engine này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
|
|
301
|
+
| `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
|
|
273
302
|
| `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
|
|
274
303
|
| `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
|
|
275
304
|
| `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
|
|
276
305
|
| `--all` | `--tools --hooks --fleet`. |
|
|
277
|
-
| `--notify-url <url>` |
|
|
306
|
+
| `--notify-url <url>` | Thêm `<url>` vào `notifyUrl` trong `~/.colab/config.json` nếu khoá đó chưa có URL này; không bao giờ xoá hay ghi đè mục đã có. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
278
307
|
| `--release` | Checkout clone này về tag phát hành chính thức mới nhất, rồi cài. Là mặc định cho lần cài đầu từ một bản clone mới. |
|
|
279
308
|
| `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
|
|
280
309
|
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
|
|
@@ -291,8 +320,8 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
|
|
|
291
320
|
Chưa có bản phát hành chính thức nào lên npm, nên tag mặc định `latest` chỉ là
|
|
292
321
|
bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
|
|
293
322
|
@futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
|
|
294
|
-
@futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì
|
|
295
|
-
symlink vào
|
|
323
|
+
@futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì chúng là
|
|
324
|
+
symlink trỏ vào working tree của bản clone đó.
|
|
296
325
|
|
|
297
326
|
### Kiểm tra bản cài
|
|
298
327
|
|
|
@@ -303,10 +332,11 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
|
|
|
303
332
|
colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
|
|
304
333
|
```
|
|
305
334
|
|
|
306
|
-
`--check` báo
|
|
335
|
+
`--check` báo theo từng engine: bao nhiêu skill đã link, thiếu hay hỏng, kèm
|
|
336
|
+
các lưu ý riêng của engine đó (ví dụ mạng trong sandbox của Codex). Nó cũng báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
|
|
307
337
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
308
|
-
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống
|
|
309
|
-
khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
338
|
+
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống (hoặc
|
|
339
|
+
thiếu một URL) trong khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
310
340
|
hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý hoặc
|
|
311
341
|
chỉ là chưa làm tới — nên một bản cài mới đúng, chưa đăng ký repo nào và chưa có
|
|
312
342
|
danh sách từ khoá danh tính, sẽ ra các dòng ⚠ và exit 0. Nó không bao giờ tự làm
|
package/audit/audit.mjs
CHANGED
|
@@ -37,6 +37,8 @@
|
|
|
37
37
|
// node audit.mjs --identity # also scan PUBLIC repository METADATA (description,
|
|
38
38
|
// # topics, homepage, name) against the operator's
|
|
39
39
|
// # private identity vocabulary — see "Identity" below
|
|
40
|
+
// node audit.mjs --batch-history # also read each local repo's batch landing history
|
|
41
|
+
// # (colab batch-stats --json) — see "Batch history" below
|
|
40
42
|
//
|
|
41
43
|
// Identity (--identity): metadata never passes through git, so the pre-commit identity scan
|
|
42
44
|
// (templates/pre-commit-identity) structurally cannot see it, and it is the first thing a
|
|
@@ -45,6 +47,13 @@
|
|
|
45
47
|
// vocabulary — and is never shipped, printed, or written into a report. Off unless asked
|
|
46
48
|
// for: it needs the network, and a fleet sweep must stay runnable offline.
|
|
47
49
|
//
|
|
50
|
+
// Batch history (--batch-history, #556): per LOCAL repo, the measured batch picture from
|
|
51
|
+
// `colab batch-stats --json` — overlap of serial landings with a partner inside their trunk-CI
|
|
52
|
+
// cycle, batch fill, first-attempt green rate, eviction rate. Shown, never judged on its own:
|
|
53
|
+
// an advisory is raised ONLY against a `batch-*` value the repo declares under `thresholds:`
|
|
54
|
+
// in project.yml, and none of those has a default. Off unless asked for, like --identity: it
|
|
55
|
+
// reads the CI history over the network (one API listing per day of the window).
|
|
56
|
+
//
|
|
48
57
|
// Exit code: 0 when every repo passes, 1 when any repo has a finding, 2 on a usage
|
|
49
58
|
// error. Findings never crash the run — a repo missing project.yml is a result, not
|
|
50
59
|
// an exception.
|
|
@@ -98,6 +107,9 @@ const installRoute = require("../tools/lib/install-route.js");
|
|
|
98
107
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
99
108
|
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
100
109
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
110
|
+
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
111
|
+
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
112
|
+
const batchHistory = require("../tools/lib/batch-history.js"); // #556
|
|
101
113
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
102
114
|
// validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
|
|
103
115
|
const migrationPaths = require("../tools/lib/migration-paths.js");
|
|
@@ -138,12 +150,13 @@ const COLAB_HOME = process.env.COLAB_HOME || join(homedir(), ".colab");
|
|
|
138
150
|
|
|
139
151
|
function parseArgs(argv) {
|
|
140
152
|
// config === null means "resolve from the precedence chain"; a string means explicit.
|
|
141
|
-
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false };
|
|
153
|
+
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false, batchHistory: false };
|
|
142
154
|
for (let i = 0; i < argv.length; i++) {
|
|
143
155
|
const a = argv[i];
|
|
144
156
|
if (a === "--json") opts.json = true;
|
|
145
157
|
else if (a === "--quiet" || a === "-q") opts.quiet = true;
|
|
146
158
|
else if (a === "--identity") opts.identity = true;
|
|
159
|
+
else if (a === "--batch-history") opts.batchHistory = true;
|
|
147
160
|
else if (a === "--local") {
|
|
148
161
|
const p = argv[++i];
|
|
149
162
|
if (!p) die("--local needs a path");
|
|
@@ -218,7 +231,7 @@ function parseScalarValue(raw) {
|
|
|
218
231
|
return val;
|
|
219
232
|
}
|
|
220
233
|
|
|
221
|
-
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate"]); // owner: #394 · gate: #410
|
|
234
|
+
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds"]); // owner: #394 · gate: #410 · thresholds: #560
|
|
222
235
|
|
|
223
236
|
function parseFlatYaml(text) {
|
|
224
237
|
const out = {};
|
|
@@ -1053,7 +1066,7 @@ function yamlRawValue(text, key) {
|
|
|
1053
1066
|
return m[1].replace(/\s+#.*$/, "").trim();
|
|
1054
1067
|
}
|
|
1055
1068
|
|
|
1056
|
-
const DURATION_MIN_DAYS =
|
|
1069
|
+
const DURATION_MIN_DAYS = thresholdsLib.DEFAULTS["transitional-days"]; // 180, the DEFAULT (#560: a repo may declare thresholds.transitional-days); below this, silence — see audit-exposure.test.js's pinned
|
|
1057
1070
|
// "transitional descriptor is clean" case, which this
|
|
1058
1071
|
// threshold exists to keep passing untouched: a descriptor
|
|
1059
1072
|
// committed moments ago must never earn a duration line.
|
|
@@ -1091,9 +1104,9 @@ function declaredStateAge(src, key) {
|
|
|
1091
1104
|
|
|
1092
1105
|
// Prose for a declaredStateAge() result, or null when it is too recent to be worth saying
|
|
1093
1106
|
// (the DURATION_MIN_DAYS gate — the caller must check this before calling warn()).
|
|
1094
|
-
function renderDuration(age) {
|
|
1107
|
+
function renderDuration(age, minDays = DURATION_MIN_DAYS) {
|
|
1095
1108
|
const days = Math.floor((Date.now() / 1000 - age.epoch) / DURATION_DAY_SECONDS);
|
|
1096
|
-
if (days <
|
|
1109
|
+
if (days < minDays) return null;
|
|
1097
1110
|
const months = Math.floor(days / 30); // coarse on purpose — a report, not a countdown
|
|
1098
1111
|
return `${age.lowerBound ? "at least " : ""}${months} month${months === 1 ? "" : "s"}`;
|
|
1099
1112
|
}
|
|
@@ -1122,12 +1135,15 @@ function auditRepo(target, ctx) {
|
|
|
1122
1135
|
// ---- .github/project.yml -------------------------------------------------
|
|
1123
1136
|
const rawCfg = src.readFile(".github/project.yml");
|
|
1124
1137
|
let cfg = null;
|
|
1138
|
+
// #560: the advisory thresholds this run applies — defaults until the descriptor declares otherwise.
|
|
1139
|
+
let th = thresholdsLib.parseThresholds(null);
|
|
1125
1140
|
if (rawCfg === null) {
|
|
1126
1141
|
fail("no .github/project.yml — repo is undescribed (tier/trunk/deploy unknown)");
|
|
1127
1142
|
} else {
|
|
1128
1143
|
const { data, problems } = parseFlatYaml(rawCfg);
|
|
1129
1144
|
problems.forEach((p) => fail(`project.yml: ${p}`));
|
|
1130
1145
|
cfg = data;
|
|
1146
|
+
th = thresholdsLib.parseThresholds(cfg);
|
|
1131
1147
|
// `tier` is deliberately NOT in this list as of #144: it used to be the sole axis of
|
|
1132
1148
|
// record and therefore unconditionally required, but a descriptor may now answer the
|
|
1133
1149
|
// gate-count question with `exposure` instead — see the "axis of record" check below,
|
|
@@ -1304,6 +1320,33 @@ function auditRepo(target, ctx) {
|
|
|
1304
1320
|
}
|
|
1305
1321
|
}
|
|
1306
1322
|
|
|
1323
|
+
// ---- ship-batch-wait (#555) -------------------------------------------------
|
|
1324
|
+
// How long a lone ready candidate waits for a partner (tools/lib/ship-batch.js parseShipBatchWait,
|
|
1325
|
+
// the reading `colab ship --batch` uses). Malformed fails here and in the CI templates' descriptor
|
|
1326
|
+
// check, the #416 pattern — ship fails closed to no wait, silently. A window with no batch to fill
|
|
1327
|
+
// (ship-batch absent or 1) is inert, so it warns. No ceiling: the repo chooses the value.
|
|
1328
|
+
if ("ship-batch-wait" in (cfg || {}) && cfg["ship-batch-wait"] !== null) {
|
|
1329
|
+
const wCfg = shipBatch.parseShipBatchWait(cfg);
|
|
1330
|
+
if (!wCfg.valid) fail(`${wCfg.reason} — see project.schema.md, ship-batch-wait`);
|
|
1331
|
+
else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
|
|
1332
|
+
}
|
|
1333
|
+
|
|
1334
|
+
// ---- ci-wait-factor (#559) ----------------------------------------------------
|
|
1335
|
+
// The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
|
|
1336
|
+
// (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
|
|
1337
|
+
// value fails here; the tools fall back to the documented default (2) and say so — never to a
|
|
1338
|
+
// different behaviour. No ceiling: how patient a repo is, is the repo's choice.
|
|
1339
|
+
if (ciProfile.FACTOR_KEY in (cfg || {}) && cfg[ciProfile.FACTOR_KEY] !== null) {
|
|
1340
|
+
const f = ciProfile.parseFactor(cfg);
|
|
1341
|
+
if (!f.valid) fail(`${f.reason} — see project.schema.md, ci-wait-factor`);
|
|
1342
|
+
}
|
|
1343
|
+
|
|
1344
|
+
// ---- thresholds (#560) --------------------------------------------------------
|
|
1345
|
+
// Repo-declared values for the advisory thresholds (tools/lib/thresholds.js, the one reading
|
|
1346
|
+
// `colab thresholds` and every consumer use). A malformed entry fails here and in the CI
|
|
1347
|
+
// templates' descriptor check (the #416 pattern); every consumer falls back to the default.
|
|
1348
|
+
thresholdsLib.parseThresholds(cfg).problems.forEach((p) => fail(`${p} — see project.schema.md, thresholds`));
|
|
1349
|
+
|
|
1307
1350
|
// ---- migrations (#383) ----------------------------------------------------
|
|
1308
1351
|
// Where the repo's migrations live, beyond the two defaults (database/migrations/,
|
|
1309
1352
|
// prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
|
|
@@ -1456,7 +1499,7 @@ function auditRepo(target, ctx) {
|
|
|
1456
1499
|
);
|
|
1457
1500
|
}
|
|
1458
1501
|
const exposureAge = declaredStateAge(src, "exposure");
|
|
1459
|
-
const durationLine = exposureAge && renderDuration(exposureAge);
|
|
1502
|
+
const durationLine = exposureAge && renderDuration(exposureAge, th.values["transitional-days"]);
|
|
1460
1503
|
if (durationLine) {
|
|
1461
1504
|
warn(`exposure: none has held for ${durationLine} (per the descriptor's own git history) — visible so a long-running transitional state does not go unnoticed`);
|
|
1462
1505
|
}
|
|
@@ -1546,7 +1589,7 @@ function auditRepo(target, ctx) {
|
|
|
1546
1589
|
);
|
|
1547
1590
|
}
|
|
1548
1591
|
const channelsAge = declaredStateAge(src, "channels");
|
|
1549
|
-
const durationLine = channelsAge && renderDuration(channelsAge);
|
|
1592
|
+
const durationLine = channelsAge && renderDuration(channelsAge, th.values["transitional-days"]);
|
|
1550
1593
|
if (durationLine) {
|
|
1551
1594
|
warn(`channels: [none] has held for ${durationLine} (per the descriptor's own git history) — visible so a long-running transitional state does not go unnoticed`);
|
|
1552
1595
|
}
|
|
@@ -1691,7 +1734,7 @@ function auditRepo(target, ctx) {
|
|
|
1691
1734
|
// ---- CLAUDE.md is a router, not an archive (#64) -------------------------
|
|
1692
1735
|
// Unconditional: this is a repo-doc concern, not a tier/deploy one, and it applies to
|
|
1693
1736
|
// the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
|
|
1694
|
-
checkClaudeMdSize(src, warn);
|
|
1737
|
+
checkClaudeMdSize(src, warn, th.values);
|
|
1695
1738
|
// #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
|
|
1696
1739
|
// file tools look it up in, is a repo-doc concern on every repo, the handbook's own included.
|
|
1697
1740
|
checkInstructionFileBlocks(src, warn);
|
|
@@ -1965,6 +2008,9 @@ function auditRepo(target, ctx) {
|
|
|
1965
2008
|
// read by every visitor, and it is subject to the rule it publishes.
|
|
1966
2009
|
if (ctx.identity) checkIdentityMetadata(src, ctx.identity, info, fail);
|
|
1967
2010
|
|
|
2011
|
+
// ---- batch history (#556) ------------------------------------------------------
|
|
2012
|
+
checkBatchHistory(src, target, cfg, ctx, info, warn);
|
|
2013
|
+
|
|
1968
2014
|
function finish() {
|
|
1969
2015
|
info.findings = findings;
|
|
1970
2016
|
info.ok = !findings.some((f) => f.level === "fail");
|
|
@@ -1974,6 +2020,43 @@ function auditRepo(target, ctx) {
|
|
|
1974
2020
|
return finish();
|
|
1975
2021
|
}
|
|
1976
2022
|
|
|
2023
|
+
/**
|
|
2024
|
+
* #556 — the repo's measured batch picture, from `colab batch-stats --json` (this handbook's own
|
|
2025
|
+
* CLI, so the audit and the command read history the same way). Writes `info.batchHistory` on every
|
|
2026
|
+
* path. The picture is never a finding; an advisory is raised only for a `batch-*` threshold the
|
|
2027
|
+
* repo declares (tools/lib/batch-history.js judge — no defaults, by the owner's ruling). A run that
|
|
2028
|
+
* was asked for and could not read the history warns: a quiet row must not read as "checked".
|
|
2029
|
+
*/
|
|
2030
|
+
function checkBatchHistory(src, target, cfg, ctx, info, warn) {
|
|
2031
|
+
const declared = batchHistory.declaredBatchKeys(cfg);
|
|
2032
|
+
if (!ctx.batchHistory) {
|
|
2033
|
+
info.batchHistory = { status: "not-requested", declared };
|
|
2034
|
+
return;
|
|
2035
|
+
}
|
|
2036
|
+
if (src.kind !== "local") {
|
|
2037
|
+
info.batchHistory = { status: "not-applicable", reason: "batch-stats reads a clone's trunk log — audit a local path", declared };
|
|
2038
|
+
return;
|
|
2039
|
+
}
|
|
2040
|
+
let rep;
|
|
2041
|
+
try {
|
|
2042
|
+
const out = execFileSync(process.execPath, [join(HANDBOOK_ROOT, "tools", "colab"), "batch-stats", "--repo", resolve(target.path), "--json"],
|
|
2043
|
+
{ encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 600_000, maxBuffer: 64 * 1024 * 1024 });
|
|
2044
|
+
rep = JSON.parse(out);
|
|
2045
|
+
} catch (err) {
|
|
2046
|
+
const why = String((err.stderr || err.message || "")).trim().split("\n").pop() || "no output";
|
|
2047
|
+
info.batchHistory = { status: "unreadable", reason: why, declared };
|
|
2048
|
+
warn(`batch history: colab batch-stats could not read it (${why}) — nothing was measured or judged`);
|
|
2049
|
+
return;
|
|
2050
|
+
}
|
|
2051
|
+
const measured = batchHistory.measure(rep);
|
|
2052
|
+
const verdict = batchHistory.judge(rep, cfg, measured);
|
|
2053
|
+
info.batchHistory = {
|
|
2054
|
+
status: "read", since: rep.since, until: rep.until, landings: rep.landings, measured,
|
|
2055
|
+
picture: batchHistory.picture(rep, measured), declared, judged: verdict.judged, unjudged: verdict.unjudged, notes: rep.notes || [],
|
|
2056
|
+
};
|
|
2057
|
+
verdict.advisories.forEach(warn);
|
|
2058
|
+
}
|
|
2059
|
+
|
|
1977
2060
|
/**
|
|
1978
2061
|
* #228 part 4 — the identity scan of REPOSITORY METADATA: name, description, homepage and
|
|
1979
2062
|
* topics. None of it passes through git, so the pre-commit scan cannot see any of it, and it
|
|
@@ -2193,9 +2276,10 @@ function checkReleaseBranch(cfg, trunk, branches, fail, warn, deploy) {
|
|
|
2193
2276
|
// a starting point rather than a recommendation", wanting calibration across adopting repos
|
|
2194
2277
|
// before anything here becomes a hard gate — the goal is a finding with the measured number
|
|
2195
2278
|
// ("state the condition"), not a build-breaking assertion of a still-uncalibrated one.
|
|
2196
|
-
const CLAUDE_MD_MAX_BYTES =
|
|
2197
|
-
|
|
2198
|
-
|
|
2279
|
+
const CLAUDE_MD_MAX_BYTES = thresholdsLib.DEFAULTS["claude-md-kb"] * 1024; // 40 KB by default (#560) — near the handbook's own cited worst case (39 KB / 452 lines)
|
|
2280
|
+
// The per-line multiple ("some small multiple of the [file's] median row", default 6) and its
|
|
2281
|
+
// absolute floor (default 2048 bytes — below it, flagging on the multiple alone is noise: tiny
|
|
2282
|
+
// medians make everything look huge) live in tools/lib/thresholds.js with the ceiling (#560).
|
|
2199
2283
|
|
|
2200
2284
|
// #117: the byte ceiling above was built to catch hand-written accretion, but it counts
|
|
2201
2285
|
// TOTAL file bytes — which also charges a repo for content it cannot shorten by the rule's
|
|
@@ -2428,7 +2512,11 @@ function checkAnchorLinks(src, fail) {
|
|
|
2428
2512
|
}
|
|
2429
2513
|
}
|
|
2430
2514
|
|
|
2431
|
-
function checkClaudeMdSize(src, warn) {
|
|
2515
|
+
function checkClaudeMdSize(src, warn, limits = thresholdsLib.DEFAULTS) {
|
|
2516
|
+
// #560: the three numbers below are the defaults; a repo may declare its own under `thresholds:`.
|
|
2517
|
+
const maxBytes = limits["claude-md-kb"] * 1024;
|
|
2518
|
+
const lineMultiple = limits["claude-md-line-multiple"];
|
|
2519
|
+
const lineFloor = limits["claude-md-line-floor-bytes"];
|
|
2432
2520
|
// #417: measure what is LOADED, not one file. A thin-shell CLAUDE.md (`@AGENTS.md` plus the
|
|
2433
2521
|
// by-name tool blocks) is tiny by construction, so measuring it alone would neuter this guard
|
|
2434
2522
|
// while a bloated AGENTS.md rides in behind it on every turn. The loaded set is CLAUDE.md plus
|
|
@@ -2451,7 +2539,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2451
2539
|
}
|
|
2452
2540
|
const derivedBytes = Math.max(0, bytes - authoredBytes);
|
|
2453
2541
|
|
|
2454
|
-
if (authoredBytes >
|
|
2542
|
+
if (authoredBytes > maxBytes) {
|
|
2455
2543
|
const totalNote = derivedBytes > 0
|
|
2456
2544
|
? ` (of ${bytes} bytes total; ${derivedBytes} bytes are marked colab:derived and excluded — #117)`
|
|
2457
2545
|
: "";
|
|
@@ -2460,7 +2548,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2460
2548
|
: `CLAUDE.md plus its @-imports (${files.slice(1).map((f) => f.path).join(", ")}) is`;
|
|
2461
2549
|
warn(
|
|
2462
2550
|
`${subject} ${authoredBytes} bytes (~${(authoredBytes / 1024).toFixed(1)} KB)${totalNote} — over the ` +
|
|
2463
|
-
`${
|
|
2551
|
+
`${maxBytes / 1024} KB advisory ceiling (#64${maxBytes === CLAUDE_MD_MAX_BYTES ? "" : ", declared in thresholds.claude-md-kb"}). It is loaded in full into every session before ` +
|
|
2464
2552
|
`any work starts; if the knowledge belongs in docs/, the ${files.length === 1 ? "CLAUDE.md" : "instruction-file"} change is a pointer, not a copy (code-wrap A2)`,
|
|
2465
2553
|
);
|
|
2466
2554
|
}
|
|
@@ -2475,7 +2563,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2475
2563
|
if (lens.length < 2) continue; // no meaningful median from 0 or 1 lines
|
|
2476
2564
|
const median = lens[Math.floor(lens.length / 2)];
|
|
2477
2565
|
const worst = lens[lens.length - 1];
|
|
2478
|
-
if (median > 0 && worst >
|
|
2566
|
+
if (median > 0 && worst > lineFloor && worst > median * lineMultiple) {
|
|
2479
2567
|
const pct = ((worst / f.authoredBytes) * 100).toFixed(1);
|
|
2480
2568
|
warn(
|
|
2481
2569
|
`${f.path} has a single line of ${worst} bytes — ${(worst / median).toFixed(1)}x the file's median line ` +
|
|
@@ -3073,6 +3161,7 @@ function report(results, opts, ctx) {
|
|
|
3073
3161
|
identity: ctx.identity
|
|
3074
3162
|
? { scanned: true, vocabulary: ctx.identity.path, source: ctx.identity.source, terms: ctx.identity.count }
|
|
3075
3163
|
: { scanned: false, reason: "not requested (--identity)" },
|
|
3164
|
+
batchHistory: ctx.batchHistory ? { read: true } : { read: false, reason: "not requested (--batch-history)" },
|
|
3076
3165
|
results,
|
|
3077
3166
|
}, null, 2));
|
|
3078
3167
|
return;
|
|
@@ -3089,6 +3178,11 @@ function report(results, opts, ctx) {
|
|
|
3089
3178
|
console.log(ctx.identity
|
|
3090
3179
|
? `identity: ${ctx.identity.count} term(s) from ${ctx.identity.path} (${ctx.identity.source}) — public repository metadata scanned`
|
|
3091
3180
|
: "identity: repository metadata NOT scanned (pass --identity)");
|
|
3181
|
+
// #556: same once-per-run statement for batch history — a per-repo line on every offline run
|
|
3182
|
+
// would make every row non-clean for a read nobody asked for.
|
|
3183
|
+
console.log(ctx.batchHistory
|
|
3184
|
+
? "batch: batch landing history read per local repo (colab batch-stats); advisories only against declared thresholds"
|
|
3185
|
+
: "batch: batch landing history NOT read (pass --batch-history)");
|
|
3092
3186
|
console.log("");
|
|
3093
3187
|
|
|
3094
3188
|
const shown = opts.quiet ? results.filter((r) => !r.clean) : results;
|
|
@@ -3108,6 +3202,12 @@ function report(results, opts, ctx) {
|
|
|
3108
3202
|
else if (r.adoption === "local") lines.push(`⌂ adopted locally, not committed — descriptor hidden by .git/info/exclude; a repo the fleet does not own (CONVENTIONS.md §9)${r.clean ? " ✓" : ""}`);
|
|
3109
3203
|
else if (r.clean) lines.push("✓");
|
|
3110
3204
|
r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
|
|
3205
|
+
// #556: the measured picture — information, not a finding, so it never changes clean/ok.
|
|
3206
|
+
if (r.batchHistory?.status === "read") {
|
|
3207
|
+
r.batchHistory.picture.forEach((l) => lines.push(`▸ ${l}`));
|
|
3208
|
+
if (!r.batchHistory.declared.length) lines.push("▸ no batch-* thresholds declared — shown, not judged");
|
|
3209
|
+
r.batchHistory.unjudged.forEach((u) => lines.push(`▸ thresholds.${u.key} not judged: ${u.why}`));
|
|
3210
|
+
} else if (r.batchHistory?.status === "not-applicable") lines.push(`▸ batch history: ${r.batchHistory.reason}`);
|
|
3111
3211
|
|
|
3112
3212
|
// Repeat the name on every line so the output stays greppable.
|
|
3113
3213
|
lines.forEach((l, i) => console.log(`${i === 0 ? head : cont} ${l}`));
|
|
@@ -3166,6 +3266,7 @@ function runAudit(opts) {
|
|
|
3166
3266
|
|
|
3167
3267
|
const ctx = { handbook: handbookInfo(HANDBOOK_ROOT), templateNames: templateNames(HANDBOOK_ROOT) };
|
|
3168
3268
|
ctx.identity = opts.identity ? loadIdentityVocabulary() : null;
|
|
3269
|
+
ctx.batchHistory = !!opts.batchHistory;
|
|
3169
3270
|
|
|
3170
3271
|
const results = [];
|
|
3171
3272
|
for (const t of targets) {
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
20
20
|
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
|
|
21
21
|
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
|
|
22
22
|
| `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
|
|
23
|
-
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily, from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
23
|
+
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
24
24
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
25
25
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
26
26
|
| `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
|