Establish .config/ as the home for tool configuration, enforced by .repo/

[justinmerrell]

Why

The repo already declares the right philosophy in CONFIGURATION.md — "One need, one place" — and already proves it once (mise.toml redirected via MISE_GLOBAL_CONFIG_FILE, ten cache dirs funnelled into one tree). What was missing is the generalization: there was no declared home for tool configuration, so the first contributor to add a linter would drop a dotfile at the root and junk-drawer accretion would begin.

This is a template. Whatever it ships is replicated into every repo scaffolded from it, so the convention had to be settled before the configs exist — and backed by something stronger than memory.

What changed

development-container/
├── .config/        lefthook.yml  markdownlint.jsonc  yamllint.yaml
│                   actionlint.yaml  codespell.cfg  README.md
├── .devcontainer/  provisioning only — scope unchanged
├── .github/        workflows/  rulesets/
├── .repo/          the `repo` CLI + 4 policies
├── taskfiles/      lint.  repo.
├── .gitattributes  .gitignore
├── Taskfile.yml    CONFIGURATION.md  README.md

Four visible root entries. .config/ is dotted deliberately: it is repo infrastructure and sits alongside .devcontainer/, .github/, .repo/. What is visible at the root is content you edit; what is dotted is machinery that operates on it.

lefthook.yml moved into .config/ and is found there with no flag, env var, or wrapper — MainConfigNames in lefthook's internal/config/loader.go is ["lefthook", ".lefthook", ".config/lefthook"]. Taskfile.yml stays at the root because go-task's discovery list is only the eight Taskfile.* variants and --taskfile would break bare task <name>.

What is now enforced

repo check runs four policies — 20 violation classes. Because there is no prose rules layer, enforcement has to explain itself: every violation carries a stable code, the reason the rule exists, and the action that resolves it.

Policy	Codes	Enforces
config	CFG-01..07	Tool config lives in .config/, every file is indexed and has a caller, nothing at the root shadows it
ports	PORT-01..05	Port table ↔ forwardPorts/portsAttributes ↔ compose published ports agree, and stay in 15432–15460
hooks	HOOK-01..04	Every lefthook job has a CI counterpart and vice versa, or a recorded reason why not
rulesets	RS-01..04	Committed branch rulesets stay valid and in step with the CI jobs they require

Two of these guard failure modes worth calling out:

• CFG-06 — lefthook's config search is first-match-wins, so a stray root lefthook.yml would silently shadow .config/lefthook.yml: no warning, different hooks. Confirmed reproducible before writing the check.
• RS-03 — a required status check is matched by a CI job's display name, so renaming a job without updating the ruleset leaves every PR waiting forever on a check that can never report, and clearing it needs admin access at exactly the moment the repo has become unmergeable.

Lint gates (markdownlint, yamllint, actionlint, codespell) run pre-commit on staged files and again in CI. Tool versions have exactly one source: .devcontainer/mise.toml, which CI resolves through jdx/mise-action via MISE_GLOBAL_CONFIG_FILE.

Judgment calls worth reviewing

• codespell, not cspell — matches musher-dev/platform's config/spelling/codespell.cfg and its codespell policy module.
• Rulesets are a policy, not a separate workflow — platform uses a rulesets-validate workflow. Making it the fourth repo policy means no new workflow, no new CI job, and no new parity-allowlist entry, since the governance job already runs repo check.
• One CRLF workaround survived deliberately. .gitattributes governs only files Git checks out. .devcontainer/.env is gitignored and hand-edited, so a Windows editor can reintroduce CR at any time and docker run --env-file hard-rejects it. The redundant *.sh postCreateCommand pass is gone; strip_crlf() in initialize.sh stays, with a comment explaining the asymmetry.
• .repo/ has no src/. Its purpose is to stop Python importing a local tree instead of the installed package, which only happens when the package is in the working directory — and this one is under .repo/, which is never where anyone works. The import name governance does collide with a real (unrelated) PyPI package; the distribution name stays the unique repo-governance, and uv tool install isolates the venv, so this is theoretical. A one-line hatchling sources mapping decouples them if it ever matters.

Divergence from platform, accepted: platform uses visible config/<domain>/ buckets. Justin's call is to migrate platform to .config/ later. Platform's rule file also contains an error — it lists Lefthook among tools that "reject every config-path flag," which is false; the corrected reasoning is in this repo's CONFIGURATION.md and is worth a follow-up PR upstream.

Repo lint debt fixed along the way

The new gates had to pass on the repo's own files: 114 markdownlint findings → 0 (fence languages, table delimiter style, reflow to the 80/120 rulers), one over-long compose line (split inside a folded scalar — the parsed YAML document is byte-identical), and a codespell false positive fixed by renaming a badly-named shell variable rather than weakening the dictionary. codespell also caught a genuine typo in the new Python.

Verification

Run from the WSL host rather than inside the container, so real binaries were fetched instead of assumed: lefthook and markdownlint via npx, actionlint and Task via go install (Task 3.52.0 — the same version the Feature pins), yamllint and codespell from PyPI wheels, and the actual uv binary.

• task lint:all, repo check (directly, through Task, and from a subdirectory), shellcheck, lefthook validate — all pass
• 15 negative tests, one per triggerable violation class — each confirmed to fire and then clear
• Each lint gate confirmed to fail on a real defect, not just pass when clean
• lefthook validate --verbose prints loading config: .../.config/lefthook.yml; the pre-commit hook fired on every commit in this branch
• The wheel builds with exactly the 17 expected modules and no strays; uv tool install ./.repo succeeds and the installed repo executable runs clean

Not verified locally — no Docker daemon on this host: the mise pins actually resolving (pipx:/aqua: backends), jdx/mise-action in CI, and a full devcontainer rebuild. Those need this PR's CI run and a container rebuild.

Note for reviewers

The Repo Structure and Lint CI jobs are new, so .github/rulesets/main-branch.json lists them as required status checks. The ruleset is not applied automatically — it must be imported once from repository settings, per .github/rulesets/RULESETS.md.

🤖 Generated with Claude Code