From fc19a818ddf8fb2ffbaed67a11be54ad7490ad8f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Mar 2026 20:40:13 +0000
Subject: [PATCH 1/5] Initial plan


From 145e6bdeb698680c10ec8ac292dce1fa06a17277 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Mar 2026 20:53:01 +0000
Subject: [PATCH 2/5] chore: bring in updates from the template repo (PRs #52,
 #54, #55)

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
---
 .config/dotnet-tools.json           |   2 +-
 .github/ISSUE_TEMPLATE/question.yml |  82 ++++++++++
 .github/workflows/build.yaml        | 227 ++++++++++++++++++----------
 .github/workflows/release.yaml      |   2 +-
 AGENTS.md                           |  17 ++-
 README.md                           |   2 +-
 requirements.yaml                   |  92 +++++++++++
 7 files changed, 342 insertions(+), 82 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/question.yml

diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
index d6b5cd8..f3d6b4c 100644
--- a/.config/dotnet-tools.json
+++ b/.config/dotnet-tools.json
@@ -33,7 +33,7 @@
       ]
     },
     "demaconsulting.reqstream": {
-      "version": "1.3.0",
+      "version": "1.4.0",
       "commands": [
         "reqstream"
       ]
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
new file mode 100644
index 0000000..aa3b7d1
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/question.yml
@@ -0,0 +1,82 @@
+---
+name: ❓ Question / Help
+description: Ask a usage question or get help with the NuGet Cache Tool
+title: "[Question]: "
+labels: ["question"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reaching out! Please fill out the sections below so we can help you as quickly as possible.
+        For general discussion, you can also use
+        [GitHub Discussions](https://github.com/demaconsulting/NuGetCacheTool/discussions).
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: A clear and concise description of what you need help with.
+      placeholder: What would you like to know or understand?
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-tried
+    attributes:
+      label: What Have You Tried?
+      description: Describe what you have already attempted, including any code or configuration you have used.
+      placeholder: |
+        ```bash
+        # Your command here
+        ```
+      render: bash
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Outcome
+      description: A clear and concise description of what you expected to happen or what you are trying to achieve.
+      placeholder: Describe the outcome you are looking for...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Tool Version
+      description: What version of the NuGet Cache Tool are you using?
+      placeholder: e.g., 1.0.0
+    validations:
+      required: true
+
+  - type: dropdown
+    id: dotnet-version
+    attributes:
+      label: .NET Version
+      description: What version of .NET are you using?
+      options:
+        - ".NET 8"
+        - ".NET 9"
+        - ".NET 10"
+        - Other (please specify in additional context)
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or links that may help answer your question.
+      placeholder: Any additional information...
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following
+      options:
+        - label: I have searched existing issues and discussions to ensure this has not been answered before
+          required: true
+        - label: I have provided a clear description of my question
+          required: true
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index 50d7d40..ce26736 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -18,6 +18,10 @@ jobs:
     permissions:
       contents: read
     steps:
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies for quality checks.
+      # Downstream projects: Add any additional dependency installations here.
+
       - name: Checkout
         uses: actions/checkout@v6
 
@@ -33,15 +37,23 @@ jobs:
       - name: Capture tool versions
         shell: bash
         run: |
+          mkdir -p artifacts
           echo "Capturing tool versions..."
-          dotnet versionmark --capture --job-id "quality" -- dotnet git versionmark
+          dotnet versionmark --capture --job-id "quality" \
+            --output "artifacts/versionmark-quality.json" -- \
+            dotnet git versionmark
           echo "✓ Tool versions captured"
 
-      - name: Upload version capture
-        uses: actions/upload-artifact@v7
-        with:
-          name: version-capture-quality
-          path: versionmark-quality.json
+      # === CAPTURE OTS SELF-VALIDATION RESULTS ===
+      # This section captures self-validation results from OTS tools.
+      # Downstream projects: Add any additional self-validation steps here.
+
+      - name: Run VersionMark self-validation
+        run: dotnet versionmark --validate --results artifacts/versionmark-self-validation-quality.trx
+
+      # === RUN QUALITY CHECKS ===
+      # This section runs all quality checks for the project.
+      # Downstream projects: Add any additional quality checks here.
 
       - name: Run markdown linter
         uses: DavidAnson/markdownlint-cli2-action@v22
@@ -59,6 +71,12 @@ jobs:
         with:
           config_file: .yamllint.yaml
 
+      - name: Upload quality artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: artifacts-quality
+          path: artifacts/
+
   # Builds and unit-tests the project on supported operating systems to ensure
   # unit-tests operate on all platforms and to run SonarScanner for generating
   # the code quality report.
@@ -71,12 +89,16 @@ jobs:
 
     strategy:
       matrix:
-        os: [windows-latest, ubuntu-latest]
+        os: [windows-latest, ubuntu-latest, macos-latest]
 
     runs-on: ${{ matrix.os }}
 
     steps:
 
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies for the build.
+      # Downstream projects: Add any additional dependency installations here.
+
       - name: Checkout
         uses: actions/checkout@v6
         with:
@@ -94,6 +116,34 @@ jobs:
         run: >
           dotnet tool restore
 
+      # === CAPTURE TOOL VERSIONS ===
+      # This section captures the versions of all tools used in the build process.
+      # Downstream projects: Add any additional tools to capture here.
+
+      - name: Capture tool versions
+        shell: bash
+        run: |
+          mkdir -p artifacts
+          echo "Capturing tool versions..."
+          # Create short job ID: build-windows, build-ubuntu, build-macos
+          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//')
+          JOB_ID="build-${OS_SHORT}"
+          dotnet versionmark --capture --job-id "${JOB_ID}" \
+            --output "artifacts/versionmark-${JOB_ID}.json" -- \
+            dotnet git dotnet-sonarscanner versionmark
+          echo "✓ Tool versions captured"
+
+      # === CAPTURE OTS SELF-VALIDATION RESULTS ===
+      # This section captures self-validation results from OTS tools.
+      # Downstream projects: Add any additional self-validation steps here.
+
+      - name: Run VersionMark self-validation
+        run: dotnet versionmark --validate --results artifacts/versionmark-self-validation-${{ matrix.os }}.trx
+
+      # === BUILD AND TEST ===
+      # This section builds and tests the project.
+      # Downstream projects: Add any additional build and test steps here.
+
       - name: Restore Dependencies
         run: >
           dotnet restore
@@ -126,7 +176,7 @@ jobs:
           --property:Version=${{ inputs.version }}
           --collect "XPlat Code Coverage;Format=opencover"
           --logger "trx;LogFilePrefix=${{ matrix.os }}"
-          --results-directory test-results
+          --results-directory artifacts
 
       - name: End Sonar Scanner
         env:
@@ -143,33 +193,20 @@ jobs:
           --no-restore
           --property:PackageVersion=${{ inputs.version }}
 
-      - name: Capture tool versions
-        shell: bash
-        run: |
-          echo "Capturing tool versions..."
-          # Create short job ID: build-win, build-ubuntu
-          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/windows-latest/win/;s/ubuntu-latest/ubuntu/')
-          JOB_ID="build-${OS_SHORT}"
-          dotnet versionmark --capture --job-id "${JOB_ID}" -- \
-            dotnet git dotnet-sonarscanner versionmark
-          echo "✓ Tool versions captured"
-
-      - name: Upload version capture
-        uses: actions/upload-artifact@v7
-        with:
-          name: version-capture-${{ matrix.os }}
-          path: versionmark-build-*.json
+      # === UPLOAD ARTIFACTS ===
+      # This section uploads all build artifacts.
+      # Downstream projects: Add any additional artifact uploads here.
 
-      - name: Upload Test Results
+      - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: test-results-${{ matrix.os }}
-          path: test-results/*.trx
+          name: artifacts-build-${{ matrix.os }}
+          path: artifacts/
 
-      - name: Upload Artifacts
+      - name: Upload packages
         uses: actions/upload-artifact@v7
         with:
-          name: artifacts-${{ matrix.os }}
+          name: packages-${{ matrix.os }}
           path: |
             src/DemaConsulting.NuGet.CacheTool/bin/Release/*.nupkg
             src/DemaConsulting.NuGet.CacheTool/bin/Release/*.snupkg
@@ -186,6 +223,10 @@ jobs:
       security-events: write
 
     steps:
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies for CodeQL analysis.
+      # Downstream projects: Add any additional dependency installations here.
+
       - name: Checkout
         uses: actions/checkout@v6
         with:
@@ -195,6 +236,7 @@ jobs:
         uses: github/codeql-action/init@v4
         with:
           languages: csharp
+          build-mode: manual
           queries: security-and-quality
           config-file: ./.github/codeql-config.yml
 
@@ -214,6 +256,10 @@ jobs:
         run: >
           dotnet restore
 
+      # === BUILD AND ANALYZE ===
+      # This section builds the project and runs CodeQL analysis.
+      # Downstream projects: Add any additional analysis steps here.
+
       - name: Build
         run: >
           dotnet build
@@ -225,14 +271,18 @@ jobs:
         uses: github/codeql-action/analyze@v4
         with:
           category: "/language:csharp"
-          output: sarif-results
+          output: artifacts
           upload: false
 
-      - name: Upload CodeQL SARIF
+      # === UPLOAD ARTIFACTS ===
+      # This section uploads all CodeQL artifacts.
+      # Downstream projects: Add any additional artifact uploads here.
+
+      - name: Upload CodeQL artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: codeql-sarif
-          path: sarif-results/csharp.sarif
+          name: artifacts-codeql
+          path: artifacts/
 
   # Performs integration testing on a matrix of operating systems and .NET runtimes,
   # involving basic tool execution and running self-validation to ensure compatibility
@@ -246,10 +296,14 @@ jobs:
 
     strategy:
       matrix:
-        os: [windows-latest, ubuntu-latest]
+        os: [windows-latest, ubuntu-latest, macos-latest]
         dotnet-version: ['8.x', '9.x', '10.x']
 
     steps:
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies and tools for integration testing.
+      # Downstream projects: Add any additional dependency installations here.
+
       - name: Checkout
         uses: actions/checkout@v6
         with:
@@ -260,7 +314,7 @@ jobs:
       - name: Download package
         uses: actions/download-artifact@v8
         with:
-          name: artifacts-${{ matrix.os }}
+          name: packages-${{ matrix.os }}
           path: packages
 
       - name: Setup dotnet
@@ -281,6 +335,28 @@ jobs:
             --version ${{ inputs.version }} \
             DemaConsulting.NuGet.CacheTool
 
+      # === CAPTURE TOOL VERSIONS ===
+      # This section captures the versions of all tools used in the integration tests.
+      # Downstream projects: Add any additional tools to capture here.
+
+      - name: Capture tool versions
+        shell: bash
+        run: |
+          mkdir -p artifacts
+          echo "Capturing tool versions..."
+          # Create short job ID: int-windows-8, int-ubuntu-9, int-macos-10, etc.
+          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/-latest//')
+          DOTNET_SHORT=$(echo "${{ matrix.dotnet-version }}" | sed 's/\.x$//')
+          JOB_ID="int-${OS_SHORT}-${DOTNET_SHORT}"
+          dotnet versionmark --capture --job-id "${JOB_ID}" \
+            --output "artifacts/versionmark-${JOB_ID}.json" -- \
+            dotnet git versionmark
+          echo "✓ Tool versions captured"
+
+      # === RUN INTEGRATION TESTS ===
+      # This section runs the integration tests for the tool.
+      # Downstream projects: Add any additional integration test steps here.
+
       - name: Test version display
         shell: bash
         run: |
@@ -299,33 +375,21 @@ jobs:
         shell: bash
         run: |
           echo "Running self-validation..."
-          nuget-cache --validate --results validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx \
+          nuget-cache --validate \
+            --results artifacts/validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx \
             || { echo "✗ Self-validation failed"; exit 1; }
           echo "✓ Self-validation succeeded"
 
-      - name: Capture tool versions
-        shell: bash
-        run: |
-          echo "Capturing tool versions..."
-          # Create short job ID: int-win-8, int-win-9, int-ubuntu-8, etc.
-          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/windows-latest/win/;s/ubuntu-latest/ubuntu/')
-          DOTNET_SHORT=$(echo "${{ matrix.dotnet-version }}" | sed 's/\.x$//')
-          JOB_ID="int-${OS_SHORT}-${DOTNET_SHORT}"
-          dotnet versionmark --capture --job-id "${JOB_ID}" -- dotnet git versionmark
-          echo "✓ Tool versions captured"
-
-      - name: Upload version capture
-        uses: actions/upload-artifact@v7
-        with:
-          name: version-capture-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
-          path: versionmark-int-*.json
+      # === UPLOAD ARTIFACTS ===
+      # This section uploads all generated artifacts for use by downstream jobs.
+      # Downstream projects: Add any additional artifact uploads here.
 
-      - name: Upload validation test results
+      - name: Upload validation artifacts
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: validation-test-results-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
-          path: validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx
+          name: artifacts-validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
+          path: artifacts/
 
   # Builds the supporting documentation including user guides, requirements,
   # trace matrices, code quality reports, and build notes.
@@ -344,32 +408,20 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Download all test results
+      - name: Download all job artifacts
         uses: actions/download-artifact@v8
         with:
-          path: test-results
-          pattern: '*test-results*'
+          path: artifacts
+          pattern: 'artifacts-*'
+          merge-multiple: true
         continue-on-error: true
 
-      - name: Download NuGetCacheTool package
+      - name: Download packages artifact
         uses: actions/download-artifact@v8
         with:
-          name: artifacts-windows-latest
+          name: packages-ubuntu-latest
           path: packages
 
-      - name: Download CodeQL SARIF
-        uses: actions/download-artifact@v8
-        with:
-          name: codeql-sarif
-          path: codeql-results
-
-      - name: Download all version captures
-        uses: actions/download-artifact@v8
-        with:
-          path: version-captures
-          pattern: 'version-capture-*'
-        continue-on-error: true
-
       # === INSTALL DEPENDENCIES ===
       # This section installs all required dependencies and tools for document generation.
       # Downstream projects: Add any additional dependency installations here.
@@ -406,11 +458,32 @@ jobs:
       - name: Capture tool versions for build-docs
         shell: bash
         run: |
+          mkdir -p artifacts
           echo "Capturing tool versions..."
-          dotnet versionmark --capture --job-id "build-docs" -- \
+          dotnet versionmark --capture --job-id "build-docs" \
+            --output "artifacts/versionmark-build-docs.json" -- \
             dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark
           echo "✓ Tool versions captured"
 
+      # === CAPTURE OTS SELF-VALIDATION RESULTS ===
+      # This section captures self-validation results from OTS tools.
+      # Downstream projects: Add any additional self-validation steps here.
+
+      - name: Run ReqStream self-validation
+        run: dotnet reqstream --validate --results artifacts/reqstream-self-validation.trx
+
+      - name: Run BuildMark self-validation
+        run: dotnet buildmark --validate --results artifacts/buildmark-self-validation.trx
+
+      - name: Run VersionMark self-validation
+        run: dotnet versionmark --validate --results artifacts/versionmark-self-validation.trx
+
+      - name: Run SarifMark self-validation
+        run: dotnet sarifmark --validate --results artifacts/sarifmark-self-validation.trx
+
+      - name: Run SonarMark self-validation
+        run: dotnet sonarmark --validate --results artifacts/sonarmark-self-validation.trx
+
       # === GENERATE MARKDOWN REPORTS ===
       # This section generates all markdown reports from various tools and sources.
       # Downstream projects: Add any additional markdown report generation steps here.
@@ -419,7 +492,7 @@ jobs:
         run: >
           dotnet reqstream
           --requirements requirements.yaml
-          --tests "test-results/**/*.trx"
+          --tests "artifacts/**/*.trx"
           --report docs/requirements/requirements.md
           --justifications docs/justifications/justifications.md
           --matrix docs/tracematrix/tracematrix.md
@@ -428,7 +501,7 @@ jobs:
       - name: Generate CodeQL Quality Report with SarifMark
         run: >
           dotnet sarifmark
-          --sarif codeql-results/csharp.sarif
+          --sarif artifacts/csharp.sarif
           --report docs/quality/codeql-quality.md
           --heading "NuGet Cache Tool CodeQL Analysis"
           --report-depth 1
@@ -479,7 +552,7 @@ jobs:
         run: |
           echo "Publishing tool versions..."
           dotnet versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \
-            -- "versionmark-*.json" "version-captures/**/versionmark-*.json"
+            -- "artifacts/**/versionmark-*.json"
           echo "✓ Tool versions published"
 
       - name: Display Tool Versions Report
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 821a753..9a81642 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -54,7 +54,7 @@ jobs:
       - name: Download package artifacts
         uses: actions/download-artifact@v8
         with:
-          name: artifacts-ubuntu-latest
+          name: packages-ubuntu-latest
           path: artifacts
 
       - name: Download documents artifact
diff --git a/AGENTS.md b/AGENTS.md
index 46bebfb..ad5107e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,18 @@ tool for DEMA Consulting .NET developers.
 - **Code Quality Agent** - Enforces linting, static analysis, and security standards
 - **Repo Consistency Agent** - Ensures downstream repositories remain consistent with template patterns
 
+## Agent Selection Guide
+
+- Fix a bug → **Software Developer**
+- Add a new feature → **Requirements Agent** → **Software Developer** → **Test Developer**
+- Write a test → **Test Developer**
+- Fix linting or static analysis issues → **Code Quality Agent**
+- Update documentation → **Technical Writer**
+- Add or update requirements → **Requirements Agent**
+- Ensure test coverage linkage in `requirements.yaml` → **Requirements Agent**
+- Run security scanning or address CodeQL alerts → **Code Quality Agent**
+- Propagate template changes → **Repo Consistency Agent**
+
 ## Tech Stack
 
 - C# (latest), .NET 8.0/9.0/10.0, dotnet CLI, NuGet
@@ -36,6 +48,7 @@ evidence. This is critical for platform and framework requirements - **do not re
 
 - `windows@TestName` - proves the test passed on a Windows platform
 - `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform
+- `macos@TestName` - proves the test passed on a macOS 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
@@ -102,9 +115,9 @@ build.bat     # Windows
 ## CI/CD
 
 - **Quality Checks**: Markdown lint, spell check, YAML lint
-- **Build**: Multi-platform (Windows/Linux)
+- **Build**: Multi-platform (Windows/Linux/macOS)
 - **CodeQL**: Security scanning
-- **Integration Tests**: .NET 8/9/10 on Windows/Linux
+- **Integration Tests**: .NET 8/9/10 on Windows/Linux/macOS
 - **Documentation**: Auto-generated via Pandoc + Weasyprint
 
 ## Common Tasks
diff --git a/README.md b/README.md
index a5e158b..d0e088b 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ This tool provides:
 - **Multiple Packages**: Specify multiple packages in a single command
 - **Package Path Output**: Output the path to each cached package
 - **Self-Validation**: Built-in validation tests with TRX/JUnit output
-- **Multi-Platform Support**: Builds and runs on Windows and Linux
+- **Multi-Platform Support**: Builds and runs on Windows, Linux, and macOS
 - **Multi-Runtime Support**: Targets .NET 8, 9, and 10
 
 ## Installation
diff --git a/requirements.yaml b/requirements.yaml
index b12a41f..b5bc675 100644
--- a/requirements.yaml
+++ b/requirements.yaml
@@ -19,6 +19,7 @@
 # Source filter prefixes:
 #   windows@TestName    - proves the test passed on a Windows platform
 #   ubuntu@TestName     - proves the test passed on a Linux (Ubuntu) platform
+#   macos@TestName      - proves the test passed on a macOS 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
@@ -179,6 +180,15 @@ sections:
               - "ubuntu@NuGetCache_VersionDisplay"
               - "ubuntu@NuGetCache_HelpDisplay"
 
+          - id: NC-PLT-006
+            title: The tool shall build and run on macOS platforms.
+            justification: |
+              DEMA Consulting tools must support macOS for developers using Apple platforms.
+            tests:
+              # Tests link to "macos" to ensure results come from macOS platform
+              - "macos@NuGetCache_VersionDisplay"
+              - "macos@NuGetCache_HelpDisplay"
+
           - id: NC-PLT-003
             title: The tool shall support .NET 8 runtime.
             justification: |
@@ -202,3 +212,85 @@ sections:
             tests:
               - "dotnet10.x@NuGetCache_VersionDisplay"
               - "dotnet10.x@NuGetCache_HelpDisplay"
+
+      - title: OTS Software
+        requirements:
+          - id: NuGetCache-OTS-MSTest
+            title: MSTest shall execute unit tests and report results.
+            justification: |
+              MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used
+              by the project. It discovers and runs all test methods and writes TRX result files that
+              feed into coverage reporting and requirements traceability. Passing tests confirm the
+              framework is functioning correctly.
+            tags: [ots]
+            tests:
+              - Context_Create_NoArguments_ReturnsDefaultContext
+              - Context_Create_VersionFlag_SetsVersionTrue
+              - Context_Create_HelpFlag_SetsHelpTrue
+              - Context_Create_SilentFlag_SetsSilentTrue
+              - Context_Create_ValidateFlag_SetsValidateTrue
+              - Context_Create_ResultsFlag_SetsResultsFile
+              - Context_Create_LogFlag_OpensLogFile
+              - Context_Create_UnknownArgument_ThrowsArgumentException
+              - Context_Create_ShortVersionFlag_SetsVersionTrue
+
+          - id: NuGetCache-OTS-ReqStream
+            title: ReqStream shall enforce that every requirement is linked to passing test evidence.
+            justification: |
+              DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to
+              produce a requirements report, justifications document, and traceability matrix. When
+              run with --enforce, it exits with a non-zero code if any requirement lacks test evidence,
+              making unproven requirements a build-breaking condition. A successful pipeline run with
+              --enforce proves all requirements are covered and that ReqStream is functioning.
+            tags: [ots]
+            tests:
+              - ReqStream_EnforcementMode
+
+          - id: NuGetCache-OTS-BuildMark
+            title: BuildMark shall generate build-notes documentation from GitHub Actions metadata.
+            justification: |
+              DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and
+              renders them as a markdown build-notes document included in the release artifacts.
+              It runs as part of the same CI pipeline that produces the TRX test results, so a
+              successful pipeline run is evidence that BuildMark executed without error.
+            tags: [ots]
+            tests:
+              - BuildMark_MarkdownReportGeneration
+
+          - id: NuGetCache-OTS-VersionMark
+            title: VersionMark shall publish captured tool-version information.
+            justification: |
+              DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the
+              pipeline and writes a versions markdown document included in the release artifacts.
+              It runs in the same CI pipeline that produces the TRX test results, so a successful
+              pipeline run is evidence that VersionMark executed without error.
+            tags: [ots]
+            tests:
+              - VersionMark_CapturesVersions
+              - VersionMark_GeneratesMarkdownReport
+
+          - id: NuGetCache-OTS-SarifMark
+            title: SarifMark shall convert CodeQL SARIF results into a markdown report.
+            justification: |
+              DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and
+              renders it as a human-readable markdown document included in the release artifacts.
+              It runs in the same CI pipeline that produces the TRX test results, so a successful
+              pipeline run is evidence that SarifMark executed without error.
+            tags: [ots]
+            tests:
+              - SarifMark_SarifReading
+              - SarifMark_MarkdownReportGeneration
+
+          - id: NuGetCache-OTS-SonarMark
+            title: SonarMark shall generate a SonarCloud quality report.
+            justification: |
+              DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and
+              renders it as a markdown document included in the release artifacts. It runs in the
+              same CI pipeline that produces the TRX test results, so a successful pipeline run is
+              evidence that SonarMark executed without error.
+            tags: [ots]
+            tests:
+              - SonarMark_QualityGateRetrieval
+              - SonarMark_IssuesRetrieval
+              - SonarMark_HotSpotsRetrieval
+              - SonarMark_MarkdownReportGeneration

From 2d27c788b7cd5c5e2fe765d04bbbd1da6bcecb93 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 8 Mar 2026 01:05:05 +0000
Subject: [PATCH 3/5] chore: apply template PR #50 semantic requirement IDs and
 documentation fixes

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
---
 AGENTS.md         |  2 +-
 CONTRIBUTING.md   |  4 ++--
 requirements.yaml | 34 +++++++++++++++++-----------------
 3 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ad5107e..0245590 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,7 +31,7 @@ tool for DEMA Consulting .NET developers.
 ## Key Files
 
 - **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`)
-- **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings)
+- **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings)
 - **`.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml`** - Linting configs
 
 ## Requirements
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6df3c4f..d6314a9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -95,7 +95,7 @@ This project enforces code style through `.editorconfig`. Key requirements:
 
 - **Indentation**: 4 spaces for C#, 2 spaces for YAML/JSON/XML
 - **Line Endings**: LF (Unix-style)
