Apply TemplateDotNetTool template updates: staged pipelines, artifact consolidation, semantic requirement IDs, and OTS Software requirements

.github/workflows/build.yaml

@@ -19,6 +19,10 @@ jobs:
       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
 
@@ -34,15 +38,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
@@ -60,6 +72,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.
@@ -78,6 +96,10 @@ jobs:
 
     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
 
@@ -93,6 +115,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-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}" \
+            --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
@@ -119,9 +169,9 @@ jobs:
           dotnet test
           --no-build
           --configuration Release
-          --verbosity normal
           --collect "XPlat Code Coverage;Format=opencover"
-          --logger "trx;LogFileName=test-results-${{ matrix.os }}.trx"
+          --logger "trx;LogFilePrefix=${{ matrix.os }}"
+          --results-directory artifacts
 
       - name: End Sonar Scanner
         run: >
@@ -135,32 +185,17 @@ jobs:
           --configuration Release
           --property:Version=${{ 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
-        if: always()
+      - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:
-          name: test-results-${{ matrix.os }}
-          path: |
-            test/**/TestResults/*.trx
+          name: artifacts-build-${{ matrix.os }}
+          path: artifacts/
 
-      - name: Upload Artifacts
+      - name: Upload packages
         uses: actions/upload-artifact@v7
         with:
           name: packages-${{ matrix.os }}
@@ -180,6 +215,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:
@@ -209,6 +248,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
@@ -220,14 +263,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
@@ -245,6 +292,10 @@ jobs:
         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:
@@ -276,6 +327,28 @@ jobs:
             --version ${{ inputs.version }} \
             DemaConsulting.ReqStream
 
+      # === 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-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}" \
+            --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: |
@@ -295,33 +368,20 @@ jobs:
         run: |
           echo "Running self-validation..."
           reqstream --validate \
-            --results integration-test-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx \
+            --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: integration-test-results-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
-          path: integration-test-*.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.
@@ -340,32 +400,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 ReqStream package
+      - name: Download packages artifact
         uses: actions/download-artifact@v8
         with:
-          name: packages-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.
@@ -402,11 +450,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: 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.
@@ -415,7 +484,7 @@ jobs:
         run: >
           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
@@ -425,7 +494,7 @@ jobs:
         shell: bash
         run: >
           dotnet sarifmark
-          --sarif codeql-results/csharp.sarif
+          --sarif artifacts/csharp.sarif
           --report docs/quality/codeql-quality.md
           --heading "ReqStream CodeQL Analysis"
           --report-depth 1
@@ -476,7 +545,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

AGENTS.md

@@ -19,7 +19,7 @@ written in YAML files.
 ## 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

CONTRIBUTING.md

@@ -80,7 +80,7 @@ This project follows the coding standards defined in `.editorconfig`. Key conven
 
 - **Indentation**: 4 spaces for C#, 2 spaces for YAML/JSON/XML
 - **Line endings**: LF (Unix-style)
-- **Encoding**: UTF-8 with BOM
+- **Encoding**: UTF-8
 - **Braces**: Required for all control statements
 - **Naming**:
   - Interfaces: `IRequirementParser`