Document mutation-testing workflow contract tests

[leynos]

Summary

• Add a ## Mutation-testing workflow contract tests section to
  docs/developers-guide.md, placed immediately after the existing
  ### Workflow pins and Dependabot subsection (the general shape-only
  pinning policy this contract test follows). No mutation-testing-specific
  section already existed, so this is a new top-level section rather than a
  merge into one.
• Documents .github/workflows/mutation-testing.yml, the thin caller that
  delegates to leynos/shared-actions/.github/workflows/mutation-cargo.yml,
  and its contract test,
  tests/workflow_contracts/mutation_testing_test.py.

Findings reconciled against the repo

• Contract-test style: shape-only. The test asserts the uses: ref is
  the correct path pinned to a 40-character lowercase-hex commit SHA (no
  hard-coded PINNED_SHA constant), so Dependabot bumps freely with no
  test edit required. There is no pytestmark = skipif(...) guard — this
  is a Rust repo, so the test isn't run inside a mutmut sandbox that omits
  .github/.
• with: inputs actually present: only exclude-globs (the three
  #[cfg(kani)]-gated modules under src/ir/, which cargo-mutants
  cannot evaluate and would otherwise report as noisy survivors) and
  extra-args: --all-features (matching the make test CI baseline).
  paths is not set (uses the shared workflow's default).
• extra-crate-dirs is not set, and I deliberately did not document
  it as if it were. I re-read Cargo.toml's [workspace] block:
  ambient_fs is a genuine workspace member (members = ["ambient_fs"],
  default-members = [".", "ambient_fs"]), not a non-workspace companion
  crate — extra-crate-dirs is reserved (per
  shared-actions/docs/mutation-cargo-workflow.md) for crate directories
  outside the workspace, so it doesn't apply here. test_support is
  excluded from the workspace (exclude = ["test_support"]) and this
  workflow does not mutate it. This is a deviation from the "companion
  crate via extra-crate-dirs" framing I was initially briefed with; the
  section documents the repo's real configuration instead.
• Local command: make test-workflow-contracts (exists in the
  Makefile; runs
  uv run --with 'pytest>=8' --with 'pyyaml>=6' pytest tests/workflow_contracts -q).
  Ran it locally: 6 passed.
• Roadmap/execplan: no roadmap or execplan tracking applies. I checked
  docs/roadmap.md and docs/execplans/; the only "mutation" hits in the
  roadmap concern OrthoConfig's non-interactive/mutation-safety metadata
  and an unrelated --dry-run preview item, not this workflow.
• TOC cross-link: not applicable. docs/developers-guide.md has no
  table of contents or index list to link into; the guide is a flat
  sequence of ##/### sections.

Docs-lint result

make markdownlint (spelling/typos + markdownlint-cli2): passed after
fixing two spelling misses the linter caught in my first draft
(summarising → summarizing, serialises → serializes — this repo's
typos.toml enforces Oxford -ize spelling, consistent with
analyse/behaviour staying as-is elsewhere in the same paragraph). Final
run: 0 errors.

Per instructions, only the docs/markdown gates were run — not make test
or make lint.

File changed

• docs/developers-guide.md

Latest review validation

• make fmt: passed.
• make markdownlint: passed (34 checks, 0 Markdown errors).
• make nixie: passed (all Mermaid diagrams valid).

References

• https://lody.ai/leynos/sessions/98f58671-0ba4-410a-94b8-b4613bf6e990

[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

Walkthrough

Documentation updates clarify lint exceptions, reusable-workflow pinning guidance, mutation-testing workflow contracts, and BDD command-helper descriptions.

Changes

Developer workflow documentation

Layer / File(s)	Summary
Workflow contract guidance docs/developers-guide.md	Document Dependabot lockstep behaviour and describe mutation-testing workflow modes, inputs, pinning, permissions, concurrency, triggers, and contract-test assertions.
Contributor guidance clarifications docs/developers-guide.md	Clarify filesystem-lint exclusions and introduce the three BDD helpers for controlled netsuke execution.

Possibly related PRs

• leynos/agent-template-rust#52: Implements the mutation-testing workflow and its contract assertions.
• leynos/agent-template-python#24: Covers related mutation-testing workflow and reusable-workflow pin contracts.
• leynos/cuprum#204: Updates contract tests to validate SHA format rather than a fixed SHA.

Suggested reviewers: codescene-access

Poem

Pins hold fast, but not one sacred hash,
Mutation tests wake with the daily flash.
Lints guard paths where filesystem calls roam,
Three BDD helpers guide netsuke home.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
Testing (Unit And Behavioural)	❓ Inconclusive	Pending evidence from the changed workflow and contract-test files.	Inspect the diff and test files to verify whether the added tests exercise real workflow behaviour or only internal shape.
Security And Privacy	❓ Inconclusive	placeholder2	inspect2

✅ Passed checks (18 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	Pass: treat this as not applicable; the PR only changes docs/developers-guide.md and introduces no new behaviour to guard.
User-Facing Documentation	✅ Passed	Treat this PR as non-user-facing: it only updates docs/developers-guide.md, so docs/users-guide.md is not required.
Developer Documentation	✅ Passed	docs/developers-guide.md adds the mutation-testing section; no matching roadmap item or execplan needed updating, and no translated developer-guide copy exists.
Module-Level Documentation	✅ Passed	PASS: The PR changes only docs/developers-guide.md; no Rust/Python modules were added or edited, so the module docstring rule is unaffected.
Testing (Property / Proof)	✅ Passed	The change only documents a fixed workflow contract and exact config checks; it introduces no ranged invariant or proof obligation that would call for property testing or formal proof.
Testing (Compile-Time / Ui)	✅ Passed	PASS: the PR only updates docs plus a Python/YAML workflow contract; no Rust/TS compile-time or UI-output behaviour is added, so trybuild/snapshot tests are not applicable.
Unit Architecture	✅ Passed	Pass: the PR only edits docs/developers-guide.md; no code, workflows, or tests were changed, so the architecture separation check is not applicable.
Domain Architecture	✅ Passed	PASS: The PR only changes docs/developers-guide.md; no domain, adapter, persistence, or transport code was touched.
Observability	✅ Passed	Only docs/developers-guide.md changed in the PR range, so no production behaviour changed and no new observability was required.
Performance And Resource Use	✅ Passed	Only docs/developers-guide.md changed; no runtime code, loops, I/O, allocations, or hot-path logic were introduced.
Concurrency And State	✅ Passed	Approve: only docs changed; the workflow and contract test already pin per-ref concurrency and no shared mutable state is introduced.
Architectural Complexity And Maintainability	✅ Passed	Docs-only change; add no new abstraction, dependency, layer, or coupling, so architectural complexity stays flat.
Rust Compiler Lint Integrity	✅ Passed	Only docs/developers-guide.md changed; no Rust files, lint suppressions, or extra clones were added, so compiler lint integrity is unaffected.
Title check	✅ Passed	Keep the title aligned with the new mutation-testing workflow contract-test documentation.
Description check	✅ Passed	Keep the description aligned with the added mutation-testing workflow contract-test documentation.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 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: 2

🤖 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 96-97: Update the filesystem-scope statement in the developers
guide to acknowledge every sanctioned exclusion configured in dylint.toml,
including build_script_build, integration-test crates, and the relevant
application crates, rather than implying access is limited to ambient_fs and
test_support.
- Line 147: Expand the “Mutation-testing workflow contract tests” section to
document running make fmt, make markdownlint, make nixie, make check-fmt, make
lint, and make test before merging, and instruct contributors to record each
command’s output.

🪄 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: 0cc0834a-1150-41f9-9b5d-7dfa161ed58e

📥 Commits

Reviewing files that changed from the base of the PR and between bd17072 and 37139a3.

📒 Files selected for processing (1)

• docs/developers-guide.md

🔗 Linked repositories identified

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

• leynos/rstest-bdd (auto-detected) → reviewed against open PR #598 docs/mutation-contract-tests instead of the default branch
• leynos/ortho-config (auto-detected) → reviewed against open PR #392 docs/mutation-contract-tests instead of the default branch
• leynos/shared-actions (auto-detected) → reviewed against open PR #362 docs/mutation-contract-tests instead of the default branch

[buzzybee-df12]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codescene-access]

No quality gates enabled for this code.