-- **Encoding**: UTF-8 with BOM
+- **Encoding**: UTF-8
 - **Namespaces**: Use file-scoped namespace declarations
 - **Braces**: Required for all control statements
 - **Naming Conventions**:
@@ -142,7 +142,7 @@ Examples:
 
 - Write tests that are clear and focused
 - Use modern MSTest v4 assertions:
-  - `Assert.HasCount(collection, expectedCount)`
+  - `Assert.HasCount(expectedCount, collection)`
   - `Assert.IsEmpty(collection)`
   - `Assert.DoesNotContain(item, collection)`
 - Always clean up resources (use `try/finally` for console redirection)
diff --git a/requirements.yaml b/requirements.yaml
index b5bc675..e9689c0 100644
--- a/requirements.yaml
+++ b/requirements.yaml
@@ -33,7 +33,7 @@ sections:
     sections:
       - title: Command-Line Interface
         requirements:
-          - id: NC-CLI-001
+          - id: NuGetCache-Cmd-Context
             title: The tool shall implement a Context class for command-line argument handling.
             justification: |
               Provides a standardized approach to command-line argument parsing and output
@@ -47,7 +47,7 @@ sections:
               - Context_Create_ResultsFlag_SetsResultsFile
               - Context_Create_LogFlag_OpensLogFile
 
-          - id: NC-CLI-002
+          - id: NuGetCache-Cmd-Version
             title: The tool shall support -v and --version flags to display version information.
             justification: |
               Users need to quickly identify the version of the tool they are using for
@@ -59,7 +59,7 @@ sections:
               - Program_Version_ReturnsNonEmptyString
               - IntegrationTest_VersionFlag_OutputsVersion
 
-          - id: NC-CLI-003
+          - id: NuGetCache-Cmd-Help
             title: The tool shall support -?, -h, and --help flags to display usage information.
             justification: |
               Users need access to command-line usage documentation without requiring
@@ -71,7 +71,7 @@ sections:
               - Program_Run_WithHelpFlag_DisplaysUsageInformation
               - IntegrationTest_HelpFlag_OutputsUsageInformation
 
-          - id: NC-CLI-004
+          - id: NuGetCache-Cmd-Silent
             title: The tool shall support --silent flag to suppress console output.
             justification: |
               Enables automated scripts and CI/CD pipelines to run the tool without
@@ -81,7 +81,7 @@ sections:
               - Context_WriteLine_Silent_DoesNotWriteToConsole
               - IntegrationTest_SilentFlag_SuppressesOutput
 
-          - id: NC-CLI-005
+          - id: NuGetCache-Cmd-Validate
             title: The tool shall support --validate flag to run self-validation tests.
             justification: |
               Provides a built-in mechanism to verify the tool is functioning correctly
