Add OTS Software Requirements section to requirements.yaml

[Copilot]

Pull Request

Description

Adds traceability for the off-the-shelf tools used in the project's build and documentation pipeline. Each tool gets an ots-tagged requirement linked to self-validation test results as evidence, ensuring the trace matrix demonstrates OTS software was validated at time of use.

Five OTS requirements added:

ID	Tool	Feature	Self-Validation Tests
Template-OTS-MSTest	MSTest.TestFramework + MSTest.TestAdapter	Test discovery and execution	All 9 unit test methods
Template-OTS-ReqStream	DemaConsulting.ReqStream 1.4.0	Requirements/trace matrix generation with --enforce	ReqStream_EnforcementMode
Template-OTS-BuildMark	DemaConsulting.BuildMark 0.4.0	Build notes from GitHub Actions metadata	BuildMark_MarkdownReportGeneration
Template-OTS-VersionMark	DemaConsulting.VersionMark 1.0.0	Tool version publishing	VersionMark_CapturesVersions, VersionMark_GeneratesMarkdownReport
Template-OTS-SarifMark	DemaConsulting.SarifMark 1.2.0	CodeQL SARIF → markdown	SarifMark_SarifReading, SarifMark_MarkdownReportGeneration
Template-OTS-SonarMark	DemaConsulting.SonarMark 1.2.0	SonarCloud quality report	SonarMark_QualityGateRetrieval, SonarMark_IssuesRetrieval, SonarMark_HotSpotsRetrieval, SonarMark_MarkdownReportGeneration

Requirements not included:

• coverlet.collector — evidence chain is too weak to reliably prove it works
• DemaConsulting.PandocTool and DemaConsulting.WeasyPrintTool — no self-validation results available to prove they work

Also includes:

• Updated DemaConsulting.ReqStream to 1.4.0 in .config/dotnet-tools.json to enable the ReqStream_EnforcementMode self-validation test.
• All four CI jobs (quality-checks, build, codeql, build-docs) share a standardized artifacts/ folder convention and follow a consistent four-section structure with section comments:
  1. # === INSTALL DEPENDENCIES === — install/restore tools and dependencies
  2. # === CAPTURE TOOL VERSIONS === / # === CAPTURE OTS SELF-VALIDATION RESULTS === — capture version and validation evidence before use
  3. job-specific work section (e.g. # === RUN QUALITY CHECKS ===, # === BUILD AND TEST ===, # === BUILD AND ANALYZE ===, # === GENERATE DOCUMENTATION ===)
  4. # === UPLOAD ARTIFACTS === — archive results at the end
• The quality-checks job creates the artifacts/ folder as its first capture step, captures VersionMark tool versions to artifacts/versionmark-quality.json, runs VersionMark self-validation to artifacts/versionmark-self-validation-quality.trx, then runs quality checks, and uploads the artifacts/ folder as artifacts-quality at the end.
• The build job creates the artifacts/ folder and runs the capture sections right after restoring tools (before running tests). dotnet test results are written directly to artifacts/ via --results-directory artifacts, VersionMark versions are captured to artifacts/versionmark-${JOB_ID}.json via --output, and VersionMark self-validation writes to artifacts/versionmark-self-validation-${{ matrix.os }}.trx. All are uploaded as artifacts-build-${{ matrix.os }} at the end. NuGet packages are uploaded separately as packages-${{ matrix.os }}.
• The codeql job outputs the SARIF analysis results directly to artifacts/ and uploads them as artifacts-codeql at the end.
• The build-docs job downloads all artifacts-* artifacts (including artifacts-codeql) into a single flat artifacts/ folder via the "Download all job artifacts" step (using merge-multiple: true), captures its own tool versions to artifacts/versionmark-build-docs.json, runs all five OTS tool self-validations (ReqStream, BuildMark, VersionMark, SarifMark, SonarMark) writing TRX files to artifacts/, and reqstream --enforce searches artifacts/**/*.trx for all evidence. versionmark --publish reads from artifacts/**/versionmark-*.json. sarifmark reads the SARIF file from artifacts/csharp.sarif.
• Updated release.yaml to download packages-ubuntu-latest (renamed from artifacts-ubuntu-latest).

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 unit tests pass: dotnet test --configuration Release
• 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

Changes span requirements.yaml (OTS requirements), .config/dotnet-tools.json (ReqStream version bump to 1.4.0), .github/workflows/build.yaml (standardized artifacts/ folder convention and four-section job structure with section comments across all four jobs, OTS self-validation execution in quality-checks, build, and build-docs, CodeQL SARIF routed through artifacts-codeql, merge-multiple: true on the artifact download step so all artifacts land flat in artifacts/, tool version capture and OTS self-validation at the top of each job right after restoring tools, artifact uploads moved to the end of each job, and consolidated artifact structure with no intermediate assembly steps), and .github/workflows/release.yaml (updated artifact name). Every job writes all outputs directly to a local artifacts/ folder without any copy steps, keeping the pipeline clean and consistent. yamllint validates cleanly against all updated files.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Add OTS Software Requirements</issue_title>
<issue_description>### Problem Statement

OTS Software Requirements should be tracked in a new section of the requirements document.

Proposed Solution

The solution involves:

1. Examine the DemaConsulting tools used by the project and the features used
2. Examine the projects to determine which self-validation results prove which features are functional
3. Add an OTS Software Requirements section to the requirements.yaml file
4. Add OTS Software Requirements (tagged as ots) for each piece of functionality used
5. Link the OTS Software Requirements to the self-validation test results

Alternatives Considered

No response

Usage Examples

Benefits

Trace matrix demonstrates OTS software was validated at time of use.

Priority

Low - Nice to have

Willingness to Contribute

Yes, I can submit a pull request

Additional Context

No response

Checklist

• I have searched existing issues to ensure this is not a duplicate
• I have provided a clear description of the feature
• I have explained why this feature would be useful</issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: Repo Consistency Agent
Ensures downstream repositories remain consistent with the TemplateDotNetLibrary template patterns and best practices

• Fixes [Feature]: Add OTS Software Requirements #27

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Malcolmnixon]

