Apply template consistency updates from TemplateDotNetTool

.github/workflows/build.yaml

@@ -21,6 +21,27 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.x
+
+      - name: Restore Tools
+        run: dotnet tool restore
+
+      - name: Capture tool versions
+        shell: bash
+        run: |
+          echo "Capturing tool versions..."
+          dotnet versionmark --capture --job-id "quality" -- dotnet git versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Upload version capture
+        uses: actions/upload-artifact@v7
+        with:
+          name: version-capture-quality
+          path: versionmark-quality.json
+
       - name: Run markdown linter
         uses: DavidAnson/markdownlint-cli2-action@v22
         with:
@@ -213,6 +234,10 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            .versionmark.yaml
+            .config/dotnet-tools.json
 
       - name: Download package
         uses: actions/download-artifact@v8
@@ -405,6 +430,12 @@ jobs:
           --report docs/buildnotes.md
           --report-depth 1
 
+      - name: Display Build Notes Report
+        shell: bash
+        run: |
+          echo "=== Build Notes Report ==="
+          cat docs/buildnotes.md
+
       - name: Publish Tool Versions
         shell: bash
         run: |

AGENTS.md

@@ -14,7 +14,7 @@ publishing tool version information across CI/CD environments.
 
 ## Tech Stack
 
-- C# 12, .NET 8.0/9.0/10.0, dotnet CLI, NuGet
+- C# (latest), .NET 8.0/9.0/10.0, dotnet CLI, NuGet
 - YAML configuration files (.versionmark.yaml)
 - JSON for version capture data
 - Markdown for published documentation
@@ -33,7 +33,7 @@ VersionMark is a tool that:
 
 - **`.versionmark.yaml`** - Configuration defining tools to capture and how to extract versions
 - **`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

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)

README.md

@@ -189,6 +189,50 @@ Publish mode generates a markdown list consolidating versions from all jobs:
 When a tool has the same version across all jobs, it's shown without job identifiers. When versions
 differ, each version is listed on a separate line with the jobs that use it shown in parentheses.
 
+## Self Validation
+
+VersionMark includes built-in self-validation tests that verify the tool is working correctly in
+its current environment. Run with `--validate`:
+
+```bash
+versionmark --validate
+```
+
+Example output:
+
+```text
+# DEMA Consulting VersionMark
+
+| Information         | Value                                              |
+| :------------------ | :------------------------------------------------- |
+| Tool Version        | 1.2.3                                              |
+| Machine Name        | build-agent-01                                     |
+| OS Version          | Ubuntu 22.04.3 LTS                                 |
+| DotNet Runtime      | .NET 10.0.0                                        |
+| Time Stamp          | 2025-01-01 12:00:00 UTC                            |
+
+✓ VersionMark_CapturesVersions - Passed
+✓ VersionMark_GeneratesMarkdownReport - Passed
+
+Total Tests: 2
+Passed: 2
+Failed: 0
+```
+
+To save results in TRX format (Visual Studio test results):
+
+```bash
+versionmark --validate --results results.trx
+```
+
+To save results in JUnit XML format:
+
+```bash
+versionmark --validate --results results.xml
+```
+
+If any tests fail, the exit code will be non-zero.
+
 ## Documentation
 
 Generated documentation includes:

docs/guide/guide.md

@@ -302,6 +302,69 @@ alphabetical order.
 - **Version Order**: When multiple versions exist, they are sorted alphabetically
 - **Job IDs**: Within each version group, job IDs are sorted alphabetically
 
+# Self-Validation
+
+VersionMark includes built-in self-validation tests that verify the tool is functioning correctly
+in its current environment.
+
+## Running Validation
+
+Run self-validation with the `--validate` flag:
+
+```bash
+versionmark --validate
+```
+
+To save results in TRX format (Visual Studio test results):
+
+```bash
+versionmark --validate --results results.trx
+```
+
+To save results in JUnit XML format:
+
+```bash
+versionmark --validate --results results.xml
+```
+
+Use `--silent` to suppress console output while still writing a results file:
+
+```bash
+versionmark --silent --validate --results results.trx
+```
+
+## Validation Report
+
+Example output:
+
+```text
+# DEMA Consulting VersionMark
+
+| Information         | Value                                              |
+| :------------------ | :------------------------------------------------- |
+| Tool Version        | 1.2.3                                              |
+| Machine Name        | build-agent-01                                     |
+| OS Version          | Ubuntu 22.04.3 LTS                                 |
+| DotNet Runtime      | .NET 10.0.0                                        |
+| Time Stamp          | 2025-01-01 12:00:00 UTC                            |
+
+✓ VersionMark_CapturesVersions - Passed
+✓ VersionMark_GeneratesMarkdownReport - Passed
+
+Total Tests: 2
+Passed: 2
+Failed: 0
+```
+
+If any tests fail, the exit code will be non-zero.
+
+## Validation Tests
+
+| Test | What It Proves |
+| :--- | :------------- |
+| `VersionMark_CapturesVersions` | The tool can read a `.versionmark.yaml` config and capture tool versions to a JSON file |
+| `VersionMark_GeneratesMarkdownReport` | The tool can read captured JSON files and generate a markdown report |
+
 # CI/CD Integration
 
 ## GitHub Actions Example