@@ -91,7 +91,7 @@ sections:
               - Program_Run_WithValidateFlag_RunsValidation
               - IntegrationTest_ValidateFlag_RunsValidation
 
-          - id: NC-CLI-006
+          - id: NuGetCache-Cmd-Results
             title: The tool shall support --results flag to write validation results in TRX or JUnit format.
             justification: |
               Enables integration with CI/CD systems that expect standard test result formats.
@@ -100,7 +100,7 @@ sections:
               - IntegrationTest_ValidateWithResults_GeneratesTrxFile
               - IntegrationTest_ValidateWithResults_GeneratesJUnitFile
 
-          - id: NC-CLI-007
+          - id: NuGetCache-Cmd-Log
             title: The tool shall support --log flag to write output to a log file.
             justification: |
               Provides persistent logging for debugging and audit trails.
@@ -109,7 +109,7 @@ sections:
               - IntegrationTest_LogFlag_WritesOutputToFile
               - IntegrationTest_LogFlag_WithInvalidFilename_ReturnsError
 
-          - id: NC-CLI-008
+          - id: NuGetCache-Cmd-Cache
             title: The tool shall cache NuGet packages specified as [package-name]:[version] arguments.
             justification: |
               The core purpose of the tool is to ensure NuGet packages are cached in the
