Track coverage-milestones doc merge/removal

[BjornMelin]

Track merging or removing docs/development/testing/coverage-milestones.md per PR #648 review. Owner: @BjornMelin. Target date: 2026-03-31.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#567 - chore(phase-0): implement all safety and baseline improvements [merged]

---

🧪 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!

[coderabbitai]

Coding Plan

Approach

Resolve the tracking item from PR #648 review regarding whether to merge or remove docs/development/testing/coverage-milestones.md. Based on comprehensive analysis, the document should be kept separate from testing.md as it serves a distinct purpose and follows established project patterns.

Observations

The project maintains testing documentation in docs/development/testing/ with two files:

• testing.md (417 lines) serving as a comprehensive how-to reference for writing tests
• coverage-milestones.md (72 lines) serving as a temporal tracking document for coverage baselines and thresholds

Coverage is enforced through a two-layer system:

• Global thresholds in vitest.config.ts
• Critical-surface thresholds in scripts/check-coverage-critical.mjs

The documentation structure follows a modular pattern with focused documents averaging ~226 lines, and cross-references connect related content.

Assumptions

Assumption 1: Should coverage-milestones.md be merged into testing.md, removed entirely, or kept as a separate document?

Options Considered:

1. Merge into testing.md - Combine the coverage tracking content into the main testing guide
2. Remove entirely - Delete the file if it duplicates content or serves no purpose
3. Keep separate - Maintain as an independent document with its current purpose

Chosen Option: 3

Rationale: Keep separate. The files serve fundamentally different purposes (stable how-to guide vs. frequently-updated metrics tracking), have zero content overlap, follow the project's modular documentation pattern, and align with industry best practices of separating enforcement configuration from documentation. The existing cross-reference in testing.md line 12 provides adequate discoverability.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Decision Documentation and Closure

Document the decision to retain coverage-milestones.md as a separate file and ensure proper rationale is captured for future reference.

Task 1: Add Decision Rationale to Coverage Milestones Document

Add a brief section explaining why this document exists separately from the main testing guide, providing context for future maintainers.

• Add a new "Purpose" or "About this document" section near the top of docs/development/testing/coverage-milestones.md
• Include 2-3 sentences explaining the document's role as a temporal tracking document for coverage metrics
• Note that it complements testing.md (how-to guide) by tracking quantitative progress over time
• Reference that thresholds are enforced in code (vitest.config.ts and scripts/check-coverage-critical.mjs) while this document provides human-readable context and history

Task 2: Verify Cross-Reference Adequacy

Confirm that existing cross-references between testing documentation files are clear and bidirectional.

• Verify docs/development/testing/testing.md line 12 contains the link to coverage-milestones.md (already exists)
• Consider adding a reciprocal reference in coverage-milestones.md pointing back to testing.md for developers who land on this document first
• Ensure docs/development/README.md or relevant index files reference both documents appropriately

Task 3: Close Tracking Item

Mark this decision as resolved with documented rationale.

• Add a commit message that references the PR #648 review feedback and documents the decision
• Include summary rationale: document serves distinct purpose, no duplication exists, follows project patterns, aligns with best practices
• If PR #648 has an open comment thread, respond with the resolution decision and link to the updated documentation

🤖 Prompt for AI agents

This phase documents the decision to keep `coverage-milestones.md` separate from
`testing.md` and ensures proper cross-referencing for maintainability.

In `docs/development/testing/coverage-milestones.md`:
- Add a "Purpose" or "About this document" section near the top
- Explain that this document tracks coverage metrics over time as a temporal
tracking document
- Note it complements `testing.md` (how-to guide) by providing quantitative
progress tracking
- Reference that thresholds are enforced in `vitest.config.ts` and
`scripts/check-coverage-critical.mjs`
- Add a link back to `testing.md` for developers who land on this document first

Verify cross-references:
- Confirm `docs/development/testing/testing.md` line 12 has link to
coverage-milestones.md
- Check `docs/development/README.md` references both documents if applicable

Commit message:
- Reference PR `#648` review feedback
- Document decision rationale: distinct purpose, no duplication, follows project
patterns, aligns with best practices

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase documents the decision to keep `coverage-milestones.md` separate from
`testing.md` and ensures proper cross-referencing for maintainability.

In `docs/development/testing/coverage-milestones.md`:
- Add a "Purpose" or "About this document" section near the top
- Explain that this document tracks coverage metrics over time as a temporal
tracking document
- Note it complements `testing.md` (how-to guide) by providing quantitative
progress tracking
- Reference that thresholds are enforced in `vitest.config.ts` and
`scripts/check-coverage-critical.mjs`
- Add a link back to `testing.md` for developers who land on this document first

Verify cross-references:
- Confirm `docs/development/testing/testing.md` line 12 has link to
coverage-milestones.md
- Check `docs/development/README.md` references both documents if applicable

Commit message:
- Reference PR `#648` review feedback
- Document decision rationale: distinct purpose, no duplication, follows project
patterns, aligns with best practices

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!