Apply TemplateDotNetTool updates: workflow comments, artifact naming, OTS self-validation, and OTS requirements

[Copilot]

Syncs BuildMark with recent TemplateDotNetTool template changes covering workflow structure, artifact naming conventions, OTS tool self-validation, and OTS software requirements traceability.

Workflow Comments & Section Dividers (build.yaml, release.yaml)

• Added job-level prose comments to all jobs describing their purpose
• Added # === SECTION === dividers within jobs for consistent readability

Artifact Naming (build.yaml, release.yaml)

Adopts the template's two-tier naming scheme:

Before	After
artifacts-${{ matrix.os }} (packages)	packages-${{ matrix.os }}
test-results-* + version-capture-*	artifacts-build-${{ matrix.os }}
codeql-sarif	artifacts-codeql
validation-test-results-*	artifacts-validation-*
version-capture-quality	artifacts-quality

All jobs now write outputs into an artifacts/ directory with explicit --output paths, enabling build-docs to consolidate three separate download steps into one:

- name: Download all job artifacts
  uses: actions/download-artifact@v8
  with:
    path: artifacts
    pattern: 'artifacts-*'
    merge-multiple: true
  continue-on-error: true

The build-docs job downloads packages from packages-ubuntu-latest (consistent with the template and release.yaml).

OTS Tool Self-Validation (build.yaml)

Added # === CAPTURE OTS SELF-VALIDATION RESULTS === sections to produce .trx evidence files consumed by ReqStream --enforce:

• quality-checks: VersionMark self-validation
• build: VersionMark self-validation
• build-docs: ReqStream, BuildMark, VersionMark, SarifMark, SonarMark self-validation

BuildMark self-validation in build-docs invokes buildmark directly (as a globally-installed tool) rather than via dotnet buildmark.

OTS Software Requirements (requirements.yaml)

Added OTS Software section with 6 requirements linked to self-validation test names:
BuildMark-OTS-MSTest, BuildMark-OTS-ReqStream, BuildMark-OTS-BuildMark, BuildMark-OTS-VersionMark, BuildMark-OTS-SarifMark, BuildMark-OTS-SonarMark

Additional Fixes

• reqstream --tests glob: test-results/**/*.trx → artifacts/**/*.trx
• sarifmark --sarif path: codeql-results/csharp.sarif → artifacts/csharp.sarif
• SonarMark step: added shell: bash, changed "$env:SONAR_TOKEN" → "$SONAR_TOKEN" for cross-platform portability
• Pandoc steps: --filter moved before --metadata for consistency with template
• ReqStream updated from 1.3.0 to 1.4.0 in .config/dotnet-tools.json to satisfy the BuildMark-OTS-ReqStream self-validation requirement
• build-docs packages download: packages-windows-latest → packages-ubuntu-latest for consistency with the template and release.yaml

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

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 tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.BuildMark --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 '**/*.{yml,yaml}'

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

All YAML files validated as syntactically correct. No code changes — CI/CD workflow and requirements traceability only.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Malcolmnixon]

This is the BuildMark project, and BuildMark is installed from package as a global tool - as such buildmark shouldn't be executed via 'dotnet'.

[Copilot]

Fixed in 5fa8e66 — changed dotnet buildmark to buildmark so it invokes the globally-installed tool directly.

[Malcolmnixon]

@copilot I believe you may need to update ReqStream to the latest release (1.4.0) to pass the OTS Software requirements for it.

[Copilot]

@copilot I believe you may need to update ReqStream to the latest release (1.4.0) to pass the OTS Software requirements for it.

Updated ReqStream to 1.4.0 in .config/dotnet-tools.json in c2b9ec6.

[Malcolmnixon]

@copilot Wait, how did you "forget" to update ReqStream - didn't you go through the template PRs and apply the appropriate changes? Did you forget anything else?

[Copilot]

@copilot Wait, how did you "forget" to update ReqStream - didn't you go through the template PRs and apply the appropriate changes? Did you forget anything else?

The ReqStream version bump was explicitly listed in TemplateDotNetTool PR #52's description and I should have included it in the initial commit — that was an oversight.

On reviewing everything more carefully against the template, I also found that build-docs was downloading packages-windows-latest instead of packages-ubuntu-latest (the template consistently uses the Ubuntu package for all downstream steps). Fixed in fe2cf2b.