Synchronize with TemplateDotNetTool template PRs #29, #31, #32, #35

Copilot · Malcolmnixon · Copilot · commit eaabff6e8835 · 2026-02-20T14:52:51.000Z
Co-authored-by: Malcolmnixon &lt;1863707+Malcolmnixon@users.noreply.github.com&gt;
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
@@ -39,7 +39,7 @@
       ]
     },
     "demaconsulting.buildmark": {
-      "version": "0.2.0",
+      "version": "0.3.0",
       "commands": [
         "buildmark"
       ]
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -351,14 +351,12 @@ jobs:
       contents: read
 
     steps:
+      # === CHECKOUT AND DOWNLOAD ARTIFACTS ===
+      # This section retrieves the code and all necessary artifacts from previous jobs.
+
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 'lts/*'
-
       - name: Download all test results
         uses: actions/download-artifact@v7
         with:
@@ -385,6 +383,14 @@ jobs:
           pattern: 'version-capture-*'
         continue-on-error: true
 
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies and tools for document generation.
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 'lts/*'
+
       - name: Setup dotnet
         uses: actions/setup-dotnet@v5
         with:
@@ -405,6 +411,9 @@ jobs:
       - name: Restore Tools
         run: dotnet tool restore
 
+      # === CAPTURE TOOL VERSIONS ===
+      # This section captures the versions of all tools used in the build process.
+
       - name: Capture tool versions for build-docs
         shell: bash
         run: |
@@ -413,6 +422,9 @@ jobs:
             dotnet git node npm pandoc weasyprint sarifmark reqstream buildmark versionmark
           echo "✓ Tool versions captured"
 
+      # === GENERATE MARKDOWN REPORTS ===
+      # This section generates all markdown reports from various tools and sources.
+
       - name: Generate Requirements Report and Trace Matrix
         run: >
           dotnet reqstream
@@ -438,70 +450,6 @@ jobs:
           echo "=== CodeQL Quality Report ==="
           cat docs/quality/codeql-quality.md
 
-      - name: Generate HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/guide/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/guide/guide.html
-
-      - name: Generate PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/guide/guide.html
-          "docs/SonarMark User Guide.pdf"
-
-      - name: Generate Requirements HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/requirements/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/requirements/requirements.html
-
-      - name: Generate Requirements PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/requirements/requirements.html
-          "docs/SonarMark Requirements.pdf"
-
-      - name: Generate Trace Matrix HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/tracematrix/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/tracematrix/tracematrix.html
-
-      - name: Generate Trace Matrix PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/tracematrix/tracematrix.html
-          "docs/SonarMark Trace Matrix.pdf"
-
-      - name: Generate Justifications HTML with Pandoc
-        run: >
-          dotnet pandoc
-          --defaults docs/justifications/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --metadata version="${{ inputs.version }}"
-          --metadata date="$(date +'%Y-%m-%d')"
-          --output docs/justifications/justifications.html
-
-      - name: Generate Justifications PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/justifications/justifications.html
-          "docs/SonarMark Requirements Justifications.pdf"
-
       - name: Generate Code Quality Report with SonarMark
         shell: bash
         env:
@@ -536,11 +484,6 @@ jobs:
         run: |
           echo "=== Build Notes Report ==="
           cat docs/buildnotes.md
-          # Verify buildnotes.md was created
-          if [ ! -f "docs/buildnotes.md" ]; then
-            echo "Error: buildnotes.md was not created"
-            exit 1
-          fi
 
       - name: Publish Tool Versions
         shell: bash
@@ -556,6 +499,45 @@ jobs:
           echo "=== Tool Versions Report ==="
           cat docs/buildnotes/versions.md
 
+      # === GENERATE HTML DOCUMENTS WITH PANDOC ===
+      # This section converts markdown documents to HTML using Pandoc.
+
+      - name: Generate Guide HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/guide/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/guide/guide.html
+
+      - name: Generate Requirements HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/requirements/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/requirements/requirements.html
+
+      - name: Generate Trace Matrix HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/tracematrix/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/tracematrix/tracematrix.html
+
+      - name: Generate Justifications HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/justifications/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/justifications/justifications.html
+
       - name: Generate Build Notes HTML with Pandoc
         shell: bash
         run: >
@@ -566,13 +548,6 @@ jobs:
           --filter node_modules/.bin/mermaid-filter.cmd
           --output docs/buildnotes/buildnotes.html
 
-      - name: Convert Build Notes HTML to PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          --pdf-variant pdf/a-3u
-          docs/buildnotes/buildnotes.html
-          "docs/SonarMark Build Notes.pdf"
-
       - name: Generate Code Quality HTML with Pandoc
         run: >
           dotnet pandoc
@@ -582,13 +557,54 @@ jobs:
           --metadata date="$(date +'%Y-%m-%d')"
           --output docs/quality/quality.html
 
+      # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
+      # This section converts HTML documents to PDF using Weasyprint.
+
+      - name: Generate Guide PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/guide/guide.html
+          "docs/SonarMark User Guide.pdf"
+
+      - name: Generate Requirements PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/requirements/requirements.html
+          "docs/SonarMark Requirements.pdf"
+
+      - name: Generate Trace Matrix PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/tracematrix/tracematrix.html
+          "docs/SonarMark Trace Matrix.pdf"
+
+      - name: Generate Justifications PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/justifications/justifications.html
+          "docs/SonarMark Requirements Justifications.pdf"
+
+      - name: Generate Build Notes PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/buildnotes/buildnotes.html
+          "docs/SonarMark Build Notes.pdf"
+
       - name: Generate Code Quality PDF with Weasyprint
         run: >
           dotnet weasyprint
           --pdf-variant pdf/a-3u
           docs/quality/quality.html
           "docs/SonarMark Code Quality.pdf"
 
+      # === UPLOAD ARTIFACTS ===
+      # This section uploads all generated documentation artifacts.
+
       - name: Upload documentation
         uses: actions/upload-artifact@v6
         with:
diff --git a/.gitignore b/.gitignore
@@ -56,4 +56,8 @@ docs/justifications/*.html
 docs/quality/sonar-quality.md
 docs/quality/codeql-quality.md
 docs/quality/*.html
+docs/buildnotes.md
 docs/buildnotes/versions.md
+
+# VersionMark captures (generated during CI/CD)
+versionmark-*.json
diff --git a/AGENTS.md b/AGENTS.md
@@ -31,6 +31,23 @@ SonarQube/SonarCloud analysis results.
 - Enforced in CI: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce`
 - When adding features: add requirement + link to test
 
+## 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 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. Adding the
+filter ensures the CI evidence comes specifically from the required environment.
+
 ## Testing (SonarMark-Specific)
 
 - **Test Naming**: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` (for requirements traceability)

Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@`
`39`	`39`	`]`
`40`	`40`	`},`
`41`	`41`	`"demaconsulting.buildmark": {`
`42`		`- "version": "0.2.0",`
	`42`	`+ "version": "0.3.0",`
`43`	`43`	`"commands": [`
`44`	`44`	`"buildmark"`
`45`	`45`	`]`