docs: add TDD commit flow and review expectations for contributors

.github/CONTRIBUTING.md

@@ -30,14 +30,18 @@ Please consider these guidelines when filing a pull request:
 - Follow the [Coding Rules](#coding-rules)
 - Follow the [Commit Rules](#commit-rules)
 - Make sure you rebased the current master branch when filing the pull request
-- Squash your commits when filing the pull request
+- Keep a clear commit history: squash incidental/WIP commits, but for features and bug fixes follow [Test-driven development](#test-driven-development) — a failing-test commit, then the implementation
 - Provide a short title with a maximum of 100 characters
 - Provide a more detailed description containing
   _ What you want to achieve
   _ What you changed
   _ What you added
   _ What you removed
 
+### Working with maintainers
+
+A pull request is driven by its author. When you receive review feedback — whether from a maintainer or an automated reviewer — please either address it or reply explaining why you'd skip it, so the PR can keep moving. If anything is unclear, just ask; we're happy to help.
+
 ### Coding Rules
 
 To keep the code base of commitlint neat and tidy the following rules apply to every change
@@ -97,6 +101,25 @@ pnpm build
 pnpm test
 ```
 
+### Test-driven development
+
+For features and bug fixes we follow [test-driven development](https://martinfowler.com/bliki/TestDrivenDevelopment.html) ("red, green, refactor"): write a test that fails because the behavior doesn't exist yet, then write the code that makes it pass.
+
+Please mirror this in your pull request with two commits:
+
+1. **Tests first** — add tests for the new behavior. On their own they must fail (CI red), which proves they actually exercise the change.
+2. **Implementation** — add the code that makes them pass (CI green).
+
+Make sure the test commit fails for the _right reason_ — a failing assertion, not a build error — and that each test would pass only _with_ your change. A test that passes without the implementation isn't testing it.
+
+```sh
+# commit 1 — failing tests (CI red)
+git commit -m "test: cover <behavior>"
+
+# commit 2 — implementation (CI green)
+git commit -m "feat(<scope>): <behavior>"
+```
+
 ### Documentation updates
 
 Documentation uses `vitepress`.

.github/PULL_REQUEST_TEMPLATE.md

@@ -41,5 +41,7 @@ echo "your commit message here" | commitlint # fails/passes
 
 - [ ] My change requires a change to the documentation.
 - [ ] I have updated the documentation accordingly.
+- [ ] I have verified that any documentation examples I added/changed actually work.
 - [ ] I have added tests to cover my changes.
 - [ ] All new and existing tests passed.
+- [ ] For a feature/bug fix, my commits follow the [test-driven flow](https://github.com/conventional-changelog/commitlint/blob/master/.github/CONTRIBUTING.md#test-driven-development): a failing-test commit, then the implementation.