Pre-release repo check: documentation, consistency, and requirements traceability fixes

.github/agents/requirements-agent.md

@@ -36,6 +36,20 @@ Invoke the requirements-agent for:
   - Implementation validation beyond requirement scope
 - **Unit tests**: For library functionality and internal component behavior
 
+### Test Source Filters
+
+Test links can include a source filter prefix to restrict which test results count as evidence. This is essential
+for platform and framework requirements - **never remove these filters**.
+
+- `windows@TestName` - proves the test passed on a Windows platform
+- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform
+- `net8.0@TestName` - proves the test passed under the .NET 8 runtime
+- `net9.0@TestName` - proves the test passed under the .NET 9 runtime
+- `net10.0@TestName` - proves the test passed under the .NET 10 runtime
+
+Without the source filter, any matching test result satisfies the requirement regardless of which platform or
+framework produced it. Removing a filter invalidates the evidence for platform/framework requirements.
+
 ### Requirements Format
 
 Follow the `requirements.yaml` structure:

.github/agents/test-developer.md

@@ -63,12 +63,61 @@ public void ClassName_MethodUnderTest_Scenario_ExpectedBehavior()
   - Failure-testing and error handling scenarios
   - Verifying internal behavior beyond requirement scope
 
+### Test Source Filters
+
+Test links in `requirements.yaml` can include a source filter prefix to restrict which test results count as
+evidence. These filters are critical for platform and framework requirements - **do not remove them**.
+
+- `windows@TestName` - proves the test passed on a Windows platform
+- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform
+- `net8.0@TestName` - proves the test passed under the .NET 8 runtime
+- `net9.0@TestName` - proves the test passed under the .NET 9 runtime
+- `net10.0@TestName` - proves the test passed under the .NET 10 runtime
+
+Removing a source filter means a test result from any environment can satisfy the requirement, which invalidates
+the evidence-based proof that the library works on a specific platform or framework.
+
 ### TestResults-Specific
 
 - Unit tests live in `test/` directory
 - Use MSTest V4 testing framework
 - Follow existing naming conventions in the test suite
 
+### MSTest V4 Best Practices
+
+Common anti-patterns to avoid (not exhaustive):
+
+1. **Avoid Assertions in Catch Blocks (MSTEST0058)** - Instead of wrapping code in try/catch and asserting in the
+   catch block, use `Assert.ThrowsExactly<T>()`:
+
+   ```csharp
+   var ex = Assert.ThrowsExactly<ArgumentNullException>(() => SomeWork());
+   Assert.Contains("Some message", ex.Message);
+   ```
+
+2. **Avoid using Assert.IsTrue / Assert.IsFalse for equality checks** - Use `Assert.AreEqual` /
+   `Assert.AreNotEqual` instead, as it provides better failure messages:
+
+   ```csharp
+   // ❌ Bad: Assert.IsTrue(result == expected);
+   // ✅ Good: Assert.AreEqual(expected, result);
+   ```
+
+3. **Avoid non-public test classes and methods** - Test classes and `[TestMethod]` methods must be `public` or
+   they will be silently ignored:
+
+   ```csharp
+   // ❌ Bad: internal class MyTests
+   // ✅ Good: public class MyTests
+   ```
+
+4. **Avoid Assert.IsTrue(collection.Count == N)** - Use `Assert.HasCount` for count assertions:
+
+   ```csharp
+   // ❌ Bad: Assert.IsTrue(collection.Count == 3);
+   // ✅ Good: Assert.HasCount(3, collection);
+   ```
+
 ## Defer To
 
 - **Requirements Agent**: For test strategy and coverage requirements

AGENTS.md

@@ -273,6 +273,20 @@ The build process generates:
 - **Requirements Specification PDF**: Complete requirements document
 - **Trace Matrix PDF**: Shows mapping between requirements and test cases with pass/fail status
 
+## Test Source Filters
+
+Test links in `requirements.yaml` can include a source filter prefix to restrict which test results count as
+evidence. This is critical for platform and framework requirements - **do not remove these filters**.
+
+- `windows@TestName` - proves the test passed on a Windows platform
+- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform
+- `net8.0@TestName` - proves the test passed under the .NET 8 runtime
+- `net9.0@TestName` - proves the test passed under the .NET 9 runtime
+- `net10.0@TestName` - proves the test passed under the .NET 10 runtime
+
+Without the source filter, a test result from any platform/framework satisfies the requirement. Adding the filter
+ensures the CI evidence comes specifically from the required environment.
+
 ## Common Tasks for AI Agents
 
 ### Adding a New Feature

