Bring in recent changes from the template repo

.github/workflows/build.yaml

@@ -18,10 +18,20 @@ jobs:
     permissions:
       contents: read
     steps:
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies for quality checks.
+      # Downstream projects: Add any additional dependency installations here.
+      # Note: VersionMark version capture is not available here because this job
+      # builds VersionMark itself - capture is performed in integration-test and
+      # build-docs jobs after the tool is built and installed.
+
       - name: Checkout
         uses: actions/checkout@v6
 
       # === 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
         with:
@@ -50,13 +60,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:
@@ -74,11 +87,17 @@ jobs:
         run: >
           dotnet tool restore
 
+      # === BUILD AND TEST ===
+      # This section builds and tests the project.
+      # Note: VersionMark version capture is not available here because this job
+      # builds VersionMark itself - capture is performed in integration-test and
+      # build-docs jobs after the tool is built and installed.
+      # Downstream projects: Add any additional build and test steps here.
+
       - name: Restore Dependencies
         run: >
           dotnet restore
 
-      # === BUILD AND TEST ===
       - name: Start Sonar Scanner
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -125,6 +144,9 @@ jobs:
           --property:PackageVersion=${{ inputs.version }}
 
       # === UPLOAD ARTIFACTS ===
+      # This section uploads all build artifacts.
+      # Downstream projects: Add any additional artifact uploads here.
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:
@@ -152,6 +174,9 @@ jobs:
 
     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:
@@ -161,6 +186,7 @@ jobs:
         uses: github/codeql-action/init@v4
         with:
           languages: csharp
+          build-mode: manual
           queries: security-and-quality
           config-file: ./.github/codeql-config.yml
 
@@ -181,6 +207,9 @@ jobs:
           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
@@ -196,6 +225,9 @@ jobs:
           upload: false
 
       # === 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:
@@ -214,11 +246,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:
@@ -237,6 +272,10 @@ jobs:
         with:
           dotnet-version: ${{ matrix.dotnet-version }}
 
+      - name: Restore Tools
+        run: >
+          dotnet tool restore
+
       - name: Install tool from package
         shell: bash
         run: |
@@ -247,20 +286,26 @@ jobs:
             DemaConsulting.VersionMark
 
       # === 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: |
-          echo "Capturing tool versions..."
           mkdir -p artifacts
-          # 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/')
+          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}"
           versionmark --capture --job-id "${JOB_ID}" \
             --output "artifacts/versionmark-${JOB_ID}.json" -- dotnet git
           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: |
@@ -286,6 +331,9 @@ jobs:
           echo "✓ Self-validation succeeded"
 
       # === UPLOAD ARTIFACTS ===
+      # This section uploads all generated artifacts for use by downstream jobs.
+      # Downstream projects: Add any additional artifact uploads here.
+
       - name: Upload validation artifacts
         if: always()
         uses: actions/upload-artifact@v7
@@ -304,14 +352,12 @@ jobs:
 
     steps:
       # === CHECKOUT AND DOWNLOAD ARTIFACTS ===
+      # This section retrieves the code and all necessary artifacts from previous jobs.
+      # Downstream projects: Add any additional artifact downloads here.
+
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 'lts/*'
-
       - name: Download all job artifacts
         uses: actions/download-artifact@v8
         with:
@@ -327,6 +373,14 @@ jobs:
           path: packages
 
       # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies and tools for document generation.
+      # Downstream projects: Add any additional dependency installations here.
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 'lts/*'
+
       - name: Setup dotnet
         uses: actions/setup-dotnet@v5
         with:
@@ -348,6 +402,9 @@ 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 for build-docs
         shell: bash
         run: |
@@ -359,6 +416,9 @@ jobs:
           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
 
@@ -375,6 +435,9 @@ jobs:
         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.
+
       - name: Generate Requirements Report, Justifications, and Trace Matrix
         run: >
           dotnet reqstream
@@ -449,6 +512,9 @@ jobs:
           cat docs/buildnotes/versions.md
 
       # === GENERATE HTML DOCUMENTS WITH PANDOC ===
+      # This section converts markdown documents to HTML using Pandoc.
+      # Downstream projects: Add any additional Pandoc HTML generation steps here.
+
       - name: Generate Build Notes HTML with Pandoc
         shell: bash
         run: >
@@ -460,6 +526,9 @@ jobs:
           --output docs/buildnotes/buildnotes.html
 
       # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
+      # This section converts HTML documents to PDF using Weasyprint.
+      # Downstream projects: Add any additional Weasyprint PDF generation steps here.
+
       - name: Generate Build Notes PDF with Weasyprint
         run: >
           dotnet weasyprint
@@ -553,6 +622,9 @@ jobs:
           "docs/VersionMark Trace Matrix.pdf"
 
       # === UPLOAD ARTIFACTS ===
+      # This section uploads all generated documentation artifacts.
+      # Downstream projects: Add any additional artifact uploads here.
+
       - name: Upload documentation
         uses: actions/upload-artifact@v7
         with:

.gitignore

@@ -78,8 +78,8 @@ artifacts/
 
 # Node.js
 node_modules/
-npm-debug.log
 package-lock.json
+npm-debug.log
 
 # Python
 __pycache__/
@@ -111,4 +111,6 @@ coverage.opencover.xml
 
 # Agent report files
 AGENT_REPORT_*.md
+
+# VersionMark captures (generated during CI/CD)
 versionmark-*.json

AGENTS.md

@@ -12,6 +12,18 @@ publishing tool version information across CI/CD environments.
 - **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
@@ -50,6 +62,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
@@ -116,9 +129,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

README.md

@@ -21,8 +21,10 @@ used in different jobs and environments.
 - **Version Consolidation**: Collapses common versions across jobs while highlighting conflicts
 - **OS-Specific Overrides**: Supports platform-specific version capture commands
 - **Configurable**: Uses `.versionmark.yaml` config file to define tools and capture methods
-- **Multi-Platform Support**: Runs on Windows and Linux
+- **Multi-Platform Support**: Runs on Windows, Linux, and macOS
 - **Multi-Runtime Support**: Targets .NET 8, 9, and 10
+- **Continuous Compliance**: Compliance evidence generated automatically on every CI run, following
+  the [Continuous Compliance][link-continuous-compliance] methodology
 
 ## Installation
 
@@ -269,3 +271,4 @@ By contributing to this project, you agree that your contributions will be licen
 [link-quality]: https://sonarcloud.io/dashboard?id=demaconsulting_VersionMark
 [link-security]: https://sonarcloud.io/dashboard?id=demaconsulting_VersionMark
 [link-nuget]: https://www.nuget.org/packages/DemaConsulting.VersionMark
+[link-continuous-compliance]: https://github.com/demaconsulting/ContinuousCompliance

docs/guide/guide.md

@@ -21,6 +21,20 @@ This user guide covers:
 - Configuration file format and options
 - Troubleshooting and best practices
 
+# Continuous Compliance
+
+VersionMark follows the [Continuous Compliance][continuous-compliance] methodology, which ensures
+compliance evidence is generated automatically on every CI run.
+
+## Key Practices
+
+- **Requirements Traceability**: Every requirement is linked to passing tests, and a trace matrix is
+  auto-generated on each release
+- **Linting Enforcement**: markdownlint, cspell, and yamllint are enforced before any build proceeds
+- **Automated Audit Documentation**: Each release ships with generated requirements, justifications,
+  trace matrix, and quality reports
+- **CodeQL and SonarCloud**: Security and quality analysis runs on every build
+
 # Installation
 
 Install the tool globally using the .NET CLI:
@@ -572,3 +586,6 @@ works well)
 publishing
 10. **Review Generated Reports**: Check the generated markdown to ensure version information
 is accurate
+
+<!-- Link References -->
+[continuous-compliance]: https://github.com/demaconsulting/ContinuousCompliance

test/DemaConsulting.VersionMark.Tests/DemaConsulting.VersionMark.Tests.csproj

@@ -1,17 +1,20 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
+    <!-- Build Configuration -->
     <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
     <LangVersion>latest</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
-    <EnableNETAnalyzers>true</EnableNETAnalyzers>
-    <AnalysisLevel>latest</AnalysisLevel>
 
     <IsPackable>false</IsPackable>
     <IsTestProject>true</IsTestProject>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
+
+    <!-- Code Quality Configuration -->
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <EnableNETAnalyzers>true</EnableNETAnalyzers>
+    <AnalysisLevel>latest</AnalysisLevel>
   </PropertyGroup>
 
   <!-- Implicit Usings -->
@@ -51,6 +54,7 @@
     </PackageReference>
   </ItemGroup>
 
+  <!-- Project References -->
   <ItemGroup>
     <ProjectReference Include="..\..\src\DemaConsulting.VersionMark\DemaConsulting.VersionMark.csproj" />
   </ItemGroup>