@copilot Please fix all the comments

[Malcolmnixon]

@copilot Please try fixing the comments again

[Copilot]

@copilot Please try fixing the comments again

Done in 557d5d9. All review comments addressed:

• Removed Template-OTS-Coverlet and the Pandoc/WeasyPrint requirements
• Fixed capitalization to DemaConsulting.ReqStream/BuildMark/VersionMark/SarifMark/SonarMark throughout
• Updated ReqStream to 1.4.0 in .config/dotnet-tools.json and linked to ReqStream_EnforcementMode
• Changed BuildMark link to BuildMark_MarkdownReportGeneration
• Updated VersionMark title to "publish captured tool-version information" and linked to VersionMark_CapturesVersions + VersionMark_GeneratesMarkdownReport
• Linked SarifMark to SarifMark_SarifReading + SarifMark_MarkdownReportGeneration
• Linked SonarMark to SonarMark_QualityGateRetrieval, SonarMark_IssuesRetrieval, SonarMark_HotSpotsRetrieval, and SonarMark_MarkdownReportGeneration

[Malcolmnixon]

@copilot I'm not actually seeing anything that runs the self-validation of the OTS Software tools and save the TRX results so the requirements would be satisfied - you may want to add the self-validation execution immediately after capturing the versionmark information - possibly even with a nice comment (like the build-docs comments) describing that it's capturing the version information and self-validation data.

[Copilot]

@copilot I'm not actually seeing anything that runs the self-validation of the OTS Software tools and save the TRX results so the requirements would be satisfied - you may want to ad...

Added in 4c9d2a3. A new "CAPTURE OTS SELF-VALIDATION RESULTS" section is inserted in the build-docs job immediately after the tool-version capture step and before the markdown report generation. Each OTS tool is run with --validate --results test-results/ots/<tool>-self-validation.trx, placing the TRX files in test-results/ots/ where they're picked up by the existing reqstream glob test-results/**/*.trx.

[Malcolmnixon]

hmm... I think this needs the job-name and matrix.os in the file name, otherwise the trx results from all jobs will just overwrite - there should be multiple "versionmark-self-validation.trx" files side-by-side so they all contribute to validation-evidence.

[Copilot]

Fixed in fb9bdff — the filename is now versionmark-self-validation-${{ matrix.os }}.trx, producing distinct files (versionmark-self-validation-windows-latest.trx and versionmark-self-validation-ubuntu-latest.trx) that both contribute as validation evidence without overwriting each other.

[Malcolmnixon]

@copilot The build.yaml is creating a few too many different artifacts. I think it'd be cleaner to combine the build-job test-results (both unit and validation) and the verison-capture files into a single artifact. I think what we may want is:

• rename "artifacts-[matrix.os]" to "packages-[matrix.os]" as it only contains the generated packages
• create "artifacts-build-[matrix.os]" containing the flat test results and version captures (and anything else) - may require assembling them in a flat artifacts folder first.

That would require updating the release.yaml to download the correct artifacts.

[Copilot]

@copilot I think you don't need the move step:

• When running dotnet test just output the test results directly to the "build-artifacts" folder
  ...

Done in 46e8849 — the "Assemble build artifacts" step is removed:

• dotnet test now uses --results-directory build-artifacts to write TRX and coverage files directly there
• versionmark --capture now uses --output "build-artifacts/versionmark-${JOB_ID}.json" to write the JSON directly to build-artifacts/ (also added mkdir -p build-artifacts before the capture since test runs before it now creates the folder, but the mkdir ensures it exists regardless of order)
• versionmark --validate TRX goes directly to build-artifacts/versionmark-self-validation-${{ matrix.os }}.trx