Run workspace doctests as part of make test

[leynos]

Summary

Run Rust workspace doctests explicitly as part of Netsuke's canonical
make test gate.

make test currently invokes cargo test --all-targets --all-features.
Doctests are not included by that target selection, so Rustdoc examples can
drift or stop compiling without failing the local or Continuous Integration
(CI) test gate.

Reference implementation

Follow Weaver's two-command test target:

test: ## Run tests with warnings treated as errors
	RUSTFLAGS="$(RUST_FLAGS)" $(CARGO) $(TEST_CMD) $(TEST_FLAGS) $(BUILD_JOBS)
	RUSTFLAGS="$(RUST_FLAGS)" $(CARGO) test --doc --workspace --all-features

See Weaver's Makefile.

The separate doctest command is intentional: it keeps executable Rustdoc
examples covered regardless of whether the primary test runner is Cargo's
built-in harness or cargo-nextest.

Proposed work

• Add cargo test --doc --workspace --all-features to make test, preserving
  the repository's warnings-as-errors policy.
• Keep the doctest invocation separate from the normal unit, integration, and
  behavioural test command so issue Adopt cargo-nextest as the default test runner #463 can replace the latter with nextest
  without dropping Rustdoc coverage.
• Confirm all existing doctests pass; fix invalid examples rather than
  weakening them or broadly marking them ignore.
• Add or update a workflow contract test so removal of the doctest command is
  detected.
• Update AGENTS.md and docs/developers-guide.md to describe both phases of
  make test.
• Ensure CI continues to call the canonical Make target rather than maintaining
  a second, drifting doctest command in workflow YAML.

Relationship to #463

Issue #463 already recognizes that nextest does not execute doctests. This
issue extracts the doctest gate into an independently deliverable prerequisite:
it can land under the current Cargo test runner, after which #463 only needs to
replace the first command and retain the second unchanged.

Acceptance criteria

• make test runs the existing non-doctest suite and then
  cargo test --doc --workspace --all-features.
• Warnings are denied while compiling doctests.
• A broken compilable Rustdoc example makes make test and CI fail.
• Existing doctests pass without blanket ignore or no_run conversions.
• A workflow contract test protects the two-phase test target.
• Contributor documentation accurately describes both commands.
• The implementation remains compatible with the nextest migration in
  Adopt cargo-nextest as the default test runner #463.
• make check-fmt, make lint, make test, and make markdownlint pass.

References

• Weaver make test implementation
• Adopt cargo-nextest as the default test runner #463
• Makefile
• .github/workflows/ci.yml
• docs/developers-guide.md
• tests/workflow_contracts/

[coderabbitai]

🔗 Related PRs

leynos/theoremc#38 - Add core+macros crates; implement theorem_file proc-macro (3.2.1) [closed]
leynos/theoremc#44 - Run Rust tests with cargo-nextest [closed]
leynos/df12-build#57 - Preserve useful agent artefacts when schema parsing fails (#18) [merged]
#410 - Adopt the Whitaker Dylint suite in the lint gate and CI [merged]
#419 - Document mutation-testing workflow contract tests [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

Closing as completed on main. Makefile:80-87 now defines test: test-nextest doctest, with the doctest target running cargo test --workspace --doc --all-features under -D warnings — exactly the two-phase target this issue requested.