Pre-release cleanup: template alignment, guide accuracy and structure fixes

[Copilot]

Pull Request

Description

Ran all six specialized agents (repo-consistency, code-quality, requirements, technical-writer, software-developer, test-developer) and performed a deep comparison against the last 20 merged PRs (#16–#37) from the TemplateDotNetTool template repository. Actionable findings were fixed:

• .editorconfig: Added end_of_line = lf to [*] section — aligns with TemplateDotNetTool template
• .markdownlint-cli2.jsonc: Added "MD025": false — aligns with template
• docs/guide/guide.md: Fixed output format documentation that diverged from actual behavior:
  • JSON example used kebab-case field names (job-id, versions) and a non-existent timestamp field — corrected to PascalCase (JobId, Versions) matching System.Text.Json serialization of the VersionInfo record
  • Markdown example showed (All jobs) suffix for uniform versions — code emits version only, no suffix
  • Markdown example showed <sub> tags with multiple versions on one line — code emits separate bullets per version group with parenthesized job IDs
• docs/guide/guide.md: Restructured heading hierarchy for Pandoc PDF compilation:
  • Removed redundant # VersionMark User Guide title heading (title.txt provides it for PDF)
  • Added # Introduction section with ## Purpose and ## Scope subsections, following the same pattern as other compiled documents in the project (requirements, quality, etc.)
  • Promoted all sections to root-level H1 headings so the document has proper structure for numbered sections and auto-generated Table of Contents
• requirements.yaml: Added test source filter documentation block explaining source filter prefix syntax (windows@, ubuntu@, net8.0@, dotnet8.x@, etc.) — synced from template PR #35
• AGENTS.md: Added "Test Source Filters" section documenting all filter prefixes and their meaning
• .github/agents/requirements-agent.md: Added "Test Source Filters" section with warning to never remove these filters
• .github/agents/test-developer.md: Added "Test Source Filters" section and "MSTest V4 Best Practices" section — synced from template PRs #35 and #32
• .github/agents/repo-consistency-agent.md: Added "Tracking Template Evolution" section — a systematic 4-step workflow for reviewing recent template PRs and propagating improvements to downstream repos (synced from template PR #37)
• .gitignore: Added generated documentation entries for requirements, justifications, tracematrix, quality, and buildnotes (synced from template PR #32)
• .github/pull_request_template.md: Fixed yamllint command from yamllint '**/*.{yml,yaml}' to yamllint . (synced from template PR #27)

All other agents reported the codebase as release-ready with no required changes (101/101 tests passing, 0 build warnings, 37/42 requirements satisfied locally with remaining 5 requiring CI platform matrix by design).

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.VersionMark --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint .

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

No code changes — only configuration and documentation. Testing/test checkboxes are N/A for this PR.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Malcolmnixon]

@copilot An additional release-cleanup task is to update the heading-structure of the user guide. The guide has all its headings under one Title-like root heading. This isn't needed for documents compiled to PDF as the title is populated from title.txt. Additionally Pandoc automatically creates a Table of Contents so the guide doesn't need its own navigation table in Markdown, and should start with an Introduction section containing a Purpose and Scope, and then the critical sections of the document should also be root-level markdown sections.

[Copilot]

@copilot An additional release-cleanup task is to update the heading-structure of the user guide. The guide has all its headings under one Title-like root heading. This isn't needed for documents comp...

Restructured the guide in 7d73b80. Removed the redundant # VersionMark User Guide title (title.txt provides it for PDF), added an # Introduction section with ## Purpose and ## Scope subsections following the same pattern as the other compiled documents (requirements, quality, etc.), and promoted all sections to root-level H1 headings. Markdown lint and spell check both pass clean.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Malcolmnixon]

@copilot I believe you forgot to review and update the requirements.yaml file - specifically the enhanced instructions about test sources - and that probably means you forgot to review and update the corresponding agent changes (both the AGENTS.md and the special agent configuration markdown files).

You seem to have missed synchronizing important content with the template. Please run the repo-consistency agent again and instruct it to look deeply - possibly even looking back at the last week of PR changes and making sure their content is appropriately applied to this repo.

[Copilot]

@copilot I believe you forgot to review and update the requirements.yaml file - specifically the enhanced instructions about test sources - and that probably means you forgot to review and update the ...

Synced in 87bde24. I compared against the template's recent PRs (#35 "Document test source filter syntax" and #32 "Port improvements from TemplateDotNetLibrary") and added the missing content:

• requirements.yaml: Added the source filter prefix documentation block (windows@, ubuntu@, net8.0@, dotnet8.x@, etc.)
• AGENTS.md: Added the "Test Source Filters" section
• .github/agents/requirements-agent.md: Added the "Test Source Filters" section
• .github/agents/test-developer.md: Added the "Test Source Filters" and "MSTest V4 Best Practices" sections

All markdown lint and spell checks pass.

[Malcolmnixon]

@copilot Please re-run the repo-consistency agent and have it review the last 10-20 PRs from https://github.com/demaconsulting/TemplateDotNetTool merging in improvements.

[Copilot]

@copilot Please re-run the repo-consistency agent and have it review the last 10-20 PRs from https://github.com/demaconsulting/TemplateDotNetTool merging in improvements.

Completed a deep comparison against the last 20 merged template PRs (#16–#37) in ec6fc6a. Found and applied 3 additional missing items:

• .github/agents/repo-consistency-agent.md: Added "Tracking Template Evolution" section (template PR #37)
• .gitignore: Added generated documentation entries for requirements, justifications, tracematrix, quality, and buildnotes (template PR #32)
• .github/pull_request_template.md: Fixed yamllint command from yamllint '**/*.{yml,yaml}' to yamllint . (template PR #27)

The remaining template PRs were either already applied, workflow-specific (not applicable), or dependency bumps. All linting passes clean.