Align BuildMark with TemplateDotNetTool template updates

.github/agents/code-quality-agent.md

@@ -31,7 +31,7 @@ Ensure the project is:
 
 1. **Build**: Zero warnings (TreatWarningsAsErrors=true)
 2. **Linting**:
-   - markdownlint (`.markdownlint.json`)
+   - markdownlint (`.markdownlint-cli2.jsonc`)
    - cspell (`.cspell.json`)
    - yamllint (`.yamllint.yaml`)
    - dotnet format (`.editorconfig`)

.github/agents/requirements-agent.md

@@ -49,6 +49,23 @@ Follow the `requirements.yaml` structure:
 - Linked to appropriate test(s)
 - Enforced via: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce`
 
+### 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 - **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 target framework
+- `net9.0@TestName` - proves the test passed under the .NET 9 target framework
+- `net10.0@TestName` - proves the test passed under the .NET 10 target framework
+- `dotnet8.x@TestName` - proves the self-validation test ran on a machine with .NET 8.x runtime
+- `dotnet9.x@TestName` - proves the self-validation test ran on a machine with .NET 9.x runtime
+- `dotnet10.x@TestName` - proves the self-validation test ran on a machine with .NET 10.x runtime
+
+Without the source filter, a test result from any platform/framework satisfies the requirement. Removing a
+filter invalidates the evidence for platform/framework requirements.
+
 ## Defer To
 
 - **Software Developer Agent**: For implementing self-validation tests

.github/agents/software-developer.md

@@ -52,7 +52,8 @@ var results = ProcessFile(options.InputFile);
 
 ### BuildMark-Specific Rules
 
-- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` in summaries
+- **XML Docs**: On ALL members (public/internal/private) with spaces after `///`
+  - Follow standard XML indentation rules with four-space indentation
 - **Errors**: `ArgumentException` for parsing, `InvalidOperationException` for runtime issues
 - **Namespace**: File-scoped namespaces only
 - **Using Statements**: Top of file only

.github/agents/technical-writer.md

@@ -31,8 +31,10 @@ Invoke the technical-writer for:
 
 #### Markdown Style
 
-- **README.md ONLY**: Use absolute URLs in the links (shipped in NuGet package)
-- **All other markdown files**: Use reference-style links
+- **All markdown files**: Use reference-style links `[text][ref]` with `[ref]: url` at document end
+- **Exceptions**:
+  - **README.md**: Use absolute URLs in the links (shipped in NuGet package)
+  - **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent context
 - Max 120 characters per line
 - Lists require blank lines (MD032)
 

.github/agents/test-developer.md

@@ -71,6 +71,67 @@ public void ClassName_MethodUnderTest_Scenario_ExpectedBehavior()
 - Use MSTest V4 testing framework
 - Follow existing naming conventions in the test suite
 
+### 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 target framework
+- `net9.0@TestName` - proves the test passed under the .NET 9 target framework
+- `net10.0@TestName` - proves the test passed under the .NET 10 target framework
+- `dotnet8.x@TestName` - proves the self-validation test ran on a machine with .NET 8.x runtime
+- `dotnet9.x@TestName` - proves the self-validation test ran on a machine with .NET 9.x runtime
+- `dotnet10.x@TestName` - proves the self-validation test ran on a machine with .NET 10.x runtime
+
+Removing a source filter means a test result from any environment can satisfy the requirement, which invalidates
+the evidence-based proof that the tool works on a specific platform or framework.
+
+### 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);
+   ```
+
+5. **Avoid Assert.IsTrue for string prefix checks** - Use `Assert.StartsWith` instead of wrapping
+   `string.StartsWith` in `Assert.IsTrue`, as it produces clearer failure messages that show the expected prefix
+   and actual value:
+
+   ```csharp
+   // ❌ Bad: Assert.IsTrue(value.StartsWith("prefix"));
+   // ✅ Good: Assert.StartsWith("prefix", value);
+   ```
+
 ## Defer To
 
 - **Requirements Agent**: For test strategy and coverage requirements

src/DemaConsulting.BuildMark/DemaConsulting.BuildMark.csproj

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
-    <LangVersion>12</LangVersion>
+    <LangVersion>latest</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 
@@ -34,7 +34,7 @@
 
     <!-- Code Quality Configuration -->
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <GenerateDocumentationFile>True</GenerateDocumentationFile>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
@@ -50,13 +50,25 @@
     <PackageReference Include="DemaConsulting.TestResults" Version="1.5.0" />
     <PackageReference Include="GraphQL.Client" Version="6.1.0" />
     <PackageReference Include="GraphQL.Client.Serializer.SystemTextJson" Version="6.1.0" />
+    <!-- PrivateAssets="All" prevents these build-time-only packages from becoming transitive dependencies -->
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.103" PrivateAssets="All" />
+    <!--
+      Analyzer and source-only packages require both PrivateAssets and IncludeAssets:
+        PrivateAssets="all"   - prevents these build-time assets from flowing to consumers
+        IncludeAssets         - explicitly enables contentfiles (source injection) and
+                                analyzers/buildtransitive (Roslyn analyzers at compile time)
+    -->
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.103">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.19.0.132793">
+    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.20.0.135146">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <!-- Polyfill is a source-only package; contentfiles delivers the polyfill source into this project -->
+    <PackageReference Include="Polyfill" Version="9.12.0">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>

test/DemaConsulting.BuildMark.Tests/DemaConsulting.BuildMark.Tests.csproj

@@ -1,38 +1,53 @@
 <Project Sdk="Microsoft.NET.Sdk">
+
   <PropertyGroup>
+    <!-- Build Configuration -->
     <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
-    <LangVersion>12</LangVersion>
+    <LangVersion>latest</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+
+    <!-- Code Quality Configuration -->
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
-
-    <IsPackable>false</IsPackable>
-    <IsTestProject>true</IsTestProject>
-    <GenerateDocumentationFile>True</GenerateDocumentationFile>
   </PropertyGroup>
 
+  <!-- Implicit Usings -->
+  <ItemGroup>
+    <Using Include="Polyfills" />
+  </ItemGroup>
+
+  <!-- Test Framework Dependencies -->
   <ItemGroup>
     <PackageReference Include="coverlet.collector" Version="8.0.0">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+    <PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+    <PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
+    <PackageReference Include="NSubstitute" Version="5.3.0" />
+  </ItemGroup>
+
+  <!-- Code Analysis Dependencies -->
+  <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.103">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
-    <PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
-    <PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
-    <PackageReference Include="NSubstitute" Version="5.3.0" />
-    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.19.0.132793">
+    <PackageReference Include="SonarAnalyzer.CSharp" Version="10.20.0.135146">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
 
+  <!-- Project References -->
   <ItemGroup>
     <ProjectReference Include="..\..\src\DemaConsulting.BuildMark\DemaConsulting.BuildMark.csproj" />
   </ItemGroup>