@@ -119,7 +119,7 @@ sections:
               - IntegrationTest_CachePackage_OutputsPath
               - NuGetCache_CachePackage
 
-          - id: NC-CLI-009
+          - id: NuGetCache-Cmd-ErrorOutput
             title: The tool shall report errors and return a non-zero exit code on failure.
             justification: |
               Callers (scripts, CI/CD pipelines) must be able to detect failure conditions
@@ -131,7 +131,7 @@ sections:
               - IntegrationTest_UnknownArgument_ReturnsError
               - IntegrationTest_CacheNonexistentPackage_ReturnsError
 
-          - id: NC-CLI-010
+          - id: NuGetCache-Cmd-InvalidArgs
             title: The tool shall reject unknown or malformed command-line arguments with a descriptive error.
             justification: |
               Providing clear feedback for invalid arguments helps users quickly correct
@@ -144,7 +144,7 @@ sections:
 
       - title: Security
         requirements:
-          - id: NC-SEC-001
+          - id: NuGetCache-Sec-PathTraversal
             title: The tool shall prevent path traversal attacks when combining file paths.
             justification: |
               Accepting user-controlled path components without validation could allow
@@ -162,7 +162,7 @@ sections:
 
       - title: Platform Support
         requirements:
-          - id: NC-PLT-001
+          - id: NuGetCache-Platform-Windows
             title: The tool shall build and run on Windows platforms.
             justification: |
               DEMA Consulting tools must support Windows as a major development platform.
