@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.
Files changed (44) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +218 -53
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/templates/release-auto.yml +16 -3
  14. package/tools/colab +884 -98
  15. package/tools/lib/adopt.js +1 -1
  16. package/tools/lib/audit-cache.js +277 -0
  17. package/tools/lib/batch-stats.js +66 -43
  18. package/tools/lib/ci-cure.js +10 -1
  19. package/tools/lib/claim-comments.js +3 -2
  20. package/tools/lib/codec/decision.d.ts +7 -0
  21. package/tools/lib/codec/decision.js +54 -0
  22. package/tools/lib/codec/hold.d.ts +8 -1
  23. package/tools/lib/codec/hold.js +42 -8
  24. package/tools/lib/codec/release.js +6 -3
  25. package/tools/lib/codec/samples.json +45 -0
  26. package/tools/lib/config-set.js +4 -3
  27. package/tools/lib/cure-diff.js +27 -1
  28. package/tools/lib/decision-record.js +42 -0
  29. package/tools/lib/docs-only.js +47 -0
  30. package/tools/lib/git.js +57 -8
  31. package/tools/lib/grant-policy.js +133 -0
  32. package/tools/lib/instruction-file.js +75 -0
  33. package/tools/lib/instruction-gate.js +179 -0
  34. package/tools/lib/landed-prs.js +58 -0
  35. package/tools/lib/migration-grant.js +29 -5
  36. package/tools/lib/owner-policy.js +110 -0
  37. package/tools/lib/release-cut.js +127 -10
  38. package/tools/lib/release-finalize.js +66 -5
  39. package/tools/lib/ship-batch.js +188 -14
  40. package/tools/lib/ship-handoff.js +212 -0
  41. package/tools/lib/stamp.js +6 -2
  42. package/tools/lib/template-trunk.js +80 -0
  43. package/tools/lib/tree-green.js +21 -4
  44. 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 [`CLAUDE.md`](CLAUDE.md).**
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
- | [`CLAUDE.md`](CLAUDE.md) | The entry point for AI agents — the operational distillation (EN). |
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 [`CLAUDE.md`](CLAUDE.md).**
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
- | [`CLAUDE.md`](CLAUDE.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
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
- try {
511
- return runGh(["api", `repos/${slug}/contents/${path}`, "-H", "Accept: application/vnd.github.raw"]);
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 out = runGh(["api", `repos/${slug}/contents/${path}`, "--jq", ".[].name"]);
520
- return out.split("\n").map((s) => s.trim()).filter(Boolean);
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
- try {
528
- const out = runGh(["api", `repos/${slug}/branches`, "--paginate", "--jq", ".[].name"]);
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
- try {
541
- const out = runGh(["api", `repos/${slug}/tags`, "--paginate", "--jq", ".[].name"]);
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) — one JSON object per line from `--jq`, so a
555
- // paginated read never has to splice arrays. A line that does not parse makes the whole read
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
- try {
559
- const out = runGh(["api", `repos/${slug}/labels`, "--paginate", "--jq", ".[] | {name, description}"]);
560
- return out.split("\n").map((s) => s.trim()).filter(Boolean).map((line) => {
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
- try {
603
- const out = runGh(["api", `repos/${slug}`]);
604
- r = { status: "ok", data: JSON.parse(out) };
605
- } catch {
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–3 (tools/lib/ship-batch.js parseShipBatch — the one reading
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 P+M+HEAD+R (#401).
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
- checkInstructionFileBlocks(src, warn);
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
- checkInstructionFileShape(src, warn);
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, never FAIL: existing repos migrate over time (handbook-sync's graft step moves the prose).
2639
- // Byte-identical CLAUDE.md and AGENTS.md (a symlinked or copied pair) are one file here, as in
2640
- // checkInstructionFileBlocks: there is nothing to move, and the prose is loaded once.
2641
- function checkInstructionFileShape(src, warn) {
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.self) lines.push("⌂ handbook source — every rule applies except its own stamps (it has nothing to copy from)");
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
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0"
36
+ "version": "1.14.0-rc.10"
37
37
  }
@@ -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.** On a repo whose trunk has another
71
- name, edit both. Until you do, the guard simply never fires on trunk — nothing breaks.
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 three
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*.