@futurelastic/colab-handbook 1.16.0-rc.1 → 1.16.0-rc.3

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
@@ -21,7 +21,7 @@ colab register # adds the repo to this machine's fleet list
21
21
  ```
22
22
 
23
23
  Then, in an agent session in that repo, run the `code-start` skill with an issue
24
- number — each engine has its own way to invoke a skill, see [*Choose your engine*](#choose-your-engine).
24
+ number — each agent runtime has its own way to invoke a skill, see [*Choose your agent runtime*](#choose-your-agent-runtime).
25
25
  With an agent at hand, the `handbook-sync` skill replaces the last three commands and also does
26
26
  the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
27
27
  You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
@@ -115,7 +115,7 @@ with a pointer to [#604](https://github.com/futurelastic/colab-handbook/issues/6
115
115
  ## Your first session
116
116
 
117
117
  A unit of work goes round one loop. Each step is a skill, invoked by name in an
118
- agent session (the syntax is the engine's — [*Choose your engine*](#choose-your-engine)),
118
+ agent session (the syntax is the agent runtime's — [*Choose your agent runtime*](#choose-your-agent-runtime)),
119
119
  or followed by hand from [`skills/`](skills/).
120
120
 
121
121
  | Step | Skill | Who runs it | What it leaves behind |
@@ -235,9 +235,9 @@ the step you are refining by its number (`code-ship` B1c, `code-sweep` §3): a
235
235
  large skill is a short core plus reference files, and the core keeps every
236
236
  step's number.
237
237
 
238
- Claude Code loads the file into the skill automatically. Other engines get a
238
+ Claude Code loads the file into the skill automatically. Other agent runtimes get a
239
239
  plain sentence in each skill telling the agent to read the file, which works
240
- without any engine support. Because the file instructs agents, a change to it
240
+ without any runtime support. Because the file instructs agents, a change to it
241
241
  is never treated as docs-only: it merges on `auto-trunk` or a human's go, like a
242
242
  `CLAUDE.md` change. Rule:
243
243
  [`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
