@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.1

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 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,8 @@
39
39
  // # private identity vocabulary — see "Identity" below
40
40
  // node audit.mjs --batch-history # also read each local repo's batch landing history
41
41
  // # (colab batch-stats --json) — see "Batch history" below
42
+ // node audit.mjs --base <rev> # the instruction-file ratchet's base for LOCAL repos
43
+ // # (default origin/<trunk>) — see checkInstructionFileShape
42
44
  //
43
45
  // Identity (--identity): metadata never passes through git, so the pre-commit identity scan
44
46
  // (templates/pre-commit-identity) structurally cannot see it, and it is the first thing a
@@ -123,6 +125,8 @@ const trustHumansLib = require("../tools/lib/trust-humans.js");
123
125
  const hermeticLib = require("../tools/lib/hermetic.js");
124
126
  // #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
125
127
  const treeGreenLib = require("../tools/lib/tree-green.js");
128
+ // #570: the `ci-docs-skip:` opt-in — read through the same module whose rule the CI guard mirrors.
129
+ const docsOnlyLib = require("../tools/lib/docs-only.js");
126
130
  // #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
127
131
  const verifyRunsLib = require("../tools/lib/verify-runs.js");
128
132
  // #410: the optional `gate:` block — read through the same module the skills name.
@@ -130,6 +134,7 @@ const gateLib = require("../tools/lib/gate.js");
130
134
  // #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
131
135
  // shared with `colab adopt` so the shell it writes and the shape the audit checks are one shape.
132
136
  const instructionFile = require("../tools/lib/instruction-file.js");
137
+ const instructionGate = require("../tools/lib/instruction-gate.js"); // #588
133
138
  // #228's identity vocabulary — resolution, parsing, matching and REDACTION. Shared with the
134
139
  // conformance test that holds it and the shell hook (templates/pre-commit-identity) to the
135
140
  // same semantics; the shell scanner cannot require it (a template lands in repos with no