@@ -171,7 +171,7 @@ sections:
               - "windows@NuGetCache_VersionDisplay"
               - "windows@NuGetCache_HelpDisplay"
 
-          - id: NC-PLT-002
+          - id: NuGetCache-Platform-Linux
             title: The tool shall build and run on Linux platforms.
             justification: |
               DEMA Consulting tools must support Linux for CI/CD and containerized environments.
@@ -180,7 +180,7 @@ sections:
               - "ubuntu@NuGetCache_VersionDisplay"
               - "ubuntu@NuGetCache_HelpDisplay"
 
-          - id: NC-PLT-006
+          - id: NuGetCache-Platform-MacOS
             title: The tool shall build and run on macOS platforms.
             justification: |
               DEMA Consulting tools must support macOS for developers using Apple platforms.
@@ -189,7 +189,7 @@ sections:
               - "macos@NuGetCache_VersionDisplay"
               - "macos@NuGetCache_HelpDisplay"
 
-          - id: NC-PLT-003
+          - id: NuGetCache-Platform-Net8
             title: The tool shall support .NET 8 runtime.
             justification: |
               .NET 8 is an LTS release providing long-term stability for enterprise users.
@@ -197,7 +197,7 @@ sections:
               - "dotnet8.x@NuGetCache_VersionDisplay"
               - "dotnet8.x@NuGetCache_HelpDisplay"
 