@@ -265,7 +265,7 @@ migration hold with or without it.
265
265
  | [`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). |
266
266
  | [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. What each check means: [`audit/README.md`](audit/README.md). |
267
267
  | [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Plain `SKILL.md` folders; `install.sh` links them into each coding agent you choose. |
268
- | [`engines/`](engines/) | One small data file per coding agent: where its user-level skills go, how a skill is invoked, what it supports. Adding an engine is adding a file — [`engines/README.md`](engines/README.md). |
268
+ | [`engines/`](engines/) | One small data file per agent runtime: where its user-level skills go, how a skill is invoked, what it supports. Adding an agent runtime is adding a file — [`engines/README.md`](engines/README.md). |
269
269
  | [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
270
270
 
271
271
  ## Setting up a machine
@@ -289,12 +289,12 @@ Later moves are explicit:
289
289
  A clone with uncommitted changes is never moved, and a re-run without either
290
290
  flag keeps whatever is checked out.
291
291
 
292
- ### Choose your engine
292
+ ### Choose your agent runtime
293
293
 
294
294
  The skills are plain `SKILL.md` folders that call `git`, `gh` and `colab`; any
295
295
  coding agent that reads skills can run them. What differs is **where each
296
296
  agent looks for them**, so the install asks. At a terminal, `./install.sh`
297
- lists the engines it knows and lets you pick one or more, with *other: give a
297
+ lists the agent runtimes it knows and lets you pick one or more, with *other: give a
298
298
  path* last. Unattended, say it with a flag:
299
299
 
300
300
  ```sh
@@ -303,21 +303,21 @@ path* last. Unattended, say it with a flag:
303
303
  ./install.sh --skills-dir ~/my-agent/skills # any other agent: you give its folder
304
304
  ```
305
305
 
306
- | Engine | Skills folder | Invoke | Before the skills work there |
306
+ | Agent runtime | Skills folder | Invoke | Before the skills work there |
307
307
  |---|---|---|---|
308
308
  | Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Nothing. This user-level install **wins** over a repo's own `.claude/skills/<name>` of the same name (precedence is enterprise > personal > project), so rename a repo variant you want used. |
309
309
  | OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Its default sandbox has no network, so `gh` fails: set `[sandbox_workspace_write] network_access = true` in `~/.codex/config.toml`. Values from Codex's docs; not yet verified by a clean-machine run. |
310
310
  | anything else | `--skills-dir <path>` | the agent's own way | The agent's shell needs network access for `gh`. The folder is remembered in `~/.colab/skills-dirs`. |
311
311
 
312
- A re-run with no flag and no terminal keeps every engine it finds already
312
+ A re-run with no flag and no terminal keeps every agent runtime it finds already
313
313
  linked, so an existing machine changes nothing. Finding none, it installs for
314
- Claude Code and says so. The per-engine facts live in [`engines/`](engines/),
314
+ Claude Code and says so. The per-runtime facts live in [`engines/`](engines/),
315
315
  one file each — that folder is the source for the table above.
316
316
 
317
317
  | Flag | What it does |
318
318
  |---|---|
319
- | *(none)* | Symlink `skills/` into each chosen engine's user-level folder, so they are available in every repo you open. Asks at a terminal; otherwise keeps what is linked (see [*Choose your engine*](#choose-your-engine)). |
320
- | `--engine <id>[,<id>]` | Install for these engines (`claude`, `codex` — the files in `engines/`), no question asked. |
319
+ | *(none)* | Symlink `skills/` into each chosen agent runtime's user-level folder, so they are available in every repo you open. Asks at a terminal; otherwise keeps what is linked (see [*Choose your agent runtime*](#choose-your-agent-runtime)). |
320
+ | `--engine <id>[,<id>]` | Install for these agent runtimes (`claude`, `codex` — the files in `engines/`), no question asked. |
321
321
  | `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
322
322
  | `--tools` | The `colab` CLI twice: a **symlink** at `~/.local/bin/colab` for your sessions (it prints the `PATH` line if needed), and a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services. Also creates an empty `~/.colab/state.json` if there is none. |
323
323
  | `--hooks` | Point this clone's git at `.githooks/`: a gitleaks secret scan and an identity scan whose vocabulary you keep outside every repo (see [`templates/README.md`](templates/README.md)). |
@@ -353,8 +353,8 @@ node audit/audit.mjs # a conformance report across every registered repo
353
353
  colab update # stamped copies that fell behind, the frozen CLI included
354
354
  ```
355
355
 
356
- `--check` reports, per engine, how many skills are linked, missing or broken,
357
- plus that engine's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
356
+ `--check` reports, per agent runtime, how many skills are linked, missing or broken,
357
+ plus that runtime's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
358
358
  which commands it does not dispatch, whether the state file exists, whether
359
359
  anything is registered, whether both pre-commit hooklets can run, and whether
360
360
  `notifyUrl` is unset, or lacks a URL, while a local observer declared one. ✗ means
package/README.vi.md CHANGED
@@ -20,7 +20,7 @@ colab register # đưa repo vào danh sách fleet của máy này
20
20
  ```
21
21
 
22
22
  Sau đó, trong một phiên agent ở repo đó, chạy skill `code-start` kèm số issue —
23
- mỗi engine có cách gọi skill riêng, xem [*Chọn engine*](#chọn-engine). Có agent
23
+ mỗi agent runtime có cách gọi skill riêng, xem [*Chọn agent runtime*](#chọn-agent-runtime). Có agent
24
24
  trong tay thì skill `handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
25
25
  lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
26
26
  và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
@@ -114,7 +114,7 @@ production đủ 7 ngày. Thông báo nằm ở đầu
114
114
  ## Phiên làm việc đầu tiên
115
115
 
116
116
  Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi theo tên trong phiên
117
- agent (cú pháp gọi là của engine — [*Chọn engine*](#chọn-engine)), hoặc tự làm
117
+ agent (cú pháp gọi là của agent runtime — [*Chọn agent runtime*](#chọn-agent-runtime)), hoặc tự làm
118
118
  theo bằng tay từ [`skills/`](skills/).
119
119
 
120
120
  | Bước | Skill | Ai chạy | Để lại gì |
@@ -234,8 +234,8 @@ chối thì vẫn bị từ chối. Hãy gọi bước bạn muốn chỉnh theo
234
234
  B1c, `code-sweep` §3): một skill lớn gồm một phần lõi ngắn cộng các file tham
235
235
  chiếu, và phần lõi giữ số của mọi bước.
236
236
 
237
- Claude Code tự nạp file vào skill. Các engine khác có một câu thường trong mỗi
238
- skill bảo agent đọc file, cách này chạy được mà không cần engine hỗ trợ gì.
237
+ Claude Code tự nạp file vào skill. Các agent runtime khác có một câu thường trong mỗi
238
+ skill bảo agent đọc file, cách này chạy được mà không cần runtime hỗ trợ gì.
239
239
  Vì file này ra lệnh cho agent, thay đổi trong nó không bao giờ được coi là
240
240
  docs-only: nó merge bằng `auto-trunk` hoặc khi có người duyệt, giống một thay đổi
241
241
  `CLAUDE.md`. Quy tắc:
@@ -264,7 +264,7 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
264
264
  | [`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). |
265
265
  | [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
266
266
  | [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). Là các thư mục `SKILL.md` thuần; `install.sh` link chúng vào từng coding agent bạn chọn. |
267
- | [`engines/`](engines/) | Mỗi coding agent một file dữ liệu nhỏ: skill cấp user đặt ở đâu, gọi skill thế nào, agent hỗ trợ gì. Thêm engine là thêm một file — [`engines/README.md`](engines/README.md). |
267
+ | [`engines/`](engines/) | Mỗi agent runtime một file dữ liệu nhỏ: skill cấp user đặt ở đâu, gọi skill thế nào, agent hỗ trợ gì. Thêm agent runtime là thêm một file — [`engines/README.md`](engines/README.md). |
268
268
  | [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
269
269
 
270
270
  ## Cài đặt máy
@@ -288,12 +288,12 @@ sau đều phải chủ động:
288
288
  Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
289
289
  không kèm flag nào thì giữ nguyên thứ đang checkout.
290
290
 
291
- ### Chọn engine
291
+ ### Chọn agent runtime
292
292
 
293
293
  Các skill là thư mục `SKILL.md` thuần, chỉ gọi `git`, `gh` và `colab`; coding
294
294
  agent nào đọc được skill thì chạy được chúng. Khác nhau là **mỗi agent tìm
295
295
  skill ở đâu**, nên bản cài sẽ hỏi. Ở terminal, `./install.sh` liệt kê các
296
- engine nó biết và cho bạn chọn một hoặc nhiều, lựa chọn cuối là *other: give a
296
+ agent runtime nó biết và cho bạn chọn một hoặc nhiều, lựa chọn cuối là *other: give a
297
297
  path*. Chạy không người trông thì nói bằng flag:
298
298
 
299
299
  ```sh
@@ -302,21 +302,21 @@ path*. Chạy không người trông thì nói bằng flag:
302
302
  ./install.sh --skills-dir ~/my-agent/skills # agent khác: bạn đưa thư mục của nó
303
303
  ```
304
304
 
305
- | Engine | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
305
+ | Agent runtime | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
306
306
  |---|---|---|---|
307
307
  | Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Không cần gì. Bản cài cấp user này **thắng** `.claude/skills/<name>` cùng tên của repo (thứ tự ưu tiên là enterprise > personal > project), nên muốn dùng bản của repo thì đổi tên nó. |
308
308
  | OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Sandbox mặc định không có mạng nên `gh` lỗi: đặt `[sandbox_workspace_write] network_access = true` trong `~/.codex/config.toml`. Số liệu lấy từ tài liệu của Codex; chưa được xác minh bằng một lần chạy trên máy sạch. |
309
309
  | agent khác | `--skills-dir <path>` | theo cách của agent | Shell của agent cần có mạng cho `gh`. Thư mục được ghi nhớ trong `~/.colab/skills-dirs`. |
310
310
 
311
- Chạy lại không flag và không có terminal thì giữ mọi engine đã thấy được link
312
- sẵn, nên máy đã cài không thay đổi gì. Không thấy engine nào thì cài cho Claude
313
- Code và nói rõ điều đó. Thông tin từng engine nằm trong [`engines/`](engines/),
314
- mỗi engine một file — thư mục đó là nguồn của bảng trên.
311
+ Chạy lại không flag và không có terminal thì giữ mọi agent runtime đã thấy được link
312
+ sẵn, nên máy đã cài không thay đổi gì. Không thấy agent runtime nào thì cài cho Claude
313
+ Code và nói rõ điều đó. Thông tin từng agent runtime nằm trong [`engines/`](engines/),
314
+ mỗi agent runtime một file — thư mục đó là nguồn của bảng trên.
315
315
 
316
316
  | Flag | Làm gì |
317
317
  |---|---|
318
- | *(không có)* | Symlink `skills/` vào thư mục cấp user của từng engine đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn engine*](#chọn-engine)). |
319
- | `--engine <id>[,<id>]` | Cài cho các engine này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
318
+ | *(không có)* | Symlink `skills/` vào thư mục cấp user của từng agent runtime đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn agent runtime*](#chọn-agent-runtime)). |
319
+ | `--engine <id>[,<id>]` | Cài cho các agent runtime này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
320
320
  | `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
321
321
  | `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
322
322
  | `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
@@ -351,8 +351,8 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
351
351
  colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
352
352
  ```
353
353
 
354
- `--check` báo theo từng engine: bao nhiêu skill đã link, thiếu hay hỏng, kèm
355
- các lưu ý riêng của engine đó (ví dụ mạng trong sandbox của Codex). Nó cũng báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
354
+ `--check` báo theo từng agent runtime: bao nhiêu skill đã link, thiếu hay hỏng, kèm
355
+ các lưu ý riêng của runtime đó (ví dụ mạng trong sandbox của Codex). Nó cũng báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
356
356
  nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
357
357
  hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống (hoặc
358
358
  thiếu một URL) trong khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
package/audit/audit.mjs CHANGED
@@ -91,6 +91,8 @@ const stamp = require("../tools/lib/stamp.js");
91
91
  const { missingConventionLabels, staleConventionDescriptions, MINIMAL_LABEL_NAMES } = require("../tools/lib/labels.js");
92
92
  // #393: "adopted locally, not committed" — one classifier, shared with `colab adopt --local`.
93
93
  const { localAdoptionState } = require("../tools/lib/local-adopt.js");
94
+ // #158 heading slugs, shared with the rule-inventory check (#632).
95
+ const { collectHeadingSlugs } = require("../tools/lib/md-anchors.js");
94
96
  // #144's authority-flip precedence ladder — shared with `tools/colab` for the same reason
95
97
  // every other cross-tool reading in this file is: two implementations of "which key governs"
96
98
  // is exactly the two-places-drift disease this handbook exists to kill.
@@ -2505,59 +2507,9 @@ function splitDerivedSpans(text) {
2505
2507
  return { authoredLines, malformed };
2506
2508
  }
2507
2509
 
2508
- // Minimal GitHub-compatible heading→anchor slugifier (#158). GitHub's real algorithm is
2509
- // unpublished; this is deliberately the common-case subset, calibrated against the 47
2510
- // anchor links already live in this repo (CLAUDE.md, CONVENTIONS.md, README*.md,
2511
- // project.schema.md, skills/handbook-sync/SKILL.md, tools/README.md) — every one of
2512
- // them resolves under it. Not a general markdown-heading parser: it does not need to be,
2513
- // because the only headings it is ever asked to slugify are the ones already governing
2514
- // the links this check exists to validate.
2515
- function slugifyHeading(text) {
2516
- return text
2517
- .replace(/`([^`]*)`/g, "$1") // code spans contribute their literal text, not backticks
2518
- .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) contributes only the text
2519
- .trim()
2520
- .replace(/#+$/, "") // a trailing "##" some repos use to mark a self-anchor
2521
- .toLowerCase()
2522
- // strip punctuation, keep Unicode letters/digits, underscore, hyphens/spaces -- NOT
2523
- // collapsed. `\w` is ASCII-only ([A-Za-z0-9_]); GitHub's real slugifier keeps Unicode
2524
- // letters (Vietnamese, Japanese, accented Latin, ...), so `\w` alone silently deleted
2525
- // them and produced a slug GitHub never renders (#280). `\p{L}`/`\p{N}` (with the `/u`
2526
- // flag) widen letter/digit matching to Unicode while `_` stays its own explicit member
2527
- // of the class -- it must NOT be folded into `\p{L}`/`\p{N}`, because the very next
2528
- // step below (`.replace(/[ _]/g, "-")`) turns underscores into hyphens and needs them
2529
- // to survive this line to do it; the issue's own one-line suggestion dropped `_` from
2530
- // the class and would have silently broken every underscored heading slug.
2531
- .replace(/[^\p{L}\p{N}_\- ]+/gu, "")
2532
- .trim()
2533
- // Each space/underscore becomes its OWN hyphen -- never collapsed. GitHub does not
2534
- // merge runs: a heading like "tier -- required" strips the em-dash but keeps both
2535
- // spaces around where it was, producing "tier--required" (double hyphen), and every
2536
- // link already written against a real heading in this repo is punctuated that way.
2537
- // Collapsing here silently breaks every one of them.
2538
- .replace(/[ _]/g, "-");
2539
- }
2540
-
2541
- // Every heading in `text`, in document order, mapped to its resolved slug — including
2542
- // GitHub's duplicate-slug suffixing (`-1`, `-2`, … in heading order, not alphabetical).
2543
- // Fenced code blocks are skipped so a `#` inside a code sample is never read as a heading.
2544
- function collectHeadingSlugs(text) {
2545
- const slugs = new Set();
2546
- const seen = new Map(); // base slug -> next suffix to try
2547
- let inFence = false;
2548
- for (const line of text.split("\n")) {
2549
- if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
2550
- if (inFence) continue;
2551
- const m = /^#{1,6}\s+(.+?)\s*$/.exec(line);
2552
- if (!m) continue;
2553
- const base = slugifyHeading(m[1]);
2554
- if (!base) continue;
2555
- const n = seen.get(base) ?? 0;
2556
- seen.set(base, n + 1);
2557
- slugs.add(n === 0 ? base : `${base}-${n}`);
2558
- }
2559
- return slugs;
2560
- }
2510
+ // slugifyHeading + collectHeadingSlugs live in tools/lib/md-anchors.js (#632) — one slugifier,
2511
+ // shared with scripts/check-rule-inventory.mjs, so an inventory `dest#anchor` and a doc link
2512
+ // cannot disagree about what a heading's anchor is.
2561
2513
 
2562
2514
  // Every `](target#fragment)` markdown link, repo-relative to the file that carries it.
2563
2515
  // `target` is `""` for a same-file link (`[…](#slug)`); anything already resolved by the
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.16.0-rc.1"
36
+ "version": "1.16.0-rc.3"
37
37
  }
@@ -175,7 +175,7 @@ colab template ci-python --dest .github/workflows/ci.yml --roundtrip --roundtrip
175
175
 
176
176
  ### Migration round-trip — what the Laravel job proves, and what it cannot
177
177
 
178
- `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
178
+ `ci-laravel.yml`'s `migrations` job runs every migration **twice per database engine**: once from
179
179
  zero, then — after rolling back the migrations the change adds and seeding rows at the
180
180
  schema *before* the change — once more, the way a deploy lands new migrations on data
181
181
  that predates them. The schema after both passes must match. Two things to know before
@@ -0,0 +1,60 @@
1
+ 'use strict';
2
+ // md-anchors — the heading-to-anchor slugs a markdown link or an inventory `dest#anchor` resolves
3
+ // against. Moved out of audit/audit.mjs (#158) by #632 so the audit and
4
+ // scripts/check-rule-inventory.mjs share one slugifier.
5
+
6
+ // Minimal GitHub-compatible heading→anchor slugifier (#158). GitHub's real algorithm is
7
+ // unpublished; this is deliberately the common-case subset, calibrated against the 47
8
+ // anchor links already live in this repo (CLAUDE.md, CONVENTIONS.md, README*.md,
9
+ // project.schema.md, skills/handbook-sync/SKILL.md, tools/README.md) — every one of
10
+ // them resolves under it. Not a general markdown-heading parser: it does not need to be,
11
+ // because the only headings it is ever asked to slugify are the ones already governing
12
+ // the links this check exists to validate.
13
+ function slugifyHeading(text) {
14
+ return text
15
+ .replace(/`([^`]*)`/g, "$1") // code spans contribute their literal text, not backticks
16
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) contributes only the text
17
+ .trim()
18
+ .replace(/#+$/, "") // a trailing "##" some repos use to mark a self-anchor
19
+ .toLowerCase()
20
+ // strip punctuation, keep Unicode letters/digits, underscore, hyphens/spaces -- NOT
21
+ // collapsed. `\w` is ASCII-only ([A-Za-z0-9_]); GitHub's real slugifier keeps Unicode
22
+ // letters (Vietnamese, Japanese, accented Latin, ...), so `\w` alone silently deleted
23
+ // them and produced a slug GitHub never renders (#280). `\p{L}`/`\p{N}` (with the `/u`
24
+ // flag) widen letter/digit matching to Unicode while `_` stays its own explicit member
25
+ // of the class -- it must NOT be folded into `\p{L}`/`\p{N}`, because the very next
26
+ // step below (`.replace(/[ _]/g, "-")`) turns underscores into hyphens and needs them
27
+ // to survive this line to do it; the issue's own one-line suggestion dropped `_` from
28
+ // the class and would have silently broken every underscored heading slug.
29
+ .replace(/[^\p{L}\p{N}_\- ]+/gu, "")
30
+ .trim()
31
+ // Each space/underscore becomes its OWN hyphen -- never collapsed. GitHub does not
32
+ // merge runs: a heading like "tier -- required" strips the em-dash but keeps both
33
+ // spaces around where it was, producing "tier--required" (double hyphen), and every
34
+ // link already written against a real heading in this repo is punctuated that way.
35
+ // Collapsing here silently breaks every one of them.
36
+ .replace(/[ _]/g, "-");
37
+ }
38
+
39
+ // Every heading in `text`, in document order, mapped to its resolved slug — including
40
+ // GitHub's duplicate-slug suffixing (`-1`, `-2`, … in heading order, not alphabetical).
41
+ // Fenced code blocks are skipped so a `#` inside a code sample is never read as a heading.
42
+ function collectHeadingSlugs(text) {
43
+ const slugs = new Set();
44
+ const seen = new Map(); // base slug -> next suffix to try
45
+ let inFence = false;
46
+ for (const line of text.split("\n")) {
47
+ if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
48
+ if (inFence) continue;
49
+ const m = /^#{1,6}\s+(.+?)\s*$/.exec(line);
50
+ if (!m) continue;
51
+ const base = slugifyHeading(m[1]);
52
+ if (!base) continue;
53
+ const n = seen.get(base) ?? 0;
54
+ seen.set(base, n + 1);
55
+ slugs.add(n === 0 ? base : `${base}-${n}`);
56
+ }
57
+ return slugs;
58
+ }
59
+
60
+ module.exports = { slugifyHeading, collectHeadingSlugs };