Add Requirements Management with ReqStream

.cspell.json

@@ -25,6 +25,7 @@
     "opencover",
     "reqstream",
     "snupkg",
+    "tracematrix",
     "trx",
     "yamllint"
   ],

.github/workflows/build.yaml

@@ -234,6 +234,21 @@ jobs:
           buildmark --help || { echo "✗ Help command failed"; exit 1; }
           echo "✓ Help command succeeded"
 
+      - name: Run BuildMark self-validation
+        shell: bash
+        run: |
+          echo "Running BuildMark self-validation..."
+          buildmark --validate --results validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx \
+            || { echo "✗ Self-validation failed"; exit 1; }
+          echo "✓ Self-validation succeeded"
+
+      - name: Upload validation test results
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: validation-test-results-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
+          path: validation-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx
+
   build-docs:
     name: Build Documents
     runs-on: windows-latest
@@ -278,19 +293,28 @@ jobs:
       - name: Install npm dependencies
         run: npm install
 
-      - name: Download All Test Results
+      - name: Download all test results
         uses: actions/download-artifact@v7
         with:
-          pattern: test-results-*
           path: test-results
-          merge-multiple: true
+          pattern: '*test-results*'
+        continue-on-error: true
 
       - name: Download CodeQL SARIF
         uses: actions/download-artifact@v7
         with:
           name: codeql-sarif
           path: codeql-results
 
+      - name: Generate Requirements Report and Trace Matrix
+        run: >
+          dotnet reqstream
+          --requirements requirements.yaml
+          --tests "test-results/**/*.trx"
+          --report docs/requirements/requirements.md
+          --matrix docs/tracematrix/tracematrix.md
+          --enforce
+
       - name: Generate CodeQL Quality Report with SarifMark
         run: >
           dotnet sarifmark
@@ -355,6 +379,38 @@ jobs:
           docs/buildnotes/buildnotes.html
           "docs/BuildMark Build Notes.pdf"
 
+      - name: Generate Requirements HTML with Pandoc
+        shell: bash
+        run: >
+          dotnet pandoc
+          --defaults docs/requirements/definition.yaml
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --output docs/requirements/requirements.html
+
+      - name: Generate Requirements PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          docs/requirements/requirements.html
+          "docs/BuildMark Requirements.pdf"
+
+      - name: Generate Trace Matrix HTML with Pandoc
+        shell: bash
+        run: >
+          dotnet pandoc
+          --defaults docs/tracematrix/definition.yaml
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --output docs/tracematrix/tracematrix.html
+
+      - name: Generate Trace Matrix PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          docs/tracematrix/tracematrix.html
+          "docs/BuildMark Trace Matrix.pdf"
+
       - name: Generate Code Quality HTML with Pandoc
         shell: bash
         run: >

docs/requirements/definition.yaml

@@ -0,0 +1,11 @@
+---
+resource-path:
+  - docs/requirements
+  - docs/template
+input-files:
+  - docs/requirements/title.txt
+  - docs/requirements/introduction.md
+  - docs/requirements/requirements.md
+template: template.html
+table-of-contents: true
+number-sections: true

docs/requirements/introduction.md

@@ -0,0 +1,31 @@
+# Introduction
+
+This document contains the requirements for the BuildMark project.
+
+## Purpose
+
+BuildMark is a .NET command-line tool that generates comprehensive markdown build notes reports from
+Git repository history and GitHub issues. It analyzes commits, pull requests, and issues to create
+human-readable build notes, making it easy to integrate release documentation into CI/CD pipelines
+and documentation workflows.
+
+## Scope
+
+This requirements document covers:
+
+- Command-line interface and options
+- Git repository integration
+- GitHub integration for issues and pull requests
+- Markdown report generation capabilities
+- Validation and self-testing features
+- Data models and repository connectors
+- Platform support for Windows, Linux, and multiple .NET runtimes
+
+## Audience
+
+This document is intended for:
+
+- Software developers working on BuildMark
+- Quality assurance teams validating requirements
+- Project stakeholders reviewing project scope
+- Users understanding the tool's capabilities

docs/requirements/title.txt

@@ -0,0 +1,17 @@
+---
+title: BuildMark Requirements
+subtitle: Requirements Specification for the BuildMark Tool
+author: DEMA Consulting
+description: Requirements Specification for the BuildMark Tool
+lang: en-US
+keywords:
+  - BuildMark
+  - Requirements
+  - Specification
+  - .NET
+  - YAML
+  - Command-Line Tool
+  - Git
+  - GitHub
+  - Markdown
+---

docs/tracematrix/definition.yaml

@@ -0,0 +1,11 @@
+---
+resource-path:
+  - docs/tracematrix
+  - docs/template
+input-files:
+  - docs/tracematrix/title.txt
+  - docs/tracematrix/introduction.md
+  - docs/tracematrix/tracematrix.md
+template: template.html
+table-of-contents: true
+number-sections: true

docs/tracematrix/introduction.md

@@ -0,0 +1,48 @@
+# Introduction
+
+This document contains the requirements trace matrix for the BuildMark project.
+
+## Purpose
+
+The trace matrix links requirements to their corresponding test cases, ensuring complete
+test coverage and traceability from requirements to implementation.
+
+## Test Sources
+
+Requirements traceability in BuildMark uses two types of tests:
+
+- **Unit and Integration Tests**: Standard MSTest tests that verify code functionality
+- **Self-Validation Tests**: Built-in validation tests run via `buildmark --validate --results`
+
+To generate complete traceability reports, both test result files must be included:
+
+```bash
+# Run unit and integration tests
+dotnet test --configuration Release --results-directory test-results --logger "trx"
+
+# Run validation tests
+buildmark --validate --results validation.trx
+
+# Verify requirements traceability
+dotnet reqstream --requirements requirements.yaml \
+  --tests "test-results/**/*.trx" \
+  --tests validation.trx \
+  --enforce
+```
+
+## Interpretation
+
+The trace matrix shows:
+
+- **Requirement ID**: Unique identifier for each requirement
+- **Requirement Title**: Brief description of the requirement
+- **Test Coverage**: List of test cases that verify the requirement
+- **Status**: Indication of whether all mapped tests pass
+
+## Coverage Requirements
+
+All requirements must have:
+
+- At least one test case mapped to verify the requirement
+- All mapped tests must pass for the requirement to be satisfied
+- Tests must execute on supported platforms and .NET runtimes

docs/tracematrix/title.txt

@@ -0,0 +1,14 @@
+---
+title: BuildMark Trace Matrix
+subtitle: Test Traceability Matrix for the BuildMark Tool
+author: DEMA Consulting
+description: Test Traceability Matrix for the BuildMark Tool
+lang: en-US
+keywords:
+  - BuildMark
+  - Trace Matrix
+  - Traceability
+  - Testing
+  - .NET
+  - Command-Line Tool
+---