@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.10
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 +218 -53
- 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/templates/release-auto.yml +16 -3
- package/tools/colab +884 -98
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/audit-cache.js +277 -0
- package/tools/lib/batch-stats.js +66 -43
- package/tools/lib/ci-cure.js +10 -1
- 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/cure-diff.js +27 -1
- 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/grant-policy.js +133 -0
- package/tools/lib/instruction-file.js +75 -0
- package/tools/lib/instruction-gate.js +179 -0
- package/tools/lib/landed-prs.js +58 -0
- package/tools/lib/migration-grant.js +29 -5
- package/tools/lib/owner-policy.js +110 -0
- package/tools/lib/release-cut.js +127 -10
- package/tools/lib/release-finalize.js +66 -5
- package/tools/lib/ship-batch.js +188 -14
- package/tools/lib/ship-handoff.js +212 -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,21 @@
|
|
|
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
|
|
44
|
+
// node audit.mjs --offline # local checks only: no GitHub read at all — see "Remote cache"
|
|
45
|
+
// node audit.mjs --fresh # ignore the cache TTL: re-ask GitHub (still conditional)
|
|
46
|
+
// node audit.mjs --cache-ttl <secs> # how long a cached GitHub read is served unasked
|
|
47
|
+
// # (default 600; env COLAB_AUDIT_CACHE_TTL; 0 = always ask)
|
|
48
|
+
//
|
|
49
|
+
// Remote cache (#593): the GitHub reads (repository metadata, labels, and a slug target's files,
|
|
50
|
+
// branches and tags) are cached across runs, one file per repo under COLAB_AUDIT_CACHE_DIR, else
|
|
51
|
+
// ${COLAB_HOME:-~/.colab}/cache/audit when that home already exists (the audit never creates it).
|
|
52
|
+
// Within the TTL a read costs no request; past it each page is re-asked with If-None-Match, and a
|
|
53
|
+
// 304 costs no quota. A rate limit or no response serves the cached copy, marked stale. --json
|
|
54
|
+
// states per repo where its remote facts came from (`remote`). --offline is the cheap frequent
|
|
55
|
+
// pass: local checks only, remote-only (slug) entries skipped, and it refuses --identity,
|
|
56
|
+
// --batch-history and --fresh, which all need the network.
|
|
42
57
|
//
|
|
43
58
|
// Identity (--identity): metadata never passes through git, so the pre-commit identity scan
|
|
44
59
|
// (templates/pre-commit-identity) structurally cannot see it, and it is the first thing a
|
|
@@ -105,11 +120,13 @@ const ownerBranchLib = require("../tools/lib/owner-branch.js");
|
|
|
105
120
|
const npmGuard = require("../tools/lib/npm-publish-guard.js");
|
|
106
121
|
const installRoute = require("../tools/lib/install-route.js");
|
|
107
122
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
108
|
-
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
123
|
+
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush, instructionFilesCallerFindings } = require("../tools/lib/workflow-triggers.js");
|
|
109
124
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
110
125
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
111
126
|
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
112
127
|
const batchHistory = require("../tools/lib/batch-history.js"); // #556
|
|
128
|
+
// #593: every GitHub REST read goes through one on-disk, per-repo cache (ETag + TTL) — see the module.
|
|
129
|
+
const auditCache = require("../tools/lib/audit-cache.js");
|
|
113
130
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
114
131
|
// validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
|
|
115
132
|
const migrationPaths = require("../tools/lib/migration-paths.js");
|
|
@@ -123,6 +140,8 @@ const trustHumansLib = require("../tools/lib/trust-humans.js");
|
|
|
123
140
|
const hermeticLib = require("../tools/lib/hermetic.js");
|
|
124
141
|
// #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
|
|
125
142
|
const treeGreenLib = require("../tools/lib/tree-green.js");
|
|
143
|
+
// #570: the `ci-docs-skip:` opt-in — read through the same module whose rule the CI guard mirrors.
|
|
144
|
+
const docsOnlyLib = require("../tools/lib/docs-only.js");
|
|
126
145
|
// #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
|
|
127
146
|
const verifyRunsLib = require("../tools/lib/verify-runs.js");
|
|
128
147
|
// #410: the optional `gate:` block — read through the same module the skills name.
|
|
@@ -130,6 +149,7 @@ const gateLib = require("../tools/lib/gate.js");
|
|
|
130
149
|
// #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
|
|
131
150
|
// shared with `colab adopt` so the shell it writes and the shape the audit checks are one shape.
|
|
132
151
|
const instructionFile = require("../tools/lib/instruction-file.js");
|
|
152
|
+
const instructionGate = require("../tools/lib/instruction-gate.js"); // #588
|
|
133
153
|
// #228's identity vocabulary — resolution, parsing, matching and REDACTION. Shared with the
|
|
134
154
|
// conformance test that holds it and the shell hook (templates/pre-commit-identity) to the
|
|
135
155
|
// same semantics; the shell scanner cannot require it (a template lands in repos with no
|
|
@@ -150,13 +170,25 @@ const COLAB_HOME = process.env.COLAB_HOME || join(homedir(), ".colab");
|
|
|
150
170
|
|
|
151
171
|
function parseArgs(argv) {
|
|
152
172
|
// config === null means "resolve from the precedence chain"; a string means explicit.
|
|
153
|
-
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false, batchHistory: false };
|
|
173
|
+
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false, batchHistory: false, offline: false, fresh: false, cacheTtl: null };
|
|
154
174
|
for (let i = 0; i < argv.length; i++) {
|
|
155
175
|
const a = argv[i];
|
|
156
176
|
if (a === "--json") opts.json = true;
|
|
157
177
|
else if (a === "--quiet" || a === "-q") opts.quiet = true;
|
|
158
178
|
else if (a === "--identity") opts.identity = true;
|
|
159
179
|
else if (a === "--batch-history") opts.batchHistory = true;
|
|
180
|
+
else if (a === "--offline" || a === "--no-remote") opts.offline = true;
|
|
181
|
+
else if (a === "--fresh") opts.fresh = true;
|
|
182
|
+
else if (a === "--cache-ttl") {
|
|
183
|
+
const p = argv[++i];
|
|
184
|
+
if (p === undefined) die("--cache-ttl needs a number of seconds");
|
|
185
|
+
opts.cacheTtl = p;
|
|
186
|
+
}
|
|
187
|
+
else if (a === "--base") {
|
|
188
|
+
const p = argv[++i];
|
|
189
|
+
if (!p) die("--base needs a rev");
|
|
190
|
+
opts.base = p;
|
|
191
|
+
}
|
|
160
192
|
else if (a === "--local") {
|
|
161
193
|
const p = argv[++i];
|
|
162
194
|
if (!p) die("--local needs a path");
|
|
@@ -505,31 +537,30 @@ function runGh(args) {
|
|
|
505
537
|
}
|
|
506
538
|
|
|
507
539
|
// A slug is fetched read-only through the API — nothing is cloned, nothing is written
|
|
508
|
-
// into anyone's working tree.
|
|
540
|
+
// into anyone's working tree. Every REST read below goes through `remoteCache` (#593), set up
|
|
541
|
+
// once per run in runAudit; the `--jq` filters these used to pass are applied here in JS,
|
|
542
|
+
// because a cached page is the raw API body.
|
|
543
|
+
let remoteCache = auditCache.create({ dir: null, ttlSeconds: 0 });
|
|
544
|
+
|
|
509
545
|
function readRemoteFile(slug, path) {
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
} catch {
|
|
513
|
-
return null;
|
|
514
|
-
}
|
|
546
|
+
const r = remoteCache.get(slug, `repos/${slug}/contents/${path}`, { accept: "application/vnd.github.raw" });
|
|
547
|
+
return r.status === "ok" ? r.text : null;
|
|
515
548
|
}
|
|
516
549
|
|
|
517
550
|
function listRemoteDir(slug, path) {
|
|
551
|
+
const r = remoteCache.get(slug, `repos/${slug}/contents/${path}`);
|
|
552
|
+
if (r.status !== "ok") return [];
|
|
518
553
|
try {
|
|
519
|
-
const
|
|
520
|
-
return
|
|
554
|
+
const arr = JSON.parse(r.text);
|
|
555
|
+
return Array.isArray(arr) ? arr.map((e) => String(e.name || "").trim()).filter(Boolean) : [];
|
|
521
556
|
} catch {
|
|
522
557
|
return [];
|
|
523
558
|
}
|
|
524
559
|
}
|
|
525
560
|
|
|
526
561
|
function listRemoteBranches(slug) {
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
return out.split("\n").map((s) => s.trim()).filter(Boolean);
|
|
530
|
-
} catch {
|
|
531
|
-
return null; // null = could not determine, distinct from "no branches"
|
|
532
|
-
}
|
|
562
|
+
const r = remoteCache.get(slug, `repos/${slug}/branches`, { paginate: true });
|
|
563
|
+
return r.status === "ok" ? r.items.map((b) => String(b.name)) : null; // null = could not determine, distinct from "no branches"
|
|
533
564
|
}
|
|
534
565
|
|
|
535
566
|
// Same null/[] contract as listRemoteBranches: null = could not determine (no remote, no
|
|
@@ -537,33 +568,22 @@ function listRemoteBranches(slug) {
|
|
|
537
568
|
// falsifiers (#137) — a version-shaped tag is evidence against a declared "nothing consumes
|
|
538
569
|
// this" claim, whether the source is local or remote.
|
|
539
570
|
function listRemoteTags(slug) {
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
return out.split("\n").map((s) => s.trim()).filter(Boolean);
|
|
543
|
-
} catch {
|
|
544
|
-
return null;
|
|
545
|
-
}
|
|
571
|
+
const r = remoteCache.get(slug, `repos/${slug}/tags`, { paginate: true });
|
|
572
|
+
return r.status === "ok" ? r.items.map((t) => String(t.name)) : null;
|
|
546
573
|
}
|
|
547
574
|
|
|
548
575
|
// Labels live on GitHub, not in the working tree, so this is the audit's one check that
|
|
549
576
|
// needs the tracker. `null` means "could not determine" — no remote, no auth, gh absent,
|
|
550
|
-
// API error — and the caller stays SILENT on it rather than warning: unlike branches
|
|
577
|
+
// API error, --offline — and the caller stays SILENT on it rather than warning: unlike branches
|
|
551
578
|
// (every git repo has them), labels are a GitHub-only concept and a remote-less or
|
|
552
579
|
// offline audit legitimately cannot see them. A warn per offline repo would be noise,
|
|
553
580
|
// and we cannot assert a label is missing when we could not read the set at all.
|
|
554
|
-
// Each entry is { name, description } (#364)
|
|
555
|
-
//
|
|
556
|
-
// null: a half-read set would report the unread half as "missing".
|
|
581
|
+
// Each entry is { name, description } (#364). Any page that does not parse makes the whole
|
|
582
|
+
// read null: a half-read set would report the unread half as "missing".
|
|
557
583
|
function listRemoteLabels(slug) {
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
const l = JSON.parse(line);
|
|
562
|
-
return { name: String(l.name), description: typeof l.description === "string" ? l.description : "" };
|
|
563
|
-
});
|
|
564
|
-
} catch {
|
|
565
|
-
return null;
|
|
566
|
-
}
|
|
584
|
+
const r = remoteCache.get(slug, `repos/${slug}/labels`, { paginate: true });
|
|
585
|
+
if (r.status !== "ok") return null;
|
|
586
|
+
return r.items.map((l) => ({ name: String(l.name), description: typeof l.description === "string" ? l.description : "" }));
|
|
567
587
|
}
|
|
568
588
|
|
|
569
589
|
// The repository's own METADATA — name, description, homepage, topics, visibility — which
|
|
@@ -586,6 +606,7 @@ function listRemoteLabels(slug) {
|
|
|
586
606
|
// One issue's state, labels and comments (#441 — a release.final-grant's decision issue), or null
|
|
587
607
|
// when it could not be read. null is never "no decision": the caller fails closed on it.
|
|
588
608
|
function readRemoteIssue(slug, num) {
|
|
609
|
+
if (remoteCache.offline) return null; // --offline: no tracker read (the caller skips the check)
|
|
589
610
|
try {
|
|
590
611
|
return JSON.parse(runGh(["issue", "view", String(num), "--repo", slug, "--json", "state,labels,comments"]));
|
|
591
612
|
} catch {
|
|
@@ -599,11 +620,11 @@ const remoteMetadataCache = new Map();
|
|
|
599
620
|
function readRemoteMetadata(slug) {
|
|
600
621
|
if (remoteMetadataCache.has(slug)) return remoteMetadataCache.get(slug);
|
|
601
622
|
let r;
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
r = { status: "unreadable" };
|
|
623
|
+
const got = remoteCache.get(slug, `repos/${slug}`);
|
|
624
|
+
if (got.status === "offline") r = { status: "offline" };
|
|
625
|
+
else if (got.status !== "ok") r = { status: "unreadable" };
|
|
626
|
+
else {
|
|
627
|
+
try { r = { status: "ok", data: JSON.parse(got.text) }; } catch { r = { status: "unreadable" }; }
|
|
607
628
|
}
|
|
608
629
|
remoteMetadataCache.set(slug, r);
|
|
609
630
|
return r;
|
|
@@ -651,6 +672,7 @@ function makeSource(target) {
|
|
|
651
672
|
return {
|
|
652
673
|
label: target.label,
|
|
653
674
|
kind: "local",
|
|
675
|
+
root,
|
|
654
676
|
exists: existsSync(root),
|
|
655
677
|
readFile: (p) => {
|
|
656
678
|
const f = join(root, p);
|
|
@@ -1112,6 +1134,16 @@ function renderDuration(age, minDays = DURATION_MIN_DAYS) {
|
|
|
1112
1134
|
}
|
|
1113
1135
|
|
|
1114
1136
|
function auditRepo(target, ctx) {
|
|
1137
|
+
remoteCache.begin();
|
|
1138
|
+
const info = auditRepoInner(target, ctx);
|
|
1139
|
+
// #593: where this repo's remote facts came from — cache, revalidated (304), fetched, stale —
|
|
1140
|
+
// and how old the oldest is. Absent when the repo made no GitHub read at all.
|
|
1141
|
+
const remote = remoteCache.summary();
|
|
1142
|
+
if (remote) info.remote = remote;
|
|
1143
|
+
return info;
|
|
1144
|
+
}
|
|
1145
|
+
|
|
1146
|
+
function auditRepoInner(target, ctx) {
|
|
1115
1147
|
const src = makeSource(target);
|
|
1116
1148
|
// #522: the branch list is read by the single-trunk rule (tier B / exposure none|released) AND the
|
|
1117
1149
|
// trunk-exists check below — one read, so a remote target costs one API listing, not three.
|
|
@@ -1303,7 +1335,7 @@ function auditRepo(target, ctx) {
|
|
|
1303
1335
|
if (prefixRaw !== null && prefixRaw !== "machine") fail(`branchPrefix is ${JSON.stringify(prefixRaw)}, expected "machine" (omit for the unprefixed default)`);
|
|
1304
1336
|
|
|
1305
1337
|
// ---- ship-batch (#373) ------------------------------------------------------
|
|
1306
|
-
// Batch landing's opt-in: an integer 1–
|
|
1338
|
+
// Batch landing's opt-in: an integer 1–MAX_BATCH (tools/lib/ship-batch.js parseShipBatch — the one reading
|
|
1307
1339
|
// `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
|
|
1308
1340
|
// to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
|
|
1309
1341
|
// the CI templates' descriptor check too (#416, held to this same parser by
|
|
@@ -1331,6 +1363,17 @@ function auditRepo(target, ctx) {
|
|
|
1331
1363
|
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
1364
|
}
|
|
1333
1365
|
|
|
1366
|
+
// ---- ship-batch-steps (#557) -------------------------------------------------
|
|
1367
|
+
// The sizes an adaptive batch walks through (tools/lib/ship-batch.js parseShipBatchSteps, the
|
|
1368
|
+
// reading `colab ship --batch` uses): ascending whole numbers within ship-batch. Malformed fails
|
|
1369
|
+
// here and in the CI templates' descriptor check, the #416 pattern — ship fails closed to the fixed
|
|
1370
|
+
// size, silently. Steps with no batch to size (ship-batch absent or 1) are inert, so they warn.
|
|
1371
|
+
if (shipBatch.STEPS_KEY in (cfg || {}) && cfg[shipBatch.STEPS_KEY] !== null) {
|
|
1372
|
+
const sCfg = shipBatch.parseShipBatchSteps(cfg);
|
|
1373
|
+
if (!sCfg.valid) fail(`${sCfg.reason} — see project.schema.md, ship-batch-steps`);
|
|
1374
|
+
else if (shipBatch.parseShipBatch(cfg).n <= 1) warn(`${sCfg.reason} is inert without ship-batch > 1 — there is no batch to size`);
|
|
1375
|
+
}
|
|
1376
|
+
|
|
1334
1377
|
// ---- ci-wait-factor (#559) ----------------------------------------------------
|
|
1335
1378
|
// The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
|
|
1336
1379
|
// (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
|
|
@@ -1374,11 +1417,28 @@ function auditRepo(target, ctx) {
|
|
|
1374
1417
|
// read by three consumers). tools/lib/migration-grant.js parseGrantPolicy is the one reading, so
|
|
1375
1418
|
// `colab migration-grant` and the audit cannot disagree. The value is always reported
|
|
1376
1419
|
// (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
|
|
1420
|
+
// but silent. `reviewer` is clean when a round-trip job exists: colab ship honours it under
|
|
1421
|
+
// P+M+HEAD+R (#401), and R needs that job (#494).
|
|
1378
1422
|
{
|
|
1379
1423
|
const pol = migrationGrant.parseGrantPolicy(cfg);
|
|
1380
1424
|
info.migrationGrant = pol.policy;
|
|
1425
|
+
// #598: an undeclared key is not "human, full stop" — the machine-level value (the gating
|
|
1426
|
+
// machine's colab config) may apply, and this audit cannot know which machine gates. So the
|
|
1427
|
+
// source is reported: `repo` (declared here, final) or `undeclared` (repo-local default human,
|
|
1428
|
+
// machine level unread). The round-trip warning below stays on a DECLARED reviewer only: for a
|
|
1429
|
+
// machine-level reviewer the mint itself refuses without the job, which is where it surfaces.
|
|
1430
|
+
info.migrationGrantSource = pol.declared ? "repo" : "undeclared";
|
|
1381
1431
|
if (!pol.valid) fail(pol.reason);
|
|
1432
|
+
// #494: R needs a live `Migration round-trip…` job. Without one every reviewer grant fails R
|
|
1433
|
+
// (the mint and ship both refuse) and the declared policy does nothing — say so here, not at
|
|
1434
|
+
// ship time. A warning: the policy fails safe, back to a human grant.
|
|
1435
|
+
if (pol.valid && pol.policy === "reviewer") {
|
|
1436
|
+
const rt = migrationGrant.roundtripJobWorkflows({ readFile: (p) => src.readFile(p), workflows });
|
|
1437
|
+
info.migrationRoundtrip = rt;
|
|
1438
|
+
if (!rt.length) {
|
|
1439
|
+
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`);
|
|
1440
|
+
}
|
|
1441
|
+
}
|
|
1382
1442
|
}
|
|
1383
1443
|
|
|
1384
1444
|
// ---- ci-grant (#504) -------------------------------------------------------
|
|
@@ -1425,6 +1485,28 @@ function auditRepo(target, ctx) {
|
|
|
1425
1485
|
if (!tr.valid) fail(tr.reason);
|
|
1426
1486
|
}
|
|
1427
1487
|
|
|
1488
|
+
// ---- instruction-files (#602) ---------------------------------------------
|
|
1489
|
+
// `instruction-files: upstream` — a fork whose CLAUDE.md/AGENTS.md belong to the upstream it
|
|
1490
|
+
// tracks; the instruction-file shape is then not judged (checkInstructionFileShape below, and
|
|
1491
|
+
// the shared gate the hook and the CI workflow run). tools/lib/instruction-file.js
|
|
1492
|
+
// parseInstructionFiles is the one reading. An invalid value fails: it reads as absent (judged —
|
|
1493
|
+
// the stricter direction), so the declaration silently does nothing.
|
|
1494
|
+
{
|
|
1495
|
+
const ifl = instructionFile.parseInstructionFiles(cfg);
|
|
1496
|
+
info.instructionFiles = ifl.declared ? ifl.value : null;
|
|
1497
|
+
if (!ifl.valid) fail(ifl.reason);
|
|
1498
|
+
}
|
|
1499
|
+
|
|
1500
|
+
// ---- ci-docs-skip (#570) ----------------------------------------------------
|
|
1501
|
+
// Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
|
|
1502
|
+
// (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
|
|
1503
|
+
// An invalid value fails: the guard reads it as not opted in, so it silently does nothing.
|
|
1504
|
+
{
|
|
1505
|
+
const ds = docsOnlyLib.parseCiDocsSkip(cfg);
|
|
1506
|
+
info.ciDocsSkip = ds.declared && ds.valid ? ds.exclude : null;
|
|
1507
|
+
if (!ds.valid) fail(ds.reason);
|
|
1508
|
+
}
|
|
1509
|
+
|
|
1428
1510
|
// ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
|
|
1429
1511
|
// Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
|
|
1430
1512
|
// the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
|
|
@@ -1523,7 +1605,11 @@ function auditRepo(target, ctx) {
|
|
|
1523
1605
|
// not been reopened. Unreadable fails closed: an automatic production deploy nobody can
|
|
1524
1606
|
// trace to a human's choice is exactly what the grant exists to rule out.
|
|
1525
1607
|
const grant = rel.effective.finalGrant;
|
|
1526
|
-
if (grant) {
|
|
1608
|
+
if (grant && ctx.offline) {
|
|
1609
|
+
// #593: --offline reads no tracker. Recorded, not judged — the run header says once that
|
|
1610
|
+
// remote facts were not read, so this row is never mistaken for a verified grant.
|
|
1611
|
+
info.releaseFinalGrant = { issue: grant.issue, ok: null, checked: false, reason: "--offline" };
|
|
1612
|
+
} else if (grant) {
|
|
1527
1613
|
const v = releasePolicy.finalGrantVerdict(src.issue ? src.issue(grant.issue) : null, { issue: grant.issue, trust: trustHumansLib.parseTrustHumans(cfg) });
|
|
1528
1614
|
info.releaseFinalGrant = { issue: grant.issue, ok: v.ok, ruledBy: v.ruledBy };
|
|
1529
1615
|
if (!v.ok) {
|
|
@@ -1736,10 +1822,16 @@ function auditRepo(target, ctx) {
|
|
|
1736
1822
|
// the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
|
|
1737
1823
|
checkClaudeMdSize(src, warn, th.values);
|
|
1738
1824
|
// #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
|
-
|
|
1825
|
+
// file tools look it up in, is a repo-doc concern on every repo, the handbook's own included —
|
|
1826
|
+
// except the misplaced-Conventions-block half, which is a stamp check: the handbook has no
|
|
1827
|
+
// block to place, and its AGENTS.md says it "follows the colab-handbook" (#587).
|
|
1828
|
+
checkInstructionFileBlocks(src, warn, { self: isSelf });
|
|
1741
1829
|
// #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
|
|
1742
|
-
|
|
1830
|
+
// #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
|
|
1831
|
+
checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null, upstreamOwned: instructionFile.parseInstructionFiles(cfg).exempt });
|
|
1832
|
+
// #599: a caller of the reusable instruction-files workflow narrowed off session branches, or not
|
|
1833
|
+
// dispatchable, defeats the ratchet's point (fail on the branch) and the cure rule's way out.
|
|
1834
|
+
checkInstructionFilesCaller(src, workflows, cfg?.trunk ?? null, warn);
|
|
1743
1835
|
|
|
1744
1836
|
// ---- markdown anchor links resolve (#158) --------------------------------
|
|
1745
1837
|
// Unconditional, same posture as checkClaudeMdSize above: general markdown hygiene,
|
|
@@ -2587,7 +2679,7 @@ function checkClaudeMdSize(src, warn, limits = thresholdsLib.DEFAULTS) {
|
|
|
2587
2679
|
// Both WARN, never FAIL: neither stops anything working, they cost tokens or drift tracking.
|
|
2588
2680
|
// Byte-identical CLAUDE.md and AGENTS.md (a symlinked or copied pair) are ONE file here, or
|
|
2589
2681
|
// every symlinked repo would warn on a duplicate it does not have.
|
|
2590
|
-
function checkInstructionFileBlocks(src, warn) {
|
|
2682
|
+
function checkInstructionFileBlocks(src, warn, { self = false } = {}) {
|
|
2591
2683
|
const read = (p) => src.readFile(p);
|
|
2592
2684
|
const loaded = instructionFile.collectLoaded(read, "CLAUDE.md").files;
|
|
2593
2685
|
const claude = loaded.find((f) => f.path === "CLAUDE.md");
|
|
@@ -2610,6 +2702,9 @@ function checkInstructionFileBlocks(src, warn) {
|
|
|
2610
2702
|
}
|
|
2611
2703
|
}
|
|
2612
2704
|
|
|
2705
|
+
// The handbook source carries no Conventions block by design (it is X, nothing to copy from),
|
|
2706
|
+
// so "the block moved out of CLAUDE.md" cannot be true of it — skip, like every stamp check.
|
|
2707
|
+
if (self) return;
|
|
2613
2708
|
const hasBlock = (t) => !!(parseClaudeStamp(t) || looksLikeHandbookClaude(t));
|
|
2614
2709
|
if (!(claude && hasBlock(claude.text))) {
|
|
2615
2710
|
const elsewhere = scan.filter((f) => f.path !== "CLAUDE.md" && hasBlock(f.text)).map((f) => f.path);
|
|
@@ -2635,10 +2730,38 @@ function checkInstructionFileBlocks(src, warn) {
|
|
|
2635
2730
|
// A repo with neither file is not this check's business (no instruction
|
|
2636
2731
|
// file at all is an adoption gap, reported elsewhere).
|
|
2637
2732
|
//
|
|
2638
|
-
// WARN,
|
|
2639
|
-
//
|
|
2640
|
-
//
|
|
2641
|
-
|
|
2733
|
+
// WARN, and FAIL only under the ratchet (#588): existing repos migrate over time (handbook-sync's
|
|
2734
|
+
// graft step moves the prose), so the finding fails only where `colab instruction-files` would —
|
|
2735
|
+
// a LOCAL repo inside git, judged against merge-base(<base>, HEAD) with <base> = `--base`, else
|
|
2736
|
+
// origin/<trunk>: some CLAUDE.md non-conforming in the working tree AND either a CLAUDE.md/AGENTS.md
|
|
2737
|
+
// changed since the merge base, or every CLAUDE.md conformed there. Same code as the hook and the
|
|
2738
|
+
// reusable workflow (tools/lib/instruction-gate.js), so the three cannot disagree. A remote source,
|
|
2739
|
+
// or a local one with no base to compare against, keeps the warning: no ratchet, no failure.
|
|
2740
|
+
function instructionRatchet(src, opts) {
|
|
2741
|
+
if (src.kind !== "local" || !src.root) return null;
|
|
2742
|
+
const base = opts.base || (opts.trunk ? `origin/${opts.trunk}` : null);
|
|
2743
|
+
if (!base) return null;
|
|
2744
|
+
const r = instructionGate.gate({ cwd: src.root, base, head: "worktree" });
|
|
2745
|
+
if (!r.ok) return opts.base ? { ok: false, error: r.error } : null; // an explicit base that cannot be read is said aloud
|
|
2746
|
+
return r;
|
|
2747
|
+
}
|
|
2748
|
+
|
|
2749
|
+
//
|
|
2750
|
+
// #602: a fork declaring `instruction-files: upstream` is not judged at all — neither the ratchet's
|
|
2751
|
+
// failure nor the two warnings: its CLAUDE.md/AGENTS.md are the upstream's (CONVENTIONS.md §9, *A
|
|
2752
|
+
// fork of an upstream*), and the --json `instructionFiles` field says why nothing was reported.
|
|
2753
|
+
function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
|
|
2754
|
+
if (opts.upstreamOwned) return;
|
|
2755
|
+
const ratchet = instructionRatchet(src, opts);
|
|
2756
|
+
if (ratchet && !ratchet.ok) warn(`instruction-file ratchet not evaluated: ${ratchet.error} (#588)`);
|
|
2757
|
+
if (ratchet && ratchet.ok && ratchet.fail) {
|
|
2758
|
+
const why = ratchet.reason === "touched"
|
|
2759
|
+
? "this change touches CLAUDE.md/AGENTS.md"
|
|
2760
|
+
: "every CLAUDE.md conformed at the merge base, so this regresses the repo";
|
|
2761
|
+
for (const f of ratchet.bad) {
|
|
2762
|
+
fail(`prose-in-claude-md: ${f.message} (CONVENTIONS.md §9 step 5; ratchet: ${why}; \`colab instruction-files --base <rev>\` reproduces it) (#588)`);
|
|
2763
|
+
}
|
|
2764
|
+
}
|
|
2642
2765
|
const claude = src.readFile("CLAUDE.md");
|
|
2643
2766
|
if (claude === null || claude === undefined) return;
|
|
2644
2767
|
const agents = src.readFile("AGENTS.md");
|
|
@@ -2650,6 +2773,7 @@ function checkInstructionFileShape(src, warn) {
|
|
|
2650
2773
|
} else if (agents === claude) {
|
|
2651
2774
|
return;
|
|
2652
2775
|
}
|
|
2776
|
+
if (ratchet && ratchet.ok && ratchet.fail) return; // already reported above, as a failure
|
|
2653
2777
|
const residue = instructionFile.shellResidue(claude);
|
|
2654
2778
|
if (!residue.length) return;
|
|
2655
2779
|
const shape = instructionFile.isThinShell(claude)
|
|
@@ -2677,6 +2801,13 @@ function checkInstructionFileShape(src, warn) {
|
|
|
2677
2801
|
// caller is `deploy: manual` (a human runs it) or `deploy: tag` deployed OUTSIDE CI (a GitOps
|
|
2678
2802
|
// poller runs it). Both share the same invariant: the deploy runs off no in-repo workflow, so the
|
|
2679
2803
|
// path to production must be WRITTEN DOWN or nobody but its author can ship it.
|
|
2804
|
+
// ---- the instruction-files caller's trigger (#599) ---------------------------
|
|
2805
|
+
// The logic lives in tools/lib/workflow-triggers.js beside the other trigger readers. WARN, never
|
|
2806
|
+
// fail: the caller is a copy the repo owns, and handbook-sync's trigger graft is the fix.
|
|
2807
|
+
function checkInstructionFilesCaller(src, workflows, trunk, warn) {
|
|
2808
|
+
for (const f of instructionFilesCallerFindings({ readFile: (p) => src.readFile(p), workflows, trunk })) warn(f.text);
|
|
2809
|
+
}
|
|
2810
|
+
|
|
2680
2811
|
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
2681
2812
|
// The logic lives in tools/lib/workflow-triggers.js (#338) so `colab release cut` refuses on the
|
|
2682
2813
|
// same finding; this maps its severity onto the audit's fail/warn.
|
|
@@ -2811,6 +2942,9 @@ function checkPrivateNpm(src, workflows, fail, warn) {
|
|
|
2811
2942
|
const assetSurface = npmGuard.releaseAssetUploads(workflows, reader.readFile).length > 0;
|
|
2812
2943
|
if (!npmSurface && !assetSurface) return;
|
|
2813
2944
|
const meta = src.metadata ? src.metadata() : { status: "unreadable" };
|
|
2945
|
+
// #593: --offline reads no visibility by request; the run header already says so once, and a
|
|
2946
|
+
// "could not be read" advisory on every offline pass would mark every such repo non-clean.
|
|
2947
|
+
if (meta.status === "offline") return;
|
|
2814
2948
|
let visibility = null;
|
|
2815
2949
|
if (meta.status === "ok" && meta.data) {
|
|
2816
2950
|
visibility = meta.data.visibility || (meta.data.private === true ? "private" : meta.data.private === false ? "public" : null);
|
|
@@ -3162,6 +3296,10 @@ function report(results, opts, ctx) {
|
|
|
3162
3296
|
? { scanned: true, vocabulary: ctx.identity.path, source: ctx.identity.source, terms: ctx.identity.count }
|
|
3163
3297
|
: { scanned: false, reason: "not requested (--identity)" },
|
|
3164
3298
|
batchHistory: ctx.batchHistory ? { read: true } : { read: false, reason: "not requested (--batch-history)" },
|
|
3299
|
+
// #593: whether GitHub was read at all this run, and the cache it was read through.
|
|
3300
|
+
remote: ctx.offline
|
|
3301
|
+
? { read: false, reason: "--offline" }
|
|
3302
|
+
: { read: true, cache: ctx.cache.dir, persistent: !!ctx.cache.dir, ttlSeconds: ctx.cache.ttlSeconds, fresh: ctx.cache.fresh },
|
|
3165
3303
|
results,
|
|
3166
3304
|
}, null, 2));
|
|
3167
3305
|
return;
|
|
@@ -3183,6 +3321,10 @@ function report(results, opts, ctx) {
|
|
|
3183
3321
|
console.log(ctx.batchHistory
|
|
3184
3322
|
? "batch: batch landing history read per local repo (colab batch-stats); advisories only against declared thresholds"
|
|
3185
3323
|
: "batch: batch landing history NOT read (pass --batch-history)");
|
|
3324
|
+
// #593: same once-per-run statement for the remote reads.
|
|
3325
|
+
console.log(ctx.offline
|
|
3326
|
+
? "remote: GitHub NOT read (--offline) — labels, visibility and grants unchecked; remote-only entries skipped"
|
|
3327
|
+
: `remote: GitHub read through ${ctx.cache.dir ? `the cache at ${ctx.cache.dir}` : "an in-memory cache (no colab home to persist it)"}, TTL ${ctx.cache.ttlSeconds}s${ctx.cache.fresh ? ", --fresh" : ""}`);
|
|
3186
3328
|
console.log("");
|
|
3187
3329
|
|
|
3188
3330
|
const shown = opts.quiet ? results.filter((r) => !r.clean) : results;
|
|
@@ -3198,7 +3340,8 @@ function report(results, opts, ctx) {
|
|
|
3198
3340
|
// The handbook's own row says WHY it carries no stamp findings. Without this it
|
|
3199
3341
|
// would read as clean-by-luck, which is indistinguishable from a check that
|
|
3200
3342
|
// quietly stopped working.
|
|
3201
|
-
if (r.
|
|
3343
|
+
if (r.skipped === "offline") lines.push("– skipped (--offline: a remote-only entry has nothing local to check)");
|
|
3344
|
+
else if (r.self) lines.push("⌂ handbook source — every rule applies except its own stamps (it has nothing to copy from)");
|
|
3202
3345
|
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 ? " ✓" : ""}`);
|
|
3203
3346
|
else if (r.clean) lines.push("✓");
|
|
3204
3347
|
r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
|
|
@@ -3215,8 +3358,9 @@ function report(results, opts, ctx) {
|
|
|
3215
3358
|
|
|
3216
3359
|
const failed = results.filter((r) => !r.ok).length;
|
|
3217
3360
|
const warned = results.filter((r) => r.ok && !r.clean).length;
|
|
3361
|
+
const skipped = results.filter((r) => r.skipped).length;
|
|
3218
3362
|
console.log("");
|
|
3219
|
-
console.log(`${results.length} repo(s): ${results.length - failed - warned} clean, ${warned} with advisories, ${failed} with problems.`);
|
|
3363
|
+
console.log(`${results.length} repo(s): ${results.length - failed - warned - skipped} clean, ${warned} with advisories, ${failed} with problems${skipped ? `, ${skipped} skipped` : ""}.`);
|
|
3220
3364
|
}
|
|
3221
3365
|
|
|
3222
3366
|
/**
|
|
@@ -3264,12 +3408,33 @@ function runAudit(opts) {
|
|
|
3264
3408
|
const targets = loadTargets(opts);
|
|
3265
3409
|
if (!targets.length) die("nothing to audit — add entries to the repo list or pass --local <path>");
|
|
3266
3410
|
|
|
3411
|
+
if (opts.offline) {
|
|
3412
|
+
// Each of these is a read of the network the operator asked for; an offline run that quietly
|
|
3413
|
+
// skipped it would report clean over a check that never ran.
|
|
3414
|
+
if (opts.identity) die("--offline and --identity conflict: the identity scan reads repository metadata from GitHub");
|
|
3415
|
+
if (opts.batchHistory) die("--offline and --batch-history conflict: batch history reads CI runs from GitHub");
|
|
3416
|
+
if (opts.fresh) die("--offline and --fresh conflict: --fresh asks GitHub, --offline never does");
|
|
3417
|
+
}
|
|
3418
|
+
const ttlSeconds = auditCache.resolveTtlSeconds(opts.cacheTtl);
|
|
3419
|
+
if (ttlSeconds === null) die(`--cache-ttl / COLAB_AUDIT_CACHE_TTL must be a whole number of seconds (got "${opts.cacheTtl ?? process.env.COLAB_AUDIT_CACHE_TTL}")`);
|
|
3420
|
+
remoteCache = auditCache.create({
|
|
3421
|
+
dir: auditCache.resolveDir(process.env, COLAB_HOME), ttlSeconds, fresh: opts.fresh, offline: opts.offline,
|
|
3422
|
+
});
|
|
3423
|
+
|
|
3267
3424
|
const ctx = { handbook: handbookInfo(HANDBOOK_ROOT), templateNames: templateNames(HANDBOOK_ROOT) };
|
|
3425
|
+
ctx.offline = !!opts.offline;
|
|
3426
|
+
ctx.cache = { dir: remoteCache.dir, ttlSeconds, fresh: !!opts.fresh };
|
|
3268
3427
|
ctx.identity = opts.identity ? loadIdentityVocabulary() : null;
|
|
3269
3428
|
ctx.batchHistory = !!opts.batchHistory;
|
|
3429
|
+
ctx.base = opts.base || null;
|
|
3270
3430
|
|
|
3271
3431
|
const results = [];
|
|
3272
3432
|
for (const t of targets) {
|
|
3433
|
+
if (ctx.offline && t.kind !== "local") {
|
|
3434
|
+
// A slug target has nothing local to check: every fact about it is a GitHub read.
|
|
3435
|
+
results.push({ repo: t.label, kind: t.kind, tier: null, ok: true, clean: true, skipped: "offline", remote: { mode: "offline" }, findings: [] });
|
|
3436
|
+
continue;
|
|
3437
|
+
}
|
|
3273
3438
|
try {
|
|
3274
3439
|
results.push(auditRepo(t, ctx));
|
|
3275
3440
|
} catch (err) {
|
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*.
|