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

[27Bslash6]

What

Adds two local pre-commit hooks that reject common patterns of internal references: ticket ids, secret-store paths, internal hosts and plan labels.

• no-internal-references checks the top-level, packages/* and crates/* READMEs and docs/.
• no-internal-references-commit-msg checks the commit message. It reads only down to git's scissors line, so the diff git commit -v appends is ignored. It skips git's # comment lines plus Merge and Revert " subjects, which quote branch names and earlier subjects.

The patterns are generic on purpose: a list of specific names would itself disclose them. default_install_hook_types includes commit-msg, so a plain prek install (or pre-commit install) sets up both hooks.

• Removes one internal ticket reference from the README.
• New .pre-commit-config.yaml carrying only this hook.
• Adds a Contributing section to the README that links the scope rule.

Why

User-facing docs collect worklogs and internal references unless something stops them at commit time. The rule these hooks back is What belongs in these docs.

Verification

Seeded violations, after prek install, each using a ticket-shaped id (shown here as <id>). Neither commit landed, and the tree was clean afterwards:

--- seed: README.md gains <id>
No internal references in docs...........................................Failed
  README.md:437:Tracked in <id>.
--- seed: commit message carries <id>
No internal references in commit message.................................Failed
  COMMIT_EDITMSG:1:docs: seed (<id>)
--- control: an editor commit (git's "#" lines quote the branch name)
No internal references in commit message.................................Passed

prek run no-internal-references --all-files: Passed. A default merge commit, whose subject quotes the branch name, passes the commit-message hook.

Real commits after prek install: a git commit -v whose only id sits in the staged diff passes; a revert, through git revert --no-commit then git commit, of a commit whose subject carries an id passes; an id in the subject still fails. A 24-case message matrix covers those plus id-bearing revert bodies, ids above the scissors line, k3s phrasing variants and a 2.3 MB verbose diff.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: cachekit-io/cachekit-core/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 845b5952-107b-4bcb-808f-bb641fe60daf

📥 Commits

Reviewing files that changed from the base of the PR and between ae2738b and cebb2c5.

📒 Files selected for processing (2)

• .pre-commit-config.yaml
• README.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Summary by CodeRabbit

• Documentation
  • Updated the protocol-vector guidance to describe the protocol 1.1 writer-encoding change without an internal ticket reference.
  • Added contributor guidance explaining how to set up commit hooks and where to find shared documentation standards.
• Chores
  • Added checks for internal references in README and documentation text, as well as commit messages. The checks report matching lines and block commits when references are found.

Walkthrough

The changes add pre-commit hooks that check README and docs text, and commit messages, for configured internal references. The README updates protocol wording and describes the hooks.

Changes

Reference checks and README updates

Layer / File(s)	Summary
Internal-reference hook checks .pre-commit-config.yaml	Local hooks check README and docs files, and commit messages, for configured internal references. The commit-message hook excludes specified Git-generated or non-author-written content, reports matches, and exits unsuccessfully on matches or message-file read errors.
README protocol and contribution guidance README.md	The README replaces the LAB-866 reference with protocol 1.1 serde_bytes writer-flip wording. It adds contribution guidance that describes the hook installation commands and checks.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to cebb2

The documentation and local hook changes are mergeable after normal checks.

Architecture Summary

Architecture risk: 🔵 Low · up to cebb2

The change affects 1 system.

Changed systems: README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: The writer-encoding change is now identified as the protocol 1.1 serde_bytes writer flip; the previous LAB-866 reference was removed.
• observed — Modified behavior in README.md: Added a Contributing section linking to the shared guidance on documentation content and stating that either supported hook-install command sets up checks against internal references in README files, docs/ and commit messages.
• observed — Modified behavior in .pre-commit-config.yaml: Adds the default pre-commit and commit-msg hook types and a local text hook that checks README and docs files for the configured internal-reference patterns.
• observed — Modified behavior in .pre-commit-config.yaml: Adds a Python commit-message hook using the same patterns. It excludes comment lines and text after the scissors marker, skips a leading subject matching the configured Git merge or revert/reapply forms, reports remaining matches, and exits unsuccessfully if matches are found; failure to read the message also exits unsuccessfully.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarises the main change: preventing internal references in documentation and commit messages.
Description check	✅ Passed	The description explains the hooks, their scope, the README changes and the reported verification. It is directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

Kody Code Review — 1 suggested fix.
Paste the prompt below to your agent and all review fixed at once!

🛠️ Open Agent Prompt

A code review identified the following issues in this pull request.
Each section describes what was found and includes a reference implementation where available.

Files involved:
- .pre-commit-config.yaml:23

---

### [1/1] .pre-commit-config.yaml:23
Issue identified during code review:
False positive in the no-internal-references-commit-msg hook: the regex skips only lines starting with `#`, but git runs the commit-msg hook on the raw COMMIT_EDITMSG before stripping comments and everything below the scissors line, so the hook also scans the `git commit -v` / `commit.verbose` diff and auto-generated revert subjects. Committing this README change with `-v` puts `-writer flip (LAB-866; ...` in the diff, and `git revert` of any commit whose subject carries a ticket id (CHANGELOG shows LAB-866, LAB-683, LAB-1638, LAB-1645) produces `Revert "... (LAB-866)"`; the hook rejects both. Fix: truncate the message at `# ------------------------ >8 ------------------------` and run `git stripspace --strip-comments` before grepping (or use pygrep with `args: [--multiline]` and a pattern limited to text above the scissors line), and document `--no-verify` for reverts.
Reference implementation (from code review):

// .pre-commit-config.yaml:23
language: system
        entry: sh -c 'sed "/^# -\{24\} >8 -\{24\}$/,\$d" "$1" | git stripspace --strip-comments | grep -nE "LAB-[0-9]+|op://|\.ts\.net|\bk3s\b|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit([^[:alnum:]_-]|$)" && exit 1 || exit 0' --
        stages: [commit-msg]

---

Review each issue in context, use the reference implementations as guidance, and apply fixes that are consistent with the surrounding codebase.

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

[27Bslash6]

@kody start-review

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

[kodus-27b]

Code Review Completed! 🔥

The code review was successfully completed based on your current configurations.

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the `@kody start-review` command at the root of your PR.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Providing Context (Files & MCPs)

Add these hints in your PR description (or a comment) to unlock deeper checks:

• Ticket / Acceptance Criteria: `Refs: ABC-123` (Linear/Jira/Asana/ClickUp/Trello) or a direct ticket link.
• Bugfix Validation: a Sentry/Datadog/Bugsnag event link (or paste the stack trace/error message).
• Endpoint Risk: mention the route (e.g., `POST /api/payments`) or controller/action name.
• Attach a repo file as context: use an explicit marker like `@file:docs/guide.mdx#L10-L50` (replace with your real path).
• API Contract Docs: include `@file:openapi.yaml` or `@file:swagger.json` when changing routes/schemas.
• Definition of Done / Standards: include `@file:DOD.md` or `@file:CONTRIBUTING.md` if your repo has them.
• Design System Source of Truth: include `@file:ui/index.ts` (replace with your DS entrypoint path).
• Feature Flags: include the flag key/name and `@file:flags.ts` / `@file:config.json` (and optionally the PostHog flag name).
• Edge/CDN Rules: link the Cloudflare rule/zone or describe the intended redirect/header behavior.
• Attach an MCP tool output: use `@mcp<provider|tool>` (replace with an installed MCP provider + tool, e.g., `@mcp<sentry|events.search>`).

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.