chore(docs): keep internal references out of docs and commit messages (LAB-8003)

.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+# Pre-commit hooks. Install once per clone: prek install (Python pre-commit works too).
+default_install_hook_types: [pre-commit, commit-msg]
+
+repos:
+  # Keeps internal references (ticket ids, secret-store paths, internal hosts and process
+  # names) out of user-facing docs and commit messages. The patterns are generic on purpose:
+  # a list of specific internal names would itself disclose them.
+  # Scope rule: https://docs.cachekit.io/contributing/#what-belongs-in-these-docs
+  - repo: local
+    hooks:
+      - id: no-internal-references
+        name: No internal references in docs
+        language: pygrep
+        entry: '\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s_-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])'
+        files: ^((packages|crates)/[^/]+/)?README[^/]*$|^docs/
+        types: [text]
+        stages: [pre-commit]
+      - id: no-internal-references-commit-msg
+        name: No internal references in commit message
+        # Same patterns. git hands this hook the raw message file: "# " comment lines, the diff
+        # below the `git commit -v` scissors line, and its own merge and revert subjects, which
+        # quote branch names and earlier subjects. Only the text the author wrote is checked.
+        language: python
+        entry: python -c
+        args:
+          - |
+            import re, sys
+            P = re.compile(r"\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s_-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])")
+            KIND = r"(?:branch|branches|remote-tracking branch|remote-tracking branches|tag|tags|commit|commits)"
+            GIT_SUBJECT = re.compile(rf"Merge {KIND} '[^']*'(?:(?:, |; | and ){KIND}? ?'[^']*')*(?: of \S+)?(?: into \S+)?|(?:Revert|Reapply) \".*\"")
+            try:
+                with open(sys.argv[1], encoding="utf-8", errors="replace") as f:
+                    text = f.read()
+            except OSError as e:
+                sys.exit(f"{sys.argv[1]}: cannot read the commit message: {e}")
+            text = text.split("# ------------------------ >8 ------------------------")[0]
+            lines = [line for line in text.splitlines() if line.strip() and not re.match(r"#(?:[ \t]|$)", line)]
+            if lines and GIT_SUBJECT.fullmatch(lines[0]):
+                lines = lines[1:]
+            bad = [line for line in lines if P.search(line)]
+            for line in bad:
+                print(f"{sys.argv[1]}: {line}")
+            sys.exit(1 if bad else 0)
+        stages: [commit-msg]

README.md

@@ -385,7 +385,7 @@ ByteStorage envelope vectors from
 both sets must decode to the exact payload bytes, while re-encode
 byte-identity is asserted against the set matching this crate's current
 writer encoding — msgpack `bin`, since the protocol 1.1 `serde_bytes`
-writer flip (LAB-866; `checksum` deliberately stays array-of-ints per the
+writer flip (`checksum` deliberately stays array-of-ints per the
 protocol's normative scope exclusion). Legacy envelopes remain readable
 forever.
 `tests/dual_decode.rs` proves both reader shapes accept both encodings,
@@ -416,6 +416,13 @@ This crate requires **Rust 1.85** or later (Edition 2024).
 
 ---
 
+## Contributing
+
+User-facing docs in this repository follow CacheKit's shared rule on what belongs in them:
+[What belongs in these docs](https://docs.cachekit.io/contributing/#what-belongs-in-these-docs).
+`prek install` (or `pre-commit install`) sets up hooks that reject internal references in README
+files, `docs/` and commit messages.
+
 ## License
 
 MIT License — see [LICENSE](LICENSE) for details.