@@ -157,6 +162,11 @@ function parseArgs(argv) {
157
162
  else if (a === "--quiet" || a === "-q") opts.quiet = true;
158
163
  else if (a === "--identity") opts.identity = true;
159
164
  else if (a === "--batch-history") opts.batchHistory = true;
165
+ else if (a === "--base") {
166
+ const p = argv[++i];
167
+ if (!p) die("--base needs a rev");
168
+ opts.base = p;
169
+ }
160
170
  else if (a === "--local") {
161
171
  const p = argv[++i];
162
172
  if (!p) die("--local needs a path");
@@ -651,6 +661,7 @@ function makeSource(target) {
651
661
  return {
652
662
  label: target.label,
653
663
  kind: "local",
664
+ root,
654
665
  exists: existsSync(root),
655
666
  readFile: (p) => {
656
667
  const f = join(root, p);
@@ -1303,7 +1314,7 @@ function auditRepo(target, ctx) {
1303
1314
  if (prefixRaw !== null && prefixRaw !== "machine") fail(`branchPrefix is ${JSON.stringify(prefixRaw)}, expected "machine" (omit for the unprefixed default)`);
1304
1315
 
1305
1316
  // ---- ship-batch (#373) ------------------------------------------------------
1306
- // Batch landing's opt-in: an integer 1–3 (tools/lib/ship-batch.js parseShipBatch — the one reading
1317
+ // Batch landing's opt-in: an integer 1–MAX_BATCH (tools/lib/ship-batch.js parseShipBatch — the one reading
1307
1318
  // `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
1308
1319
  // to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
1309
1320
  // the CI templates' descriptor check too (#416, held to this same parser by
@@ -1331,6 +1342,17 @@ function auditRepo(target, ctx) {
1331
1342
  else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
1332
1343
  }
1333
1344
 
1345
+ // ---- ship-batch-steps (#557) -------------------------------------------------
1346
+ // The sizes an adaptive batch walks through (tools/lib/ship-batch.js parseShipBatchSteps, the
1347
+ // reading `colab ship --batch` uses): ascending whole numbers within ship-batch. Malformed fails
1348
+ // here and in the CI templates' descriptor check, the #416 pattern — ship fails closed to the fixed
1349
+ // size, silently. Steps with no batch to size (ship-batch absent or 1) are inert, so they warn.
1350
+ if (shipBatch.STEPS_KEY in (cfg || {}) && cfg[shipBatch.STEPS_KEY] !== null) {
1351
+ const sCfg = shipBatch.parseShipBatchSteps(cfg);
1352
+ if (!sCfg.valid) fail(`${sCfg.reason} — see project.schema.md, ship-batch-steps`);
1353
+ else if (shipBatch.parseShipBatch(cfg).n <= 1) warn(`${sCfg.reason} is inert without ship-batch > 1 — there is no batch to size`);
1354
+ }
1355
+
1334
1356
  // ---- ci-wait-factor (#559) ----------------------------------------------------
1335
1357
  // The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
1336
1358
  // (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
@@ -1374,11 +1396,28 @@ function auditRepo(target, ctx) {
1374
1396
  // read by three consumers). tools/lib/migration-grant.js parseGrantPolicy is the one reading, so
1375
1397
  // `colab migration-grant` and the audit cannot disagree. The value is always reported
1376
1398
  // (info.migrationGrant). An invalid value fails: the reader falls back to `human`, which is safe
1377
- // but silent. `reviewer` is clean: colab ship honours it under P+M+HEAD+R (#401).
1399
+ // but silent. `reviewer` is clean when a round-trip job exists: colab ship honours it under
1400
+ // P+M+HEAD+R (#401), and R needs that job (#494).
1378
1401
  {
1379
1402
  const pol = migrationGrant.parseGrantPolicy(cfg);
1380
1403
  info.migrationGrant = pol.policy;
1404
+ // #596: an undeclared key is no longer "human, full stop" — the owner-level value (a tracker
1405
+ // record, `colab owner-policy show`) may apply, and this offline audit cannot read it. So the
1406
+ // source is reported: `repo` (declared here, final) or `undeclared` (repo-local default human,
1407
+ // owner level unread). The round-trip warning below stays on a DECLARED reviewer only: for an
1408
+ // owner-level reviewer the mint itself refuses without the job, which is where it surfaces.
1409
+ info.migrationGrantSource = pol.declared ? "repo" : "undeclared";
1381
1410
  if (!pol.valid) fail(pol.reason);
1411
+ // #494: R needs a live `Migration round-trip…` job. Without one every reviewer grant fails R
1412
+ // (the mint and ship both refuse) and the declared policy does nothing — say so here, not at
1413
+ // ship time. A warning: the policy fails safe, back to a human grant.
1414
+ if (pol.valid && pol.policy === "reviewer") {
1415
+ const rt = migrationGrant.roundtripJobWorkflows({ readFile: (p) => src.readFile(p), workflows });
1416
+ info.migrationRoundtrip = rt;
1417
+ if (!rt.length) {
1418
+ warn(`migration-grant: reviewer, but no workflow in .github/workflows has a "${migrationGrant.ROUNDTRIP_JOB_PREFIX}" job — every reviewer grant fails R (the mint and colab ship refuse); adopt the job from templates/ci-laravel.yml or the opt-in block in templates/ci-node.yml, or declare migration-grant: human`);
1419
+ }
1420
+ }
1382
1421
  }
1383
1422
 
1384
1423
  // ---- ci-grant (#504) -------------------------------------------------------
@@ -1425,6 +1464,16 @@ function auditRepo(target, ctx) {
1425
1464
  if (!tr.valid) fail(tr.reason);
1426
1465
  }
1427
1466
 
1467
+ // ---- ci-docs-skip (#570) ----------------------------------------------------
1468
+ // Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
1469
+ // (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
1470
+ // An invalid value fails: the guard reads it as not opted in, so it silently does nothing.
1471
+ {
1472
+ const ds = docsOnlyLib.parseCiDocsSkip(cfg);
1473
+ info.ciDocsSkip = ds.declared && ds.valid ? ds.exclude : null;
1474
+ if (!ds.valid) fail(ds.reason);
1475
+ }
1476
+
1428
1477
  // ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
1429
1478
  // Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
1430
1479
  // the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
@@ -1736,10 +1785,13 @@ function auditRepo(target, ctx) {
1736
1785
  // the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
1737
1786
  checkClaudeMdSize(src, warn, th.values);
1738
1787
  // #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
1739
- // file tools look it up in, is a repo-doc concern on every repo, the handbook's own included.
1740
- checkInstructionFileBlocks(src, warn);
1788
+ // file tools look it up in, is a repo-doc concern on every repo, the handbook's own included —
1789
+ // except the misplaced-Conventions-block half, which is a stamp check: the handbook has no
1790
+ // block to place, and its AGENTS.md says it "follows the colab-handbook" (#587).
1791
+ checkInstructionFileBlocks(src, warn, { self: isSelf });
1741
1792
  // #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
1742
- checkInstructionFileShape(src, warn);
1793
+ // #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
1794
+ checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null });
1743
1795
 
1744
1796
  // ---- markdown anchor links resolve (#158) --------------------------------
1745
1797
  // Unconditional, same posture as checkClaudeMdSize above: general markdown hygiene,
@@ -2587,7 +2639,7 @@ function checkClaudeMdSize(src, warn, limits = thresholdsLib.DEFAULTS) {
2587
2639
  // Both WARN, never FAIL: neither stops anything working, they cost tokens or drift tracking.
2588
2640
  // Byte-identical CLAUDE.md and AGENTS.md (a symlinked or copied pair) are ONE file here, or
2589
2641
  // every symlinked repo would warn on a duplicate it does not have.
2590
- function checkInstructionFileBlocks(src, warn) {
2642
+ function checkInstructionFileBlocks(src, warn, { self = false } = {}) {
2591
2643
  const read = (p) => src.readFile(p);
2592
2644
  const loaded = instructionFile.collectLoaded(read, "CLAUDE.md").files;
2593
2645
  const claude = loaded.find((f) => f.path === "CLAUDE.md");
@@ -2610,6 +2662,9 @@ function checkInstructionFileBlocks(src, warn) {
2610
2662
  }
2611
2663
  }
2612
2664
 
2665
+ // The handbook source carries no Conventions block by design (it is X, nothing to copy from),
2666
+ // so "the block moved out of CLAUDE.md" cannot be true of it — skip, like every stamp check.
2667
+ if (self) return;
2613
2668
  const hasBlock = (t) => !!(parseClaudeStamp(t) || looksLikeHandbookClaude(t));
2614
2669
  if (!(claude && hasBlock(claude.text))) {
2615
2670
  const elsewhere = scan.filter((f) => f.path !== "CLAUDE.md" && hasBlock(f.text)).map((f) => f.path);
@@ -2635,10 +2690,33 @@ function checkInstructionFileBlocks(src, warn) {
2635
2690
  // A repo with neither file is not this check's business (no instruction
2636
2691
  // file at all is an adoption gap, reported elsewhere).
2637
2692
  //
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) {
2693
+ // WARN, and FAIL only under the ratchet (#588): existing repos migrate over time (handbook-sync's
2694
+ // graft step moves the prose), so the finding fails only where `colab instruction-files` would —
2695
+ // a LOCAL repo inside git, judged against merge-base(<base>, HEAD) with <base> = `--base`, else
2696
+ // origin/<trunk>: some CLAUDE.md non-conforming in the working tree AND either a CLAUDE.md/AGENTS.md
2697
+ // changed since the merge base, or every CLAUDE.md conformed there. Same code as the hook and the
2698
+ // reusable workflow (tools/lib/instruction-gate.js), so the three cannot disagree. A remote source,
2699
+ // or a local one with no base to compare against, keeps the warning: no ratchet, no failure.
2700
+ function instructionRatchet(src, opts) {
2701
+ if (src.kind !== "local" || !src.root) return null;
2702
+ const base = opts.base || (opts.trunk ? `origin/${opts.trunk}` : null);
2703
+ if (!base) return null;
2704
+ const r = instructionGate.gate({ cwd: src.root, base, head: "worktree" });
2705
+ if (!r.ok) return opts.base ? { ok: false, error: r.error } : null; // an explicit base that cannot be read is said aloud
2706
+ return r;
2707
+ }
2708
+
2709
+ function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
2710
+ const ratchet = instructionRatchet(src, opts);
2711
+ if (ratchet && !ratchet.ok) warn(`instruction-file ratchet not evaluated: ${ratchet.error} (#588)`);
2712
+ if (ratchet && ratchet.ok && ratchet.fail) {
2713
+ const why = ratchet.reason === "touched"
2714
+ ? "this change touches CLAUDE.md/AGENTS.md"
2715
+ : "every CLAUDE.md conformed at the merge base, so this regresses the repo";
2716
+ for (const f of ratchet.bad) {
2717
+ fail(`prose-in-claude-md: ${f.message} (CONVENTIONS.md §9 step 5; ratchet: ${why}; \`colab instruction-files --base <rev>\` reproduces it) (#588)`);
2718
+ }
2719
+ }
2642
2720
  const claude = src.readFile("CLAUDE.md");
2643
2721
  if (claude === null || claude === undefined) return;
2644
2722
  const agents = src.readFile("AGENTS.md");
@@ -2650,6 +2728,7 @@ function checkInstructionFileShape(src, warn) {
2650
2728
  } else if (agents === claude) {
2651
2729
  return;
2652
2730
  }
2731
+ if (ratchet && ratchet.ok && ratchet.fail) return; // already reported above, as a failure
2653
2732
  const residue = instructionFile.shellResidue(claude);
2654
2733
  if (!residue.length) return;
2655
2734
  const shape = instructionFile.isThinShell(claude)
@@ -3267,6 +3346,7 @@ function runAudit(opts) {
3267
3346
  const ctx = { handbook: handbookInfo(HANDBOOK_ROOT), templateNames: templateNames(HANDBOOK_ROOT) };
3268
3347
  ctx.identity = opts.identity ? loadIdentityVocabulary() : null;
3269
3348
  ctx.batchHistory = !!opts.batchHistory;
3349
+ ctx.base = opts.base || null;
3270
3350
 
3271
3351
  const results = [];
3272
3352
  for (const t of targets) {
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.1"
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*.