-          - id: NC-PLT-004
+          - id: NuGetCache-Platform-Net9
             title: The tool shall support .NET 9 runtime.
             justification: |
               .NET 9 support enables users to leverage the latest .NET features.
@@ -205,7 +205,7 @@ sections:
               - "dotnet9.x@NuGetCache_VersionDisplay"
               - "dotnet9.x@NuGetCache_HelpDisplay"
 
-          - id: NC-PLT-005
+          - id: NuGetCache-Platform-Net10
             title: The tool shall support .NET 10 runtime.
             justification: |
               .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem.

From df939b0635a5fcab2f4a5130bee1eafdaf3753ca Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 8 Mar 2026 01:14:58 +0000
Subject: [PATCH 4/5] chore: shorten Platform to PLT in requirement IDs

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
---
 requirements.yaml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/requirements.yaml b/requirements.yaml
index e9689c0..87216c2 100644
--- a/requirements.yaml
+++ b/requirements.yaml
@@ -162,7 +162,7 @@ sections:
 
       - title: Platform Support
         requirements:
-          - id: NuGetCache-Platform-Windows
+          - id: NuGetCache-PLT-Windows
             title: The tool shall build and run on Windows platforms.
             justification: |
               DEMA Consulting tools must support Windows as a major development platform.
@@ -171,7 +171,7 @@ sections:
               - "windows@NuGetCache_VersionDisplay"
               - "windows@NuGetCache_HelpDisplay"
 
