What

• Adds yamllint (pinned v1.38.0) to .pre-commit-config.yaml with the key-duplicates rule and nothing else.
• Renamed in the hook list to check yaml for duplicate keys, so a failure says what it is.

Why

check-yaml cannot catch a duplicate mapping key:

• it runs with args: [--unsafe], which parses for syntax without constructing the document;
• and even without that flag it loads via yaml.safe_load, which resolves a duplicate to the last occurrence silently.

Docker Compose's loader rejects duplicates outright. So the two loaders disagree, and the strict one is the one that runs in CI.

That gap shipped a tests/compose/docker-compose.test.yaml carrying a second backend: key alongside the one at line 5. pre-commit passed it; the e2e tier then died at compose up in 0.4s, before a single container started:

line 93: mapping key "backend" already defined at line 5

The failure mode is nasty because the local signal is green and the file looks fine — the second key simply replaces the first, taking the service's image: pin and every other env var with it.

How

- repo: https://github.com/adrienverge/yamllint
  rev: v1.38.0
  hooks:
    - id: yamllint
      name: check yaml for duplicate keys
      args: ["-d", "{rules: {key-duplicates: enable}}"]

The rule is named inline rather than in a .yamllint.yaml, so the one rule in force is visible at the point of use and a future rev bump cannot widen the scope.

Every other yamllint rule is off, deliberately. The repo has no yamllint baseline and this hook is not an invitation to adopt one: extends: default reports 333 findings across the same files (270 of them line-length), which would get the hook disabled rather than the files fixed.

Can this PR break any existing features. If yes, please list possible items. If no, please explain why.

• No runtime code is touched — the change is confined to .pre-commit-config.yaml.
• The only risk is the hook failing on existing files. It does not: all 22 tracked YAML files report zero findings, so no exclusions and no per-file waivers are needed.
• It can newly block a commit, but only for a file that Docker Compose (and Kubernetes, and GitHub Actions) would reject anyway.
• types: [file, yaml] is upstream's own selector; no custom files: pattern to drift.

Database Migrations

• None

Env Config

• None

Relevant Docs

• yamllint key-duplicates
• check-yaml --unsafe

Related Issues or PRs

• Found while fixing CI on UN-4232 [FEAT] Agent-KV API serving the table extractor only #2317, which is where the duplicate key was introduced and reverted.

Dependencies Versions

• yamllint v1.38.0 (released 2026-01-13), new pre-commit hook repo. No application dependency is added — pre-commit builds it in its own isolated env.

Notes on Testing

• The test that matters: reintroduced the exact incident shape and confirmed the hook fails, naming file, line and key — while check-yaml passes on that same file. A guard that does not fail on the bug it targets is worthless.
• Confirmed .yml is covered as well as .yaml, by planting a duplicate in .github/ISSUE_TEMPLATE/config.yml. A hook that matches no files also reports "Passed", so this needed checking separately.
• pre-commit run yamllint --all-files passes on the current tree (22 files, 0 findings).
• pre-commit validate-config passes.
• Verified the hook runs as part of a real commit, alongside the existing check yaml.

To reproduce the catch yourself:

printf '\nservices:\n  backend:\n    image: x\n' >> tests/compose/docker-compose.test.yaml
pre-commit run yamllint --all-files   # fails
pre-commit run check-yaml --all-files # passes
git checkout tests/compose/docker-compose.test.yaml

Screenshots

N/A

Checklist

I have read and understood the Contribution Guidelines.

🤖 Generated with Claude Code