CONTRIBUTING.md

@@ -6,7 +6,7 @@ great tool.
 ## Code of Conduct
 
 This project and everyone participating in it is governed by our
-[Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report
+[Code of Conduct][code-of-conduct]. By participating, you are expected to uphold this code. Please report
 unacceptable behavior through GitHub issues.
 
 ## How Can I Contribute?
@@ -46,9 +46,8 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 
 ### Prerequisites
 
-- [.NET SDK 8.0, 9.0, or 10.0](https://dotnet.microsoft.com/download)
-- A code editor ([Visual Studio](https://visualstudio.microsoft.com/),
-  [Visual Studio Code](https://code.visualstudio.com/), or [JetBrains Rider](https://www.jetbrains.com/rider/))
+- [.NET SDK 8.0, 9.0, or 10.0][dotnet-download]
+- A code editor ([Visual Studio][vs], [Visual Studio Code][vscode], or [JetBrains Rider][rider])
 
 ### Getting Started
 
@@ -251,7 +250,7 @@ TestResults/
 
 Releases are managed by the project maintainers:
 
-1. Version numbers follow [Semantic Versioning](https://semver.org/)
+1. Version numbers follow [Semantic Versioning][semver]
 2. Releases are created through GitHub releases
 3. NuGet packages are automatically published on release
 4. Release notes are generated from commit messages
@@ -266,3 +265,11 @@ Contributors will be recognized in the project README and release notes. We appr
 how small!
 
 Thank you for contributing to TestResults! 🎉
+
+<!-- Link References -->
+[code-of-conduct]: CODE_OF_CONDUCT.md
+[dotnet-download]: https://dotnet.microsoft.com/download
+[vs]: https://visualstudio.microsoft.com/
+[vscode]: https://code.visualstudio.com/
+[rider]: https://www.jetbrains.com/rider/
+[semver]: https://semver.org/

README.md

@@ -1,13 +1,13 @@
 # TestResults Library
 
-![GitHub forks](https://img.shields.io/github/forks/demaconsulting/TestResults?style=plastic)
-![GitHub Repo stars](https://img.shields.io/github/stars/demaconsulting/TestResults?style=plastic)
-![GitHub contributors](https://img.shields.io/github/contributors/demaconsulting/TestResults?style=plastic)
-![GitHub](https://img.shields.io/github/license/demaconsulting/TestResults?style=plastic)
-![Build](https://github.com/demaconsulting/TestResults/actions/workflows/build_on_push.yaml/badge.svg)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=demaconsulting_TestResults&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=demaconsulting_TestResults)
-[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=demaconsulting_TestResults&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=demaconsulting_TestResults)
-[![NuGet](https://img.shields.io/nuget/v/DemaConsulting.TestResults?style=plastic)](https://www.nuget.org/packages/DemaConsulting.TestResults)
+[![GitHub forks][badge-forks]][link-forks]
+[![GitHub stars][badge-stars]][link-stars]
+[![GitHub contributors][badge-contributors]][link-contributors]
+[![License][badge-license]][link-license]
+[![Build][badge-build]][link-build]
+[![Quality Gate][badge-quality]][link-quality]
+[![Security][badge-security]][link-security]
+[![NuGet][badge-nuget]][link-nuget]
 
 A lightweight C# library for programmatically creating test result files in TRX and JUnit formats.
 
@@ -268,7 +268,7 @@ We welcome contributions! Please see our [Contributing Guide][contributing] for
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE][license] file for details.
+This project is licensed under the MIT License - see the [LICENSE][link-license] file for details.
 
 ## Support
 
@@ -280,7 +280,27 @@ This project is licensed under the MIT License - see the [LICENSE][license] file
 
 Developed and maintained by [DEMA Consulting](https://github.com/demaconsulting).
 
+<!-- Badge References -->
+[badge-forks]: https://img.shields.io/github/forks/demaconsulting/TestResults?style=plastic
+[badge-stars]: https://img.shields.io/github/stars/demaconsulting/TestResults?style=plastic
+[badge-contributors]: https://img.shields.io/github/contributors/demaconsulting/TestResults?style=plastic
+[badge-license]: https://img.shields.io/github/license/demaconsulting/TestResults?style=plastic
+[badge-build]: https://img.shields.io/github/actions/workflow/status/demaconsulting/TestResults/build_on_push.yaml?style=plastic
+[badge-quality]: https://sonarcloud.io/api/project_badges/measure?project=demaconsulting_TestResults&metric=alert_status
+[badge-security]: https://sonarcloud.io/api/project_badges/measure?project=demaconsulting_TestResults&metric=security_rating
+[badge-nuget]: https://img.shields.io/nuget/v/DemaConsulting.TestResults?style=plastic
+
+<!-- Link References -->
+[link-forks]: https://github.com/demaconsulting/TestResults/network/members
+[link-stars]: https://github.com/demaconsulting/TestResults/stargazers
+[link-contributors]: https://github.com/demaconsulting/TestResults/graphs/contributors
+[link-license]: https://github.com/demaconsulting/TestResults/blob/main/LICENSE
+[link-build]: https://github.com/demaconsulting/TestResults/actions/workflows/build_on_push.yaml
+[link-quality]: https://sonarcloud.io/dashboard?id=demaconsulting_TestResults
+[link-security]: https://sonarcloud.io/dashboard?id=demaconsulting_TestResults
+[link-nuget]: https://www.nuget.org/packages/DemaConsulting.TestResults
+
+<!-- Document References -->
 [architecture]: https://github.com/demaconsulting/TestResults/blob/main/ARCHITECTURE.md
 [contributing]: https://github.com/demaconsulting/TestResults/blob/main/CONTRIBUTING.md
 [code-of-conduct]: https://github.com/demaconsulting/TestResults/blob/main/CODE_OF_CONDUCT.md
-[license]: https://github.com/demaconsulting/TestResults/blob/main/LICENSE

SECURITY.md

@@ -24,7 +24,7 @@ findings.
 Instead, please report them using one of the following methods:
 
 1. **GitHub Security Advisories** (Preferred)
-   - Go to the [Security tab](https://github.com/demaconsulting/TestResults/security)
+   - Go to the [Security tab][security-tab]
    - Click on "Report a vulnerability"
    - Fill out the form with details about the vulnerability
 
@@ -96,7 +96,7 @@ We maintain transparency about known security issues:
 - No known vulnerabilities at this time
 
 Historical security advisories can be found in the
-[GitHub Security Advisories](https://github.com/demaconsulting/TestResults/security/advisories) section.
+[GitHub Security Advisories][security-advisories] section.
 
 ## Security Best Practices for Users
 
@@ -130,3 +130,7 @@ directly.
 ## Attribution
 
 This security policy is based on security policy best practices and adapted for the TestResults project.
+
+<!-- Link References -->
+[security-tab]: https://github.com/demaconsulting/TestResults/security
+[security-advisories]: https://github.com/demaconsulting/TestResults/security/advisories

requirements.yaml

@@ -3,6 +3,17 @@
 #
 # This file defines the requirements for the TestResults library.
 # Requirements are verified through tests and documented in the requirements and trace matrix documents.
+#
+# Test links can include a source filter prefix (e.g. "windows@", "ubuntu@", "net8.0@") to restrict
+# which test results count as evidence for a requirement. This is critical for platform and framework
+# requirements - removing these filters invalidates the evidence-based proof.
+#
+# Source filter prefixes:
+#   windows@TestName  - proves the test passed on a Windows platform
+#   ubuntu@TestName   - proves the test passed on a Linux (Ubuntu) platform
+#   net8.0@TestName   - proves the test passed under the .NET 8 runtime
+#   net9.0@TestName   - proves the test passed under the .NET 9 runtime
+#   net10.0@TestName  - proves the test passed under the .NET 10 runtime
 
 sections:
   - title: TestResults Library Requirements

src/DemaConsulting.TestResults/TestResult.cs

@@ -51,7 +51,7 @@ public sealed class TestResult
     public string ClassName { get; set; } = string.Empty;
 
     /// <summary>
-    ///     Gets the name of the computer that executed the test case
+    ///     Gets or sets the name of the computer that executed the test case
     /// </summary>
     public string ComputerName { get; set; } = Environment.MachineName;