-          - id: NuGetCache-Platform-Linux
+          - id: NuGetCache-PLT-Linux
             title: The tool shall build and run on Linux platforms.
             justification: |
               DEMA Consulting tools must support Linux for CI/CD and containerized environments.
@@ -180,7 +180,7 @@ sections:
               - "ubuntu@NuGetCache_VersionDisplay"
               - "ubuntu@NuGetCache_HelpDisplay"
 
-          - id: NuGetCache-Platform-MacOS
+          - id: NuGetCache-PLT-MacOS
             title: The tool shall build and run on macOS platforms.
             justification: |
               DEMA Consulting tools must support macOS for developers using Apple platforms.
@@ -189,7 +189,7 @@ sections:
               - "macos@NuGetCache_VersionDisplay"
               - "macos@NuGetCache_HelpDisplay"
 
-          - id: NuGetCache-Platform-Net8
+          - id: NuGetCache-PLT-Net8
             title: The tool shall support .NET 8 runtime.
             justification: |
               .NET 8 is an LTS release providing long-term stability for enterprise users.
@@ -197,7 +197,7 @@ sections:
               - "dotnet8.x@NuGetCache_VersionDisplay"
               - "dotnet8.x@NuGetCache_HelpDisplay"
 
-          - id: NuGetCache-Platform-Net9
+          - id: NuGetCache-PLT-Net9
             title: The tool shall support .NET 9 runtime.
             justification: |
               .NET 9 support enables users to leverage the latest .NET features.
@@ -205,7 +205,7 @@ sections:
               - "dotnet9.x@NuGetCache_VersionDisplay"
               - "dotnet9.x@NuGetCache_HelpDisplay"
 
-          - id: NuGetCache-Platform-Net10
+          - id: NuGetCache-PLT-Net10
             title: The tool shall support .NET 10 runtime.
             justification: |
               .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem.

From 81e25984d678641ff3ac1baa8e6107260ee1a1ac Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.nixon@gmail.com>
Date: Sat, 7 Mar 2026 20:22:24 -0500
Subject: [PATCH 5/5] Update .github/workflows/build.yaml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .github/workflows/build.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index ce26736..8090fdf 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -191,6 +191,7 @@ jobs:
           dotnet pack
           --no-build
           --no-restore
+          --configuration Release
           --property:PackageVersion=${{ inputs.version }}
 
       # === UPLOAD ARTIFACTS ===