Document mutation-testing workflow contract tests

[leynos]

Summary

Documents the mutation-testing caller workflow and its contract test in
docs/developers-guide.md, with a cross-link from docs/contents.md.

The caller passes the flat-layout inputs paths (create_labels/) and
module-prefix-strip (empty string). The contract test self-skips in mutmut's
sandbox, which omits .github/.

The current contract is shape-only: USES_RE verifies the expected reusable
workflow path and a full 40-character commit SHA, but deliberately does not
pin its value. Dependabot owns pin updates, so a bump does not require a
matching hand-edited test constant.

Run the contract test locally with:

uv run --with pytest --with pyyaml pytest tests/test_workflow_contract.py -q

Validation

• make check-fmt
• make lint
• make typecheck
• make test — 33 passed
• make markdownlint
• make nixie

References

• Lody session

[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]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Summary

• Documented mutation-testing workflow contract tests in the Developers’ guide.
• Added details on workflow inputs, pinned reusable workflow references, permissions, triggers, concurrency, sandbox guards, and local test execution.
• Cross-linked the new guidance from the documentation contents index.
• Verified with make markdownlint and mdformat-all.

Walkthrough

Changes

Mutation-testing workflow documentation

Layer / File(s)	Summary
Document workflow contract and guide index docs/developers-guide.md, docs/contents.md	Document the caller and reusable mutation-testing workflows, execution modes, pinned uses: reference, configuration inputs, permissions, concurrency, triggers, contract-test coverage, and local test command; update the Developers’ guide index description accordingly.

Possibly related issues

• leynos/simulacat#50 — Both changes expand docs/developers-guide.md with mutation-testing workflow documentation.

Possibly related PRs

• leynos/diesel-cte-ext#111 — Documents the same mutation-testing workflow contract and its validation rules.
• leynos/whitaker#297 — Covers the caller-to-reusable workflow flow, pinning, and contract-test invariants.
• leynos/agent-template-python#24 — Aligns mutation-testing workflow documentation with reusable workflow and contract-test assertions.

Poem

Mutation tests march by day,
Manual runs take the full array.
Pinned workflows hold the line,
Contract checks keep shapes in time,
Guides now point the clearer way.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	Docs-only change: only docs/contents.md and docs/developers-guide.md changed; the existing contract test already checks pinned uses, permissions, triggers, concurrency, and inputs.
User-Facing Documentation	✅ Passed	Document only maintainer-facing workflow; no user-facing behaviour changed, and docs/users-guide.md is untouched.
Developer Documentation	✅ Passed	docs/developers-guide.md documents the mutation-testing workflow contract tests, docs/contents.md cross-links it, and no roadmap/execplan or translated docs are present.
Module-Level Documentation	✅ Passed	Only docs/contents.md and docs/developers-guide.md changed; no code modules were touched, so the module docstring rule is not applicable.
Testing (Unit And Behavioural)	✅ Passed	Treat this as PASS: the commit only changes docs, so no new unit or behavioural test code is present to grade.
Testing (Property / Proof)	✅ Passed	PASS: This docs-only change describes an existing workflow contract; it introduces no new range invariant or proof assumption that would warrant property tests.
Testing (Compile-Time / Ui)	✅ Passed	Docs-only change; no compile-time or UI behaviour was introduced, so no trybuild or snapshot test requirement applies.
Unit Architecture	✅ Passed	PASS: Only documentation files changed; no runtime code, boundaries, dependencies, or side-effects were altered.
Domain Architecture	✅ Passed	Keep the change in docs only: it adds boundary guidance for workflow contracts and leaves domain code, adapters, and persistence untouched.
Observability	✅ Passed	Docs-only change; no operational behaviour changed, so extra observability is not required.
Security And Privacy	✅ Passed	PASS: The change is docs-only, adds no secrets or credentials, and the referenced workflow/test already enforce empty top-level permissions plus least-privilege job scopes.
Performance And Resource Use	✅ Passed	Only docs changed; no executable code, loops, I/O, allocation, or hot-path behaviour was altered.
Concurrency And State	✅ Passed	PASS: This is docs-only; the workflow already serialises per-ref concurrency, and the added contract test asserts that behaviour. No new shared mutable state.
Architectural Complexity And Maintainability	✅ Passed	Only docs changed; they document an existing explicit workflow/test contract without adding code, layers, indirection, or new dependencies.
Rust Compiler Lint Integrity	✅ Passed	PR only changes docs/contents.md and docs/developers-guide.md; no Rust files, lint suppressions, or clone-related code were added.
Title check	✅ Passed	The title clearly describes the documented mutation-testing workflow contract tests and aligns with the main changeset.
Description check	✅ Passed	The description accurately summarises the documentation changes, workflow details, contract test behaviour, and validation performed.

✨ 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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/developers-guide.md`:
- Around line 95-96: Update the module-prefix-strip documentation sentence to
remove the comma before the essential “because” clause, preserving the existing
wording and en-GB-oxendict style.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 508c8a02-39cc-4a03-8d70-1c35b78a6b88

📥 Commits

Reviewing files that changed from the base of the PR and between 72987a6 and 4b254fe.

📒 Files selected for processing (2)

• docs/contents.md
• docs/developers-guide.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• leynos/simulacat (auto-detected) → reviewed against open PR #51 docs/mutation-contract-tests instead of the default branch