@futurelastic/colab-handbook 1.13.0 → 1.14.0-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/README.md +2 -2
- package/README.vi.md +2 -2
- package/audit/audit.mjs +101 -11
- package/package.json +1 -1
- package/templates/README.md +18 -3
- package/templates/ci-laravel.yml +360 -40
- package/templates/ci-node.yml +491 -35
- package/templates/ci-python.yml +301 -32
- package/templates/deploy-container-run.mjs +17 -3
- package/templates/deploy-xserver.yml +12 -0
- package/templates/instruction-files.yml +16 -0
- package/templates/pre-commit-instruction-files +55 -0
- package/tools/colab +750 -67
- package/tools/lib/batch-stats.js +66 -43
- package/tools/lib/claim-comments.js +3 -2
- package/tools/lib/codec/decision.d.ts +7 -0
- package/tools/lib/codec/decision.js +54 -0
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/release.js +6 -3
- package/tools/lib/codec/samples.json +45 -0
- package/tools/lib/config-set.js +4 -3
- package/tools/lib/decision-record.js +42 -0
- package/tools/lib/docs-only.js +47 -0
- package/tools/lib/git.js +57 -8
- package/tools/lib/instruction-file.js +49 -0
- package/tools/lib/instruction-gate.js +150 -0
- package/tools/lib/landed-prs.js +58 -0
- package/tools/lib/migration-grant.js +29 -5
- package/tools/lib/owner-policy.js +133 -0
- package/tools/lib/release-finalize.js +66 -5
- package/tools/lib/ship-batch.js +188 -14
- package/tools/lib/ship-handoff.js +174 -0
- package/tools/lib/stamp.js +6 -2
- package/tools/lib/template-trunk.js +80 -0
- package/tools/lib/tree-green.js +21 -4
- package/tools/lib/workflow-triggers.js +57 -0
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ A small set of conventions and tools for running many repos — many coding
|
|
|
6
6
|
sessions in parallel, humans and AI agents alike — without stepping on each
|
|
7
7
|
other.
|
|
8
8
|
|
|
9
|
-
**If you are an AI agent, stop here and read [`
|
|
9
|
+
**If you are an AI agent, stop here and read [`AGENTS.md`](AGENTS.md).**
|
|
10
10
|
This file is for humans.
|
|
11
11
|
|
|
12
12
|
## Quick start
|
|
@@ -240,7 +240,7 @@ migration hold with or without it.
|
|
|
240
240
|
| Path | What it is |
|
|
241
241
|
|---|---|
|
|
242
242
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
|
|
243
|
-
| [`
|
|
243
|
+
| [`AGENTS.md`](AGENTS.md) | The entry point for AI agents — the operational distillation (EN). |
|
|
244
244
|
| [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
|
|
245
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. |
|
|
246
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). |
|
package/README.vi.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
Bộ quy ước và công cụ nhỏ để vận hành nhiều repo — nhiều phiên code song song,
|
|
6
6
|
người thật lẫn AI agent — mà không giẫm chân nhau.
|
|
7
7
|
|
|
8
|
-
**Nếu bạn là AI agent, dừng ở đây và đọc [`
|
|
8
|
+
**Nếu bạn là AI agent, dừng ở đây và đọc [`AGENTS.md`](AGENTS.md).**
|
|
9
9
|
File này dành cho con người.
|
|
10
10
|
|
|
11
11
|
## Bắt đầu nhanh
|
|
@@ -239,7 +239,7 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
239
239
|
| Đường dẫn | Là gì |
|
|
240
240
|
|---|---|
|
|
241
241
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
|
|
242
|
-
| [`
|
|
242
|
+
| [`AGENTS.md`](AGENTS.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
|
|
243
243
|
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
244
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. |
|
|
245
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). |
|
package/audit/audit.mjs
CHANGED
|
@@ -39,6 +39,8 @@
|
|
|
39
39
|
// # private identity vocabulary — see "Identity" below
|
|
40
40
|
// node audit.mjs --batch-history # also read each local repo's batch landing history
|
|
41
41
|
// # (colab batch-stats --json) — see "Batch history" below
|
|
42
|
+
// node audit.mjs --base <rev> # the instruction-file ratchet's base for LOCAL repos
|
|
43
|
+
// # (default origin/<trunk>) — see checkInstructionFileShape
|
|
42
44
|
//
|
|
43
45
|
// Identity (--identity): metadata never passes through git, so the pre-commit identity scan
|
|
44
46
|
// (templates/pre-commit-identity) structurally cannot see it, and it is the first thing a
|
|
@@ -105,7 +107,7 @@ const ownerBranchLib = require("../tools/lib/owner-branch.js");
|
|
|
105
107
|
const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
106
108
|
const installRoute = require("../tools/lib/install-route.js");
|
|
107
109
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
108
|
-
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
110
|
+
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
|
|
109
111
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
110
112
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
111
113
|
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
@@ -123,6 +125,8 @@ const trustHumansLib = require("../tools/lib/trust-humans.js");
|
|
|
123
125
|
const hermeticLib = require("../tools/lib/hermetic.js");
|
|
124
126
|
// #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
|
|
125
127
|
const treeGreenLib = require("../tools/lib/tree-green.js");
|
|
128
|
+
// #570: the `ci-docs-skip:` opt-in — read through the same module whose rule the CI guard mirrors.
|
|
129
|
+
const docsOnlyLib = require("../tools/lib/docs-only.js");
|
|
126
130
|
// #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
|
|
127
131
|
const verifyRunsLib = require("../tools/lib/verify-runs.js");
|
|
128
132
|
// #410: the optional `gate:` block — read through the same module the skills name.
|
|
@@ -130,6 +134,7 @@ const gateLib = require("../tools/lib/gate.js");
|
|
|
130
134
|
// #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
|
|
131
135
|
// shared with `colab adopt` so the shell it writes and the shape the audit checks are one shape.
|
|
132
136
|
const instructionFile = require("../tools/lib/instruction-file.js");
|
|
137
|
+
const instructionGate = require("../tools/lib/instruction-gate.js"); // #588
|
|
133
138
|
// #228's identity vocabulary — resolution, parsing, matching and REDACTION. Shared with the
|
|
134
139
|
// conformance test that holds it and the shell hook (templates/pre-commit-identity) to the
|
|
135
140
|
// same semantics; the shell scanner cannot require it (a template lands in repos with no
|
|
@@ -157,6 +162,11 @@ function parseArgs(argv) {
|
|
|
157
162
|
else if (a === "--quiet" || a === "-q") opts.quiet = true;
|
|
158
163
|
else if (a === "--identity") opts.identity = true;
|
|
159
164
|
else if (a === "--batch-history") opts.batchHistory = true;
|
|
165
|
+
else if (a === "--base") {
|
|
166
|
+
const p = argv[++i];
|
|
167
|
+
if (!p) die("--base needs a rev");
|
|
168
|
+
opts.base = p;
|
|
169
|
+
}
|
|
160
170
|
else if (a === "--local") {
|
|
161
171
|
const p = argv[++i];
|
|
162
172
|
if (!p) die("--local needs a path");
|
|
@@ -651,6 +661,7 @@ function makeSource(target) {
|
|
|
651
661
|
return {
|
|
652
662
|
label: target.label,
|
|
653
663
|
kind: "local",
|
|
664
|
+
root,
|
|
654
665
|
exists: existsSync(root),
|
|
655
666
|
readFile: (p) => {
|
|
656
667
|
const f = join(root, p);
|
|
@@ -1303,7 +1314,7 @@ function auditRepo(target, ctx) {
|
|
|
1303
1314
|
if (prefixRaw !== null && prefixRaw !== "machine") fail(`branchPrefix is ${JSON.stringify(prefixRaw)}, expected "machine" (omit for the unprefixed default)`);
|
|
1304
1315
|
|
|
1305
1316
|
// ---- ship-batch (#373) ------------------------------------------------------
|
|
1306
|
-
// Batch landing's opt-in: an integer 1–
|
|
1317
|
+
// Batch landing's opt-in: an integer 1–MAX_BATCH (tools/lib/ship-batch.js parseShipBatch — the one reading
|
|
1307
1318
|
// `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
|
|
1308
1319
|
// to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
|
|
1309
1320
|
// the CI templates' descriptor check too (#416, held to this same parser by
|
|
@@ -1331,6 +1342,17 @@ function auditRepo(target, ctx) {
|
|
|
1331
1342
|
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
1343
|
}
|
|
1333
1344
|
|
|
1345
|
+
// ---- ship-batch-steps (#557) -------------------------------------------------
|
|
1346
|
+
// The sizes an adaptive batch walks through (tools/lib/ship-batch.js parseShipBatchSteps, the
|
|
1347
|
+
// reading `colab ship --batch` uses): ascending whole numbers within ship-batch. Malformed fails
|
|
1348
|
+
// here and in the CI templates' descriptor check, the #416 pattern — ship fails closed to the fixed
|
|
1349
|
+
// size, silently. Steps with no batch to size (ship-batch absent or 1) are inert, so they warn.
|
|
1350
|
+
if (shipBatch.STEPS_KEY in (cfg || {}) && cfg[shipBatch.STEPS_KEY] !== null) {
|
|
1351
|
+
const sCfg = shipBatch.parseShipBatchSteps(cfg);
|
|
1352
|
+
if (!sCfg.valid) fail(`${sCfg.reason} — see project.schema.md, ship-batch-steps`);
|
|
1353
|
+
else if (shipBatch.parseShipBatch(cfg).n <= 1) warn(`${sCfg.reason} is inert without ship-batch > 1 — there is no batch to size`);
|
|
1354
|
+
}
|
|
1355
|
+
|
|
1334
1356
|
// ---- ci-wait-factor (#559) ----------------------------------------------------
|
|
1335
1357
|
// The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
|
|
1336
1358
|
// (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
|
|
@@ -1374,11 +1396,28 @@ function auditRepo(target, ctx) {
|
|
|
1374
1396
|
// read by three consumers). tools/lib/migration-grant.js parseGrantPolicy is the one reading, so
|
|
1375
1397
|
// `colab migration-grant` and the audit cannot disagree. The value is always reported
|
|
1376
1398
|
// (info.migrationGrant). An invalid value fails: the reader falls back to `human`, which is safe
|
|
1377
|
-
// but silent. `reviewer` is clean: colab ship honours it under
|
|
1399
|
+
// but silent. `reviewer` is clean when a round-trip job exists: colab ship honours it under
|
|
1400
|
+
// P+M+HEAD+R (#401), and R needs that job (#494).
|
|
1378
1401
|
{
|
|
1379
1402
|
const pol = migrationGrant.parseGrantPolicy(cfg);
|
|
1380
1403
|
info.migrationGrant = pol.policy;
|
|
1404
|
+
// #596: an undeclared key is no longer "human, full stop" — the owner-level value (a tracker
|
|
1405
|
+
// record, `colab owner-policy show`) may apply, and this offline audit cannot read it. So the
|
|
1406
|
+
// source is reported: `repo` (declared here, final) or `undeclared` (repo-local default human,
|
|
1407
|
+
// owner level unread). The round-trip warning below stays on a DECLARED reviewer only: for an
|
|
1408
|
+
// owner-level reviewer the mint itself refuses without the job, which is where it surfaces.
|
|
1409
|
+
info.migrationGrantSource = pol.declared ? "repo" : "undeclared";
|
|
1381
1410
|
if (!pol.valid) fail(pol.reason);
|
|
1411
|
+
// #494: R needs a live `Migration round-trip…` job. Without one every reviewer grant fails R
|
|
1412
|
+
// (the mint and ship both refuse) and the declared policy does nothing — say so here, not at
|
|
1413
|
+
// ship time. A warning: the policy fails safe, back to a human grant.
|
|
1414
|
+
if (pol.valid && pol.policy === "reviewer") {
|
|
1415
|
+
const rt = migrationGrant.roundtripJobWorkflows({ readFile: (p) => src.readFile(p), workflows });
|
|
1416
|
+
info.migrationRoundtrip = rt;
|
|
1417
|
+
if (!rt.length) {
|
|
1418
|
+
warn(`migration-grant: reviewer, but no workflow in .github/workflows has a "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job — every reviewer grant fails R (the mint and colab ship refuse); adopt the job from templates/ci-laravel.yml or the opt-in block in templates/ci-node.yml, or declare migration-grant: human`);
|
|
1419
|
+
}
|
|
1420
|
+
}
|
|
1382
1421
|
}
|
|
1383
1422
|
|
|
1384
1423
|
// ---- ci-grant (#504) -------------------------------------------------------
|
|
@@ -1425,6 +1464,16 @@ function auditRepo(target, ctx) {
|
|
|
1425
1464
|
if (!tr.valid) fail(tr.reason);
|
|
1426
1465
|
}
|
|
1427
1466
|
|
|
1467
|
+
// ---- ci-docs-skip (#570) ----------------------------------------------------
|
|
1468
|
+
// Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
|
|
1469
|
+
// (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
|
|
1470
|
+
// An invalid value fails: the guard reads it as not opted in, so it silently does nothing.
|
|
1471
|
+
{
|
|
1472
|
+
const ds = docsOnlyLib.parseCiDocsSkip(cfg);
|
|
1473
|
+
info.ciDocsSkip = ds.declared && ds.valid ? ds.exclude : null;
|
|
1474
|
+
if (!ds.valid) fail(ds.reason);
|
|
1475
|
+
}
|
|
1476
|
+
|
|
1428
1477
|
// ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
|
|
1429
1478
|
// Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
|
|
1430
1479
|
// the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
|
|
@@ -1736,10 +1785,16 @@ function auditRepo(target, ctx) {
|
|
|
1736
1785
|
// the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
|
|
1737
1786
|
checkClaudeMdSize(src, warn, th.values);
|
|
1738
1787
|
// #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
|
|
1739
|
-
// file tools look it up in, is a repo-doc concern on every repo, the handbook's own included
|
|
1740
|
-
|
|
1788
|
+
// file tools look it up in, is a repo-doc concern on every repo, the handbook's own included —
|
|
1789
|
+
// except the misplaced-Conventions-block half, which is a stamp check: the handbook has no
|
|
1790
|
+
// block to place, and its AGENTS.md says it "follows the colab-handbook" (#587).
|
|
1791
|
+
checkInstructionFileBlocks(src, warn, { self: isSelf });
|
|
1741
1792
|
// #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
|
|
1742
|
-
|
|
1793
|
+
// #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
|
|
1794
|
+
checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null });
|
|
1795
|
+
// #599: a caller of the reusable instruction-files workflow narrowed off session branches, or not
|
|
1796
|
+
// dispatchable, defeats the ratchet's point (fail on the branch) and the cure rule's way out.
|
|
1797
|
+
checkInstructionFilesCaller(src, workflows, cfg?.trunk ?? null, warn);
|
|
1743
1798
|
|
|
1744
1799
|
// ---- markdown anchor links resolve (#158) --------------------------------
|
|
1745
1800
|
// Unconditional, same posture as checkClaudeMdSize above: general markdown hygiene,
|
|
@@ -2587,7 +2642,7 @@ function checkClaudeMdSize(src, warn, limits = thresholdsLib.DEFAULTS) {
|
|
|
2587
2642
|
// Both WARN, never FAIL: neither stops anything working, they cost tokens or drift tracking.
|
|
2588
2643
|
// Byte-identical CLAUDE.md and AGENTS.md (a symlinked or copied pair) are ONE file here, or
|
|
2589
2644
|
// every symlinked repo would warn on a duplicate it does not have.
|
|
2590
|
-
function checkInstructionFileBlocks(src, warn) {
|
|
2645
|
+
function checkInstructionFileBlocks(src, warn, { self = false } = {}) {
|
|
2591
2646
|
const read = (p) => src.readFile(p);
|
|
2592
2647
|
const loaded = instructionFile.collectLoaded(read, "CLAUDE.md").files;
|
|
2593
2648
|
const claude = loaded.find((f) => f.path === "CLAUDE.md");
|
|
@@ -2610,6 +2665,9 @@ function checkInstructionFileBlocks(src, warn) {
|
|
|
2610
2665
|
}
|
|
2611
2666
|
}
|
|
2612
2667
|
|
|
2668
|
+
// The handbook source carries no Conventions block by design (it is X, nothing to copy from),
|
|
2669
|
+
// so "the block moved out of CLAUDE.md" cannot be true of it — skip, like every stamp check.
|
|
2670
|
+
if (self) return;
|
|
2613
2671
|
const hasBlock = (t) => !!(parseClaudeStamp(t) || looksLikeHandbookClaude(t));
|
|
2614
2672
|
if (!(claude && hasBlock(claude.text))) {
|
|
2615
2673
|
const elsewhere = scan.filter((f) => f.path !== "CLAUDE.md" && hasBlock(f.text)).map((f) => f.path);
|
|
@@ -2635,10 +2693,33 @@ function checkInstructionFileBlocks(src, warn) {
|
|
|
2635
2693
|
// A repo with neither file is not this check's business (no instruction
|
|
2636
2694
|
// file at all is an adoption gap, reported elsewhere).
|
|
2637
2695
|
//
|
|
2638
|
-
// WARN,
|
|
2639
|
-
//
|
|
2640
|
-
//
|
|
2641
|
-
|
|
2696
|
+
// WARN, and FAIL only under the ratchet (#588): existing repos migrate over time (handbook-sync's
|
|
2697
|
+
// graft step moves the prose), so the finding fails only where `colab instruction-files` would —
|
|
2698
|
+
// a LOCAL repo inside git, judged against merge-base(<base>, HEAD) with <base> = `--base`, else
|
|
2699
|
+
// origin/<trunk>: some CLAUDE.md non-conforming in the working tree AND either a CLAUDE.md/AGENTS.md
|
|
2700
|
+
// changed since the merge base, or every CLAUDE.md conformed there. Same code as the hook and the
|
|
2701
|
+
// reusable workflow (tools/lib/instruction-gate.js), so the three cannot disagree. A remote source,
|
|
2702
|
+
// or a local one with no base to compare against, keeps the warning: no ratchet, no failure.
|
|
2703
|
+
function instructionRatchet(src, opts) {
|
|
2704
|
+
if (src.kind !== "local" || !src.root) return null;
|
|
2705
|
+
const base = opts.base || (opts.trunk ? `origin/${opts.trunk}` : null);
|
|
2706
|
+
if (!base) return null;
|
|
2707
|
+
const r = instructionGate.gate({ cwd: src.root, base, head: "worktree" });
|
|
2708
|
+
if (!r.ok) return opts.base ? { ok: false, error: r.error } : null; // an explicit base that cannot be read is said aloud
|
|
2709
|
+
return r;
|
|
2710
|
+
}
|
|
2711
|
+
|
|
2712
|
+
function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
|
|
2713
|
+
const ratchet = instructionRatchet(src, opts);
|
|
2714
|
+
if (ratchet && !ratchet.ok) warn(`instruction-file ratchet not evaluated: ${ratchet.error} (#588)`);
|
|
2715
|
+
if (ratchet && ratchet.ok && ratchet.fail) {
|
|
2716
|
+
const why = ratchet.reason === "touched"
|
|
2717
|
+
? "this change touches CLAUDE.md/AGENTS.md"
|
|
2718
|
+
: "every CLAUDE.md conformed at the merge base, so this regresses the repo";
|
|
2719
|
+
for (const f of ratchet.bad) {
|
|
2720
|
+
fail(`prose-in-claude-md: ${f.message} (CONVENTIONS.md §9 step 5; ratchet: ${why}; \`colab instruction-files --base <rev>\` reproduces it) (#588)`);
|
|
2721
|
+
}
|
|
2722
|
+
}
|
|
2642
2723
|
const claude = src.readFile("CLAUDE.md");
|
|
2643
2724
|
if (claude === null || claude === undefined) return;
|
|
2644
2725
|
const agents = src.readFile("AGENTS.md");
|
|
@@ -2650,6 +2731,7 @@ function checkInstructionFileShape(src, warn) {
|
|
|
2650
2731
|
} else if (agents === claude) {
|
|
2651
2732
|
return;
|
|
2652
2733
|
}
|
|
2734
|
+
if (ratchet && ratchet.ok && ratchet.fail) return; // already reported above, as a failure
|
|
2653
2735
|
const residue = instructionFile.shellResidue(claude);
|
|
2654
2736
|
if (!residue.length) return;
|
|
2655
2737
|
const shape = instructionFile.isThinShell(claude)
|
|
@@ -2677,6 +2759,13 @@ function checkInstructionFileShape(src, warn) {
|
|
|
2677
2759
|
// caller is `deploy: manual` (a human runs it) or `deploy: tag` deployed OUTSIDE CI (a GitOps
|
|
2678
2760
|
// poller runs it). Both share the same invariant: the deploy runs off no in-repo workflow, so the
|
|
2679
2761
|
// path to production must be WRITTEN DOWN or nobody but its author can ship it.
|
|
2762
|
+
// ---- the instruction-files caller's trigger (#599) ---------------------------
|
|
2763
|
+
// The logic lives in tools/lib/workflow-triggers.js beside the other trigger readers. WARN, never
|
|
2764
|
+
// fail: the caller is a copy the repo owns, and handbook-sync's trigger graft is the fix.
|
|
2765
|
+
function checkInstructionFilesCaller(src, workflows, trunk, warn) {
|
|
2766
|
+
for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
|
|
2767
|
+
}
|
|
2768
|
+
|
|
2680
2769
|
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
2681
2770
|
// The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
|
|
2682
2771
|
// same finding; this maps its severity onto the audit's fail/warn.
|
|
@@ -3267,6 +3356,7 @@ function runAudit(opts) {
|
|
|
3267
3356
|
const ctx = { handbook: handbookInfo(HANDBOOK_ROOT), templateNames: templateNames(HANDBOOK_ROOT) };
|
|
3268
3357
|
ctx.identity = opts.identity ? loadIdentityVocabulary() : null;
|
|
3269
3358
|
ctx.batchHistory = !!opts.batchHistory;
|
|
3359
|
+
ctx.base = opts.base || null;
|
|
3270
3360
|
|
|
3271
3361
|
const results = [];
|
|
3272
3362
|
for (const t of targets) {
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -33,6 +33,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
33
33
|
| `adr-README.md` | `docs/adr/README.md` | Any repo starting a `docs/adr/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Same issue-keyed naming rule as `gotchas-d-README.md`, applied to architecture decision records instead of gotchas — an existing sequentially-numbered `docs/adr/` is left as-is; only new decisions use `<issue>-<slug>.md`. Optional, same as above. |
|
|
34
34
|
| `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
|
|
35
35
|
| `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
|
|
36
|
+
| `instruction-files.yml` | `.github/workflows/instruction-files.yml` | Every repo with a `CLAUDE.md` (#588) | **A caller, not a copy:** its one job `uses:` the handbook's reusable `.github/workflows/instruction-files.yml`, so the judgement is maintained once and works from any org. Fails when a `CLAUDE.md` carries repo prose instead of `@AGENTS.md` + tool blocks — **ratcheted**: only when the change touches `CLAUDE.md`/`AGENTS.md`, or the repo had already migrated. An unmigrated repo stays green until it edits those files. Pin `@<tag>` plus `with: handbook-ref: <tag>` to freeze the checker. No GitHub-hosted minutes (self-hosted-only org)? `with: runs-on: <label>` or a JSON list `'["self-hosted","linux"]'` (#594) — any Linux runner with git; the job sets up its own Node. |
|
|
36
37
|
| `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
|
|
37
38
|
|
|
38
39
|
### The `dedupe` job — why a claimed branch's first run skips the suite (#418)
|
|
@@ -67,8 +68,11 @@ notice back and print the run they relied on. Three things to keep in a copy:
|
|
|
67
68
|
|
|
68
69
|
- **It needs `contents: read`** on top of `actions: read`, to read the descriptor and the
|
|
69
70
|
commit objects.
|
|
70
|
-
- **The trunk refs in its `if:` mirror `concurrency`'s list.**
|
|
71
|
-
|
|
71
|
+
- **The trunk refs in its `if:` mirror `concurrency`'s list.** The list appears three times in a
|
|
72
|
+
copy: the `group:`, `cancel-in-progress:`, and this `if:` (#512 gave the trunk its own
|
|
73
|
+
per-run group, so a pending trunk run is never replaced). On a repo whose trunk has another
|
|
74
|
+
name, edit all three. Until you do, the guard simply never fires on trunk — nothing breaks;
|
|
75
|
+
but a trunk left out of `group:` and `cancel-in-progress:` has its runs cancelled.
|
|
72
76
|
- **Never put a trunk-only job behind it.** Publish, deploy and release jobs must run whatever
|
|
73
77
|
the guard says. Give them their own `if:` that does not read `needs.dedupe`.
|
|
74
78
|
|
|
@@ -107,7 +111,7 @@ match their source stem (`pre-push-guard` → `<hooks>/pre-push`) — so `colab
|
|
|
107
111
|
does not carry them, and they take **no version stamp**. The original reason a stamp
|
|
108
112
|
was impossible here — prepending a comment line above a `#!` shebang breaks it — is
|
|
109
113
|
fixed for `docs-lint.mjs` above (a second-line stamp, colab-handbook #252), but that fix
|
|
110
|
-
still needs a destination formula before it can apply to these too, and these
|
|
114
|
+
still needs a destination formula before it can apply to these too, and these
|
|
111
115
|
files don't have one. Copy them with `cp`, `chmod +x`, and own them exactly as you own
|
|
112
116
|
a workflow.
|
|
113
117
|
|
|
@@ -116,6 +120,7 @@ a workflow.
|
|
|
116
120
|
| `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes, and the release channels `next` / `stable`, which only `colab release cut` / `finalize` move (#445). Reads `project.yml`; missing descriptor → allows, with a warning. |
|
|
117
121
|
| `pre-commit-dispatch` | `<hooks>/pre-commit` | Any repo that needs **more than one** pre-commit check | Runs every hooklet in `pre-commit.d/`, fails if any failed, and **refuses when there is nothing to run**. Read its header before installing — it replaces a hook you already have, and step 2 of its instructions is where your existing check survives. |
|
|
118
122
|
| `pre-commit-identity` | `<hooks>/pre-commit.d/20-identity` | Any repo that could publish an identity — every public one, and any private one that may ever be opened | Scans staged content against a vocabulary the operator supplies **by path**. Also installs as `commit-msg`. |
|
|
123
|
+
| `pre-commit-instruction-files` | `<hooks>/pre-commit.d/30-instruction-files` | Every repo with a `CLAUDE.md` (#588) | Runs `colab instruction-files --staged` only when a `CLAUDE.md`/`AGENTS.md` is staged — otherwise one `git diff --cached` and out. Same judgement and ratchet as the CI caller above. No `colab` on the machine → warns and passes; CI still judges the push. |
|
|
119
124
|
| `identity-vocabulary.example` | *outside every repo* — e.g. `~/.colab/identity-vocabulary` | The above | Invented entries. **A real one is never committed anywhere**, which is the whole reason the scanner takes a path instead of shipping a list. |
|
|
120
125
|
|
|
121
126
|
`<hooks>` is `git config core.hooksPath` if you set one, else `.git/hooks`. The
|
|
@@ -192,6 +197,7 @@ mkdir -p <hooks>/pre-commit.d
|
|
|
192
197
|
git mv <hooks>/pre-commit <hooks>/pre-commit.d/10-secrets # your existing check, unchanged
|
|
193
198
|
cp templates/pre-commit-dispatch <hooks>/pre-commit
|
|
194
199
|
cp templates/pre-commit-identity <hooks>/pre-commit.d/20-identity
|
|
200
|
+
cp templates/pre-commit-instruction-files <hooks>/pre-commit.d/30-instruction-files
|
|
195
201
|
chmod +x <hooks>/pre-commit <hooks>/pre-commit.d/*
|
|
196
202
|
cp templates/identity-vocabulary.example ~/.colab/identity-vocabulary # then EDIT it, outside any repo
|
|
197
203
|
```
|
|
@@ -302,3 +308,12 @@ runner is infrastructure, not a throwaway VM.
|
|
|
302
308
|
service context (`job.services.mysql.ports['3306']`), threading it through your
|
|
303
309
|
env. A fixed `3306:3306` works exactly until the first job lands on a runner
|
|
304
310
|
that already listens there.
|
|
311
|
+
|
|
312
|
+
### One run per commit — why the CI templates have no `pull_request` trigger (#512)
|
|
313
|
+
|
|
314
|
+
The three `ci-*` templates trigger on `push: ['**']` and `workflow_dispatch`. A same-repo PR
|
|
315
|
+
commit gets the push run and nothing else; a `pull_request` trigger beside it ran the suite twice
|
|
316
|
+
and let the later run, which tests the merge ref, decide the verdict. Two edits belong to a copy:
|
|
317
|
+
a repo that goes back to trunk-only push restores `pull_request: branches: [<trunk>]`, and a repo
|
|
318
|
+
that accepts fork PRs keeps one (a fork's push never runs a workflow here). Detail:
|
|
319
|
+
`CONVENTIONS.md` §4, *Branch CI*.
|