ADR-0021 — Filename and directory casing #

• Status: Accepted
• Date: 2026-05-08
• Deciders: Natan
• Source: Recurring drift between contributors. See the global

~/.claude/CLAUDE.md standard ("kebab-case filenames everywhere") and the audit prompt that ratified this ADR.

Context #

The repository accumulated three casing conventions in parallel:

1. kebab-case lowercase — the dominant convention, used by

every directory in src/ and most of docs/ (adr/, concepts/, guides/, prds/).

1. SHOUTY filenames for emphasis — docs/RUNBOOKS/,

docs/HARDENING-RUN.md, docs/PROBLEM.md.

1. Leading-underscore sort hacks — docs/prds/_TRACKER.md,

intended to sort to the top of the directory.

This is the kind of drift that compounds: every new contributor (human or LLM) reads the tree, finds three conventions, and picks whichever feels right for their file. Within a year the repo is unreadable.

The conventional project-root files (README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE, Makefile) are not part of this problem — they are external conventions that every tool, IDE, GitHub renderer, and contributor already recognises. Renaming them would create breakage without value.

Decision #

All paths inside docs/ and src/ use kebab-case lowercase.

The only exceptions are:

1. Project-root conventional files: README.md, CHANGELOG.md,

CONTRIBUTING.md, LICENSE, Makefile, package.json, etc. These follow their own external conventions.

1. README.md at the head of a subdirectory (e.g.

docs/adr/README.md). README is a universally-understood "read this first" affordance; lowercasing it would be hostile to readers and to GitHub's directory-listing UI.

Sort order is never encoded in casing or special characters (no leading _, no SHOUTY). When sort order matters, use the existing zero-padded numeric prefix convention already used by ADRs and PRDs (00-tracker.md, 01-foo.md).

Consequences #

Renames performed alongside this ADR #

• docs/RUNBOOKS/ → docs/runbooks/
• docs/HARDENING-RUN.md → docs/hardening-run.md
• docs/PROBLEM.md → docs/problem.md
• docs/prds/_TRACKER.md → docs/prds/00-tracker.md

All cross-references in markdown and code were updated in lockstep. git mv was used so blame history follows the file.

Going forward #

• New files and directories follow the rule above. Reviewers

reject deviations and cite this ADR.

• A future PRD may add a mechanical check to

scripts/checks/standards.ts that flags any non-kebab-case path under docs/ or src/ (excepting README.md). For now the rule is doc-only — the renames in this commit reset the baseline; future drift is rare enough that PR review is sufficient.

What this ADR explicitly does NOT do #

• Rename anything outside docs/ and src/.
• Touch tool-recognised filenames (Makefile, Dockerfile, etc.).
• Mandate kebab-case for symbols inside files (variables,

types) — that is governed by Biome and TypeScript norms.