Documentation review: Fix requirements traceability and standardize linting commands

.github/pull_request_template.md

@@ -36,13 +36,11 @@ Before submitting this pull request, ensure you have completed the following:
 - [ ] New code has appropriate XML documentation comments
 - [ ] Static analyzer warnings have been addressed
 
-### Quality Checks
+### Linting
 
-Please run the following checks before submitting:
-
-- [ ] **Spell checker passes**: `cspell "**/*.{md,cs}"`
-- [ ] **Markdown linter passes**: `markdownlint "**/*.md"`
-- [ ] **YAML linter passes**: `yamllint '**/*.{yml,yaml}'`
+- [ ] Markdown linter passes: `npx markdownlint-cli2 "**/*.md" "#node_modules"`
+- [ ] Spell checker passes: `npx cspell "**/*.{md,cs}" --no-progress`
+- [ ] YAML linter passes: `yamllint .`
 
 ### Testing
 

.vscode/tasks.json

@@ -161,6 +161,53 @@
         "reveal": "always",
         "panel": "shared"
       }
+    },
+    {
+      "label": "check dependencies",
+      "command": "dotnet",
+      "type": "shell",
+      "args": [
+        "list",
+        "package",
+        "--outdated"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared"
+      }
+    },
+    {
+      "label": "check vulnerabilities",
+      "command": "dotnet",
+      "type": "shell",
+      "args": [
+        "list",
+        "package",
+        "--vulnerable",
+        "--include-transitive"
+      ],
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared"
+      }
+    },
+    {
+      "label": "maintenance check",
+      "dependsOn": [
+        "check dependencies",
+        "check vulnerabilities",
+        "lint all",
+        "build and test",
+        "verify requirements"
+      ],
+      "dependsOrder": "sequence",
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared"
+      }
     }
   ]
 }

CONTRIBUTING.md

@@ -200,13 +200,24 @@ All tests must pass with zero warnings.
 
 ### 2. Linting
 
+Run all linters to ensure code quality and consistency:
+
 ```bash
-# These commands run in CI - verify locally if tools are installed
-markdownlint-cli2 "**/*.md"
-cspell "**/*.{md,cs}"
-yamllint -c .yamllint.yaml .
+# Markdown linting
+npx markdownlint-cli2 "**/*.md" "#node_modules"
+
+# Spell checking
+npx cspell "**/*.{md,cs}" --no-progress
+
+# YAML linting
+yamllint .
+
+# Code formatting
+dotnet format --verify-no-changes
 ```
 
+All linters must pass with no errors or warnings.
+
 ### 3. Code Coverage
 
 Maintain or improve code coverage. Use the `--collect "XPlat Code Coverage"` option when running tests.

docs/tracematrix/introduction.md

@@ -7,6 +7,29 @@ This document contains the requirements trace matrix for the SonarMark project.
 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 SonarMark 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 `sonarmark --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
+sonarmark --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:

requirements.yaml

@@ -151,28 +151,34 @@ sections:
         requirements:
           - id: "PLT-001"
             title: "The tool shall run on Windows operating systems."
+            # Test source pattern "windows@" ensures these tests ran on Windows.
+            # This filtering is necessary to prove Windows OS functionality.
             tests:
-              - "windows-latest@IntegrationTest_VersionFlag_OutputsVersion"
-              - "windows-latest@IntegrationTest_HelpFlag_OutputsUsageInformation"
-              - "windows-latest@IntegrationTest_ReportParameter_IsAccepted"
-              - "windows-latest@SonarMark_QualityGateRetrieval"
-              - "windows-latest@SonarMark_IssuesRetrieval"
-              - "windows-latest@SonarMark_HotSpotsRetrieval"
-              - "windows-latest@SonarMark_MarkdownReportGeneration"
+              - "windows@IntegrationTest_VersionFlag_OutputsVersion"
+              - "windows@IntegrationTest_HelpFlag_OutputsUsageInformation"
+              - "windows@IntegrationTest_ReportParameter_IsAccepted"
+              - "windows@SonarMark_QualityGateRetrieval"
+              - "windows@SonarMark_IssuesRetrieval"
+              - "windows@SonarMark_HotSpotsRetrieval"
+              - "windows@SonarMark_MarkdownReportGeneration"
 
           - id: "PLT-002"
             title: "The tool shall run on Linux operating systems."
+            # Test source pattern "ubuntu@" ensures these tests ran on Linux.
+            # This filtering is necessary to prove Linux OS functionality.
             tests:
-              - "ubuntu-latest@IntegrationTest_VersionFlag_OutputsVersion"
-              - "ubuntu-latest@IntegrationTest_HelpFlag_OutputsUsageInformation"
-              - "ubuntu-latest@IntegrationTest_ReportParameter_IsAccepted"
-              - "ubuntu-latest@SonarMark_QualityGateRetrieval"
-              - "ubuntu-latest@SonarMark_IssuesRetrieval"
-              - "ubuntu-latest@SonarMark_HotSpotsRetrieval"
-              - "ubuntu-latest@SonarMark_MarkdownReportGeneration"
+              - "ubuntu@IntegrationTest_VersionFlag_OutputsVersion"
+              - "ubuntu@IntegrationTest_HelpFlag_OutputsUsageInformation"
+              - "ubuntu@IntegrationTest_ReportParameter_IsAccepted"
+              - "ubuntu@SonarMark_QualityGateRetrieval"
+              - "ubuntu@SonarMark_IssuesRetrieval"
+              - "ubuntu@SonarMark_HotSpotsRetrieval"
+              - "ubuntu@SonarMark_MarkdownReportGeneration"
 
           - id: "PLT-003"
             title: "The tool shall support .NET 8.0 runtime."
+            # Test source pattern "dotnet8.x@" ensures these tests ran on .NET 8.0.
+            # This filtering is necessary to prove .NET 8.0 runtime support.
             tests:
               - "dotnet8.x@SonarMark_QualityGateRetrieval"
               - "dotnet8.x@SonarMark_IssuesRetrieval"
@@ -181,6 +187,8 @@ sections:
 
           - id: "PLT-004"
             title: "The tool shall support .NET 9.0 runtime."
+            # Test source pattern "dotnet9.x@" ensures these tests ran on .NET 9.0.
+            # This filtering is necessary to prove .NET 9.0 runtime support.
             tests:
               - "dotnet9.x@SonarMark_QualityGateRetrieval"
               - "dotnet9.x@SonarMark_IssuesRetrieval"
@@ -189,6 +197,8 @@ sections:
 
           - id: "PLT-005"
             title: "The tool shall support .NET 10.0 runtime."
+            # Test source pattern "dotnet10.x@" ensures these tests ran on .NET 10.0.
+            # This filtering is necessary to prove .NET 10.0 runtime support.
             tests:
               - "dotnet10.x@SonarMark_QualityGateRetrieval"
               - "dotnet10.x@SonarMark_IssuesRetrieval"