chore: root-md cleanup + pre-commit allowlist guard - #210
Merged
Conversation
… .docs/ Root markdown is now limited to the allowlist (AGENTS.md, AGENTS.develop.md, CLAUDE.md, README.md, README_CSharp.md, CHANGELOG.md, RELEASING.md). Diagnosis write-ups, plans, test scenarios and worklogs move to the gitignored .docs/ folder (content preserved locally, untracked); the tracked docs/ folder is dissolved. Rule documented in AGENTS.md "Root file hygiene (markdown)" and AGENTS.develop.md "Key conventions for agents"; .gitignore lists .docs/ explicitly. CLAUDE.md already is the one-line pointer to AGENTS.md. Review-fixes: - [Important] AGENTS.md claims a pre-commit root-md guard that doesn't exist yet -> guard added in the next commit on this branch (stage 2) - [Minor] .gitignore comment said the .*/ rule is "below" when it is above -> corrected - [Minor][pre-existing] src/serve/tests.rs doc-comment pointed at docs/diagnose-federated-keep-warm.md (a path that never existed) -> now .docs/DIAGNOSE_FEDERATED_KEEP_WARM.md
Rejects any commit that introduces (adds/copies/renames) a root-level *.md outside the allowlist (AGENTS.md, AGENTS.develop.md, CLAUDE.md, README.md, README_CSharp.md, CHANGELOG.md, RELEASING.md); the message points at .docs/ and AGENTS.md "Root file hygiene (markdown)". Only introductions are checked (diff-filter=ACR); dot-folders are out of scope by construction. .githooks/ README.md documents the guard; CHANGELOG gets a new pending [1.3.1] section (Cargo.toml already builds 1.3.1). Verified by direct hook runs: stray root add blocked (rc=1), rename allowlisted->stray blocked (rc=1), allowlisted modify / nested add / .docs add all pass (rc=0). Review-fixes (from stage 1 review, resolved here): - [Important] AGENTS.md claimed a pre-commit root-md guard that did not exist -> guard now exists in .githooks/pre-commit with matching allowlist; .githooks/README.md table row updated Review-fixes (from stage 2 review round 1, resolved here): - [Important] non-ASCII root md names escaped the guard: core.quotePath (default true) C-quotes them, so the *.md case missed the quoted trailing quote char -> diff now runs with -c core.quotePath=false; verified DIAGNOSE_ü.md now blocked rc=1 [Debt, recorded not fixed] allowlist restated in 3 live sites (pre-commit, .githooks/README.md, AGENTS.develop.md) — documentation-inevitable duplication, stable at 7 files.
Replace the ${var,,} lowercase expansion (bash >= 4 only; fatal "bad
substitution" on stock macOS bash 3.2, which would block every commit
containing a root-level file) with tr 'A-Z' 'a-z'. Verified: EVIL.MD and
DIAGNOSE_ü.md still blocked rc=1, allowlisted modify rc=0, clean tree rc=0.
Review-fixes:
- [Important] guard used ${staged,,}, unsupported on macOS bash 3.2 -> tr-based lowering, behavior unchanged
- [Debt, corrected count] allowlist restated in 5 live sites (pre-commit, .githooks/README.md, AGENTS.md, AGENTS.develop.md, CHANGELOG.md), not 3 as previously recorded
…old [1.3.1] entry into pending [1.3.2] per changelog convention; keep serve-tests doc-comment fix on top of new tests) # Conflicts: # CHANGELOG.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What