Document mutation-testing workflow contract tests

[leynos]

Summary

• Add a "Mutation-testing workflow contract tests" section to
  docs/developers-guide.md, describing the mutmut caller workflow
  (.github/workflows/mutation-testing.yml → shared-actions'
  mutation-mutmut.yml), its two configuration inputs (paths,
  module-prefix-strip), and its shape-only SHA pin.
• Add a ### Workflow contract tests subsection covering
  tests/test_workflow_contract.py: what it asserts (uses reference,
  with: block, permissions, concurrency, triggers) and how to run it
  locally.

Notes for reviewers

• Permutation used: C (Python/mutmut), per the standing template. Rust is
  deliberately not enrolled in this workflow (no repository-root
  Cargo.toml), and this doc change does not touch that.
• Contract-test style: shape-only. USES_RE in
  tests/test_workflow_contract.py matches
  mutation-mutmut.yml@[0-9a-f]{40} without asserting a specific SHA, so
  Dependabot bumps require no test edit.
• Deviation from the standard template: the test module has no
  skipif guard. .github/ is listed in [tool.mutmut].also_copy in
  pyproject.toml, so the workflow file is copied into mutmut's sandbox and
  the contract test runs there rather than self-skipping. The section
  documents this explicitly instead of describing a guard that does not
  exist.
• Local command documented:
  uv run --with pytest --with pyyaml pytest tests/test_workflow_contract.py -q
  (verified: 6 passed). There is no dedicated Makefile target, and the test
  also falls outside PYTEST_TARGETS (the glob list make test uses), so
  this is the command a maintainer actually needs.
• TOC/cross-link: docs/developers-guide.md has no per-section table of
  contents (only a flat ADR list at the top), so no TOC entry was added.
  docs/contents.md indexes whole documents, not sections, and its existing
  entry for the developers' guide already covers this addition — no change
  needed there.
• Roadmap/execplan: docs/roadmap.md has no mutation-testing or
  contract-test task; no roadmap/execplan tracking applies to this change.
• Docs lint: markdownlint-cli2 docs/developers-guide.md — 0 errors.
  typos --config typos.toml docs/developers-guide.md — 0 errors (two
  words were corrected from -ise to -ize spellings to match the
  project's en-GB Oxford spelling convention enforced by typos.toml).

Edited file: docs/developers-guide.md

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 29170c58-4c6e-4bd4-88f1-34a46c6d4f29

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/mutation-contract-tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[codescene-access]

No quality gates enabled for this code.