demaconsulting · Malcolmnixon · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026
diff --git a/.github/agents/repo-consistency-agent.md b/.github/agents/repo-consistency-agent.md
@@ -81,6 +81,33 @@ The agent reviews the following areas for consistency with the TemplateDotNetToo
   - `quality/` (auto-generated)
 - **Definition Files**: `definition.yaml` files for document generation
 
+### Tracking Template Evolution
+
+To ensure SarifMark benefits from recent template improvements, review recent pull requests merged into
+the template repository:
+
+1. **List Recent PRs**: Retrieve recently merged PRs from `demaconsulting/TemplateDotNetTool`
+   - Review the last 10-20 PRs to identify template improvements
+
+2. **Identify Propagatable Changes**: For each PR, determine if changes should apply to SarifMark:
+   - Focus on structural changes (workflows, agents, configurations) over content-specific changes
+   - Note changes to `.github/`, linting configurations, project patterns, and documentation
+     structure
+
+3. **Check Downstream Application**: Verify if identified changes exist in SarifMark:
+   - Check if similar files/patterns exist in SarifMark
+   - Compare file contents between template and SarifMark
+   - Look for similar PR titles or commit messages in SarifMark repository history
+
+4. **Recommend Missing Updates**: For changes not yet applied, include them in the consistency
+   review with:
+   - Description of the template change (reference PR number)
+   - Explanation of benefits for SarifMark
+   - Specific files or patterns that need updating
+
+This technique ensures SarifMark doesn't miss important template improvements and helps maintain
+long-term consistency.
+
 ### Review Process
 
 1. **Identify Differences**: Compare SarifMark repository structure with TemplateDotNetTool template

diff --git a/AGENTS.md b/AGENTS.md
@@ -13,12 +13,12 @@ Project-specific guidance for agents working on SarifMark - a .NET CLI tool for
 
 ## Tech Stack
 
-- C# 12, .NET 8.0/9.0/10.0, MSTest, dotnet CLI, NuGet
+- C# (latest), .NET 8.0/9.0/10.0, MSTest, dotnet CLI, NuGet
 
 ## 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 (SarifMark-Specific)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -95,7 +95,7 @@ This project enforces code style through `.editorconfig`. Key requirements:
 
 - **Indentation**: 4 spaces for C#, 2 spaces for YAML/JSON/XML
 - **Line Endings**: LF (Unix-style)
-- **Encoding**: UTF-8 with BOM
+- **Encoding**: UTF-8
 - **Namespaces**: Use file-scoped namespace declarations
 - **Braces**: Required for all control statements
 - **Naming Conventions**:
@@ -142,7 +142,7 @@ Examples:
 
 - Write tests that are clear and focused
 - Use modern MSTest v4 assertions:
-  - `Assert.HasCount(collection, expectedCount)`
+  - `Assert.HasCount(expectedCount, collection)`
   - `Assert.IsEmpty(collection)`
   - `Assert.DoesNotContain(item, collection)`
 - Always clean up resources (use `try/finally` for console redirection)

diff --git a/README.md b/README.md
@@ -195,6 +195,41 @@ src/Program.cs(42): warning [TEST001] Test issue 1
 src/Helper.cs(15): error [TEST002] Test issue 2
 ```
 
+## Self Validation
+
+Running self-validation produces a report containing the following information:
+
+```text
+# DEMA Consulting SarifMark
+
+| Information         | Value                                              |
+| :------------------ | :------------------------------------------------- |
+| SarifMark Version   | <version>                                          |
+| Machine Name        | <machine-name>                                     |
+| OS Version          | <os-version>                                       |
+| DotNet Runtime      | <dotnet-runtime-version>                           |
+| Time Stamp          | <timestamp> UTC                                    |
+
+✓ SarifMark_SarifReading - Passed
+✓ SarifMark_MarkdownReportGeneration - Passed
+✓ SarifMark_Enforcement - Passed
+
+Total Tests: 3
+Passed: 3
+Failed: 0
+```
+
+Each test in the report proves:
+
+- **`SarifMark_SarifReading`** - SARIF file reading and parsing works correctly.
+- **`SarifMark_MarkdownReportGeneration`** - Markdown report generation from SARIF data works correctly.
+- **`SarifMark_Enforcement`** - Enforcement mode returns a non-zero exit code when issues are found.
+
+See the [Usage Guide](https://github.com/demaconsulting/SarifMark/blob/main/docs/guide/guide.md) for more details
+on the self-validation tests.
+
+On validation failure the tool will exit with a non-zero exit code.
+
 ## Contributing
 
 Contributions are welcome! We appreciate your interest in improving SarifMark.
@@ -210,6 +245,8 @@ For bug reports, feature requests, and questions, please use [GitHub Issues](htt
 This project is licensed under the MIT License - see the [LICENSE](https://github.com/demaconsulting/SarifMark/blob/main/LICENSE)
 file for details.
 
+By contributing to this project, you agree that your contributions will be licensed under the MIT License.
+
 ## Support
 
 - 🐛 **Report Bugs**: [GitHub Issues](https://github.com/demaconsulting/SarifMark/issues)

diff --git a/docs/guide/guide.md b/docs/guide/guide.md
@@ -166,20 +166,63 @@ sarifmark --sarif analysis.sarif --report report.md --enforce
 
 The command will exit with a non-zero exit code if the SARIF file contains any issues.
 
-## Run Self-Validation
+## Self-Validation
 
-Run the built-in validation tests:
+Self-validation produces a report demonstrating that SarifMark is functioning correctly. This is useful in
+regulated industries where tool validation evidence is required.
+
+### Running Validation
+
+To perform self-validation:
 
 ```bash
 sarifmark --validate
 ```
 
-Generate a test results file:
+To save validation results to a file:
 
 ```bash
 sarifmark --validate --results validation-results.trx
 ```
 
+The results file format is determined by the file extension: `.trx` for TRX (MSTest) format,
+or `.xml` for JUnit format.
+
+### Validation Report
+
+The validation report contains the tool version, machine name, operating system version,
+.NET runtime version, timestamp, and test results.
+
+Example validation report:
+
+```text
+# DEMA Consulting SarifMark
+
+| Information         | Value                                              |
+| :------------------ | :------------------------------------------------- |
+| SarifMark Version   | 1.0.0                                              |
+| Machine Name        | BUILD-SERVER                                       |
+| OS Version          | Ubuntu 22.04.3 LTS                                 |
+| DotNet Runtime      | .NET 10.0.0                                        |
+| Time Stamp          | 2024-01-15 10:30:00 UTC                            |
+
+✓ SarifMark_SarifReading - Passed
+✓ SarifMark_MarkdownReportGeneration - Passed
+✓ SarifMark_Enforcement - Passed
+
+Total Tests: 3
+Passed: 3
+Failed: 0
+```
+
+### Validation Tests
+
+Each test proves specific functionality works correctly:
+
+- **`SarifMark_SarifReading`** - SARIF file reading and parsing works correctly.
+- **`SarifMark_MarkdownReportGeneration`** - Markdown report generation from SARIF data works correctly.
+- **`SarifMark_Enforcement`** - Enforcement mode returns a non-zero exit code when issues are found.
+
 ## Silent Mode with Log File
 
 Suppress console output while saving to a log file: