Repository consistency and test strategy documentation improvements

.cspell.json

@@ -82,6 +82,7 @@
     "*.trx",
     "*.spdx.json",
     "package-lock.json",
-    "yarn.lock"
+    "yarn.lock",
+    "AGENT_REPORT_*.md"
   ]
 }

.github/workflows/build.yaml

@@ -10,6 +10,7 @@ on:
         required: true
 
 jobs:
+  # Run linting checks (markdown, spelling, YAML) to ensure code quality standards
   quality-checks:
     name: Quality Checks
     runs-on: ubuntu-latest
@@ -35,6 +36,7 @@ jobs:
         with:
           config_file: .yamllint.yaml
 
+  # Build and test on multiple operating systems with SonarCloud analysis
   build:
     name: Build ${{ matrix.os }}
     needs: quality-checks
@@ -130,6 +132,7 @@ jobs:
             src/DemaConsulting.SonarMark/bin/Release/*.nupkg
             src/DemaConsulting.SonarMark/bin/Release/*.snupkg
 
+  # Perform security analysis using CodeQL
   codeql:
     name: CodeQL Analysis
     runs-on: ubuntu-latest
@@ -184,6 +187,7 @@ jobs:
           name: codeql-sarif
           path: sarif-results/csharp.sarif
 
+  # Test the packaged tool on multiple OS and .NET versions
   integration-test:
     name: Integration Test ${{ matrix.os }} .NET ${{ matrix.dotnet-version }}
     runs-on: ${{ matrix.os }}
@@ -272,6 +276,7 @@ jobs:
           name: integration-test-results-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}
           path: integration-test-${{ matrix.os }}-dotnet${{ matrix.dotnet-version }}.trx
 
+  # Generate all documentation including requirements, trace matrix, and build notes
   build-docs:
     name: Build Documentation
     runs-on: windows-latest

.markdownlint-cli2.jsonc

@@ -11,6 +11,6 @@
   // Ignore patterns
   "ignores": [
     "node_modules",
-    "AGENT_REPORT_*.md"
+    "**/AGENT_REPORT_*.md"
   ]
 }

CONTRIBUTING.md

@@ -161,6 +161,46 @@ dotnet test --filter "FullyQualifiedName~YourTestName"
 dotnet test --collect "XPlat Code Coverage"
 ```
 
+### Test Execution Strategy
+
+SonarMark uses a multi-stage test execution strategy to validate functionality across different contexts:
+
+#### Local Testing (Unit Tests)
+
+Unit tests run locally and provide rapid feedback during development:
+
+- **Scope**: Core functionality, argument parsing, report generation logic
+- **Execution**: `dotnet test --configuration Release`
+- **Requirements Coverage**: Validates most requirements locally
+
+#### CI Integration Testing (Self-Validation Tests)
+
+Self-validation tests execute in CI and validate the complete packaged tool:
+
+- **Scope**: End-to-end validation against real SonarCloud APIs
+- **Execution**: Runs via `sonarmark --validate` in the integration-test job
+- **Requirements Coverage**: Validates requirements SONAR-003, SONAR-004, SONAR-005, RPT-001, VAL-001
+
+#### CI Platform Testing (Matrix Tests)
+
+Platform-specific tests execute across multiple OS and .NET runtime combinations:
+
+- **Scope**: Windows/Linux compatibility, .NET 8/9/10 support
+- **Execution**: Runs in the integration-test job matrix
+- **Requirements Coverage**: Validates requirements PLT-001 through PLT-005
+
+#### Requirements Traceability
+
+Full requirements traceability is validated in CI using ReqStream:
+
+```bash
+dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce
+```
+
+**Note**: When running `dotnet reqstream --enforce` locally, you may see some unsatisfied requirements. This is expected
+because self-validation and platform-specific tests only execute in the CI pipeline. Full validation requires the
+complete CI workflow.
+
 ## Documentation
 
 ### Markdown Guidelines

requirements.yaml

@@ -1,4 +1,16 @@
 ---
+# SonarMark Requirements
+#
+# Test Execution Strategy:
+# This file links requirements to tests across multiple execution contexts:
+# - Unit tests: Run locally via 'dotnet test' (validates most requirements)
+# - Self-validation tests: Run via 'sonarmark --validate' in CI integration-test job
+#   (validates SONAR-003, SONAR-004, SONAR-005, RPT-001, VAL-001)
+# - Platform tests: Run across OS/runtime matrix in CI integration-test job
+#   (validates PLT-001 through PLT-005)
+#
+# Note: Running 'dotnet reqstream --enforce' locally will show some unsatisfied requirements.
+# This is expected - full validation requires the complete CI pipeline.
 sections:
   - title: SonarMark Requirements
     sections: