demaconsulting · Malcolmnixon · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026
diff --git a/docs/design/introduction.md b/docs/design/introduction.md
@@ -15,18 +15,16 @@ The purpose of this document is to:
 
 ## Scope
 
-This document covers the design of six subsystems within VersionMark:
+This document covers the design of five subsystems within VersionMark:
 
 - The **Cli Subsystem**: the `Program` entry point and `Context` class
   that handle argument parsing, output routing, and program flow control
 - The **Configuration Subsystem**: the `VersionMarkConfig` and `ToolConfig` classes that
-  read and interpret `.versionmark.yaml` configuration files
+  read, validate, and interpret `.versionmark.yaml` configuration files
 - The **Capture Subsystem**: the `VersionInfo` record that serializes and deserializes
   captured version data to and from JSON
 - The **Publishing Subsystem**: the `MarkdownFormatter` class that generates the markdown
   version report from captured data
-- The **Linting Subsystem**: the `Lint` class that validates `.versionmark.yaml` configuration
-  files and reports issues with precise source locations
 - The **SelfTest Subsystem**: the `Validation` class and `PathHelpers` utility that
   together provide built-in verification of the tool's core functionality
 
@@ -44,15 +42,13 @@ VersionMark (System)                        Version capture/publish tool
 ├── Cli (Subsystem)                         Argument parsing and dispatch
 │   ├── Program (Unit)                      Tool entry point
 │   └── Context (Unit)                      Command-line state container
-├── Configuration (Subsystem)               YAML configuration loading
-│   ├── VersionMarkConfig (Unit)            Top-level config container
+├── Configuration (Subsystem)               YAML configuration loading and validation
+│   ├── VersionMarkConfig (Unit)            Top-level config container and validator
 │   └── ToolConfig (Unit)                   Per-tool config record
 ├── Capture (Subsystem)                     Tool version capture
 │   └── VersionInfo (Unit)                  JSON version data record
 ├── Publishing (Subsystem)                  Markdown report publishing
 │   └── MarkdownFormatter (Unit)            Version report formatter
-├── Linting (Subsystem)                     Configuration file lint
-│   └── Lint (Unit)                         YAML configuration validator
 └── SelfTest (Subsystem)                    Built-in self-validation
     ├── Validation (Unit)                   Self-validation runner
     └── PathHelpers (Unit)                  Safe path combination
@@ -71,13 +67,12 @@ src/DemaConsulting.VersionMark/
 ├── Cli/
 │   └── Context.cs                          — command-line argument parser and I/O owner
 ├── Configuration/
-│   └── VersionMarkConfig.cs                — YAML configuration and tool definitions
+│   ├── LintIssue.cs                        — lint issue record and severity enum
+│   └── VersionMarkConfig.cs                — YAML configuration, tool definitions, and validation
 ├── Capture/
 │   └── VersionInfo.cs                      — captured version data record
 ├── Publishing/
 │   └── MarkdownFormatter.cs                — markdown report generation
-├── Linting/
-│   └── Lint.cs                             — YAML configuration linter
 └── SelfTest/
     ├── Validation.cs                        — self-validation test runner
     └── PathHelpers.cs                       — safe path utilities

diff --git a/docs/reqstream/configuration/load.yaml b/docs/reqstream/configuration/load.yaml
@@ -0,0 +1,145 @@
+---
+sections:
+  - title: VersionMark Load Requirements
+    requirements:
+      - id: VersionMark-Load-FileExistence
+        title: The tool shall report an error when the configuration file does not exist.
+        justification: |
+          Users may specify an incorrect path; an immediate, clear error message
+          avoids silent failures and directs the user to fix the file path.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_NonExistentFile_Fails
+
+      - id: VersionMark-Load-YamlParsing
+        title: The tool shall report an error when the configuration file contains invalid YAML.
+        justification: |
+          Malformed YAML cannot be interpreted. Reporting a parse error with its
+          location lets users quickly find and fix the syntax issue.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_InvalidYaml_Fails
+
+      - id: VersionMark-Load-ToolsSection
+        title: The tool shall report an error when the configuration file is missing a non-empty 'tools' section.
+        justification: |
+          A configuration without any tool definitions cannot perform any useful
+          capture or publish operations.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_MultipleErrors_ReportsAllErrorsInSinglePass
+
+      - id: VersionMark-Load-ToolCommand
+        title: The tool shall report an error when a tool is missing a non-empty 'command' field.
+        justification: |
+          The 'command' field defines how to invoke the tool to obtain version
+          information. Without it the tool cannot function at runtime.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_MultipleErrors_ReportsAllErrorsInSinglePass
+
+      - id: VersionMark-Load-ToolRegex
+        title: The tool shall report an error when a tool is missing a non-empty 'regex' field.
+        justification: |
+          The 'regex' field is used to extract the version string from command output.
+          Without it the tool cannot parse a version at runtime.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_MultipleErrors_ReportsAllErrorsInSinglePass
+
+      - id: VersionMark-Load-RegexValid
+        title: The tool shall report an error when a regex value cannot be compiled.
+        justification: |
+          An invalid regex pattern will cause a runtime failure. Detecting it early
+          during load gives the user a clear error with a precise file location.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_InvalidRegex_ReportsError
+
+      - id: VersionMark-Load-RegexVersion
+        title: The tool shall report an error when a regex does not contain a named 'version' capture group.
+        justification: |
+          The capture group named 'version' is the mechanism by which the tool
+          extracts the version string. Its absence causes silent data loss at runtime.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_RegexWithoutVersionGroup_ReportsError
+
+      - id: VersionMark-Load-OsOverrides
+        title: The tool shall report an error when an OS-specific command or regex override is empty.
+        justification: |
+          An empty OS-specific override will be used at runtime on the corresponding
+          platform, causing a capture failure. Detecting it during load prevents
+          platform-specific surprises.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_EmptyOsSpecificOverride_ReportsError
+
+      - id: VersionMark-Load-UnknownKeys
+        title: The tool shall report unknown keys as non-fatal warnings that do not fail loading.
+        justification: |
+          Unknown keys may be typos or forward-compatible extensions. Treating them
+          as warnings alerts users without blocking valid configurations from
+          proceeding.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_UnknownKey_IsWarningNotError
+
+      - id: VersionMark-Load-ErrorLocation
+        title: The tool shall report all load findings with the filename and line/column location.
+        justification: |
+          Precise locations (file, line, column) allow users to jump directly to the
+          problem in their editor, dramatically reducing the time needed to fix issues.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_Error_IncludesFileAndLineInfo
+
+      - id: VersionMark-Load-AllIssues
+        title: The tool shall report all load issues in a single pass without stopping at the first error.
+        justification: |
+          Reporting all issues at once lets users fix everything in one edit cycle
+          rather than repeatedly re-running to discover each subsequent problem.
+        tags:
+          - configuration
+        tests:
+          - ConfigurationLoad_MultipleErrors_ReportsAllErrorsInSinglePass
+
+      - id: VersionMark-Load-Method
+        title: >-
+          The VersionMarkConfig.Load method shall validate a .versionmark.yaml configuration file
+          and return issues with file, line, and column location alongside the loaded configuration.
+        justification: |
+          Centralizing all load and validation checks in a single Load method ensures a consistent
+          validation pass and allows all issues to be reported in one run rather than
+          stopping at the first error. Returning both the config and issues allows callers
+          to proceed when only warnings are present.
+        tests:
+          - VersionMarkConfig_Load_ValidConfig_ReturnsConfig
+          - VersionMarkConfig_Load_MissingFile_ReturnsNullConfig
+          - VersionMarkConfig_Load_InvalidYaml_ReturnsNullConfig
+          - VersionMarkConfig_Load_MissingToolsSection_ReturnsNullConfig
+          - VersionMarkConfig_Load_EmptyToolsSection_ReturnsNullConfig
+          - VersionMarkConfig_Load_MissingCommand_ReturnsNullConfig
+          - VersionMarkConfig_Load_EmptyCommand_ReturnsNullConfig
+          - VersionMarkConfig_Load_MissingRegex_ReturnsNullConfig
+          - VersionMarkConfig_Load_EmptyRegex_ReturnsNullConfig
+          - VersionMarkConfig_Load_InvalidRegex_ReturnsNullConfig
+          - VersionMarkConfig_Load_RegexMissingVersionGroup_ReturnsNullConfig
+          - VersionMarkConfig_Load_UnknownTopLevelKey_ReturnsConfig
+          - VersionMarkConfig_Load_UnknownToolKey_ReturnsConfig
+          - VersionMarkConfig_Load_OsSpecificEmptyCommand_ReturnsNullConfig
+          - VersionMarkConfig_Load_OsSpecificEmptyRegex_ReturnsNullConfig
+          - VersionMarkConfig_Load_OsSpecificRegexMissingVersionGroup_ReturnsNullConfig
+          - VersionMarkConfig_Load_OsSpecificInvalidRegex_ReturnsNullConfig
+          - VersionMarkConfig_Load_MultipleErrors_ReportsAll
+          - VersionMarkConfig_Load_IssuesContainFilePath
diff --git a/docs/reqstream/linting/lint.yaml b/docs/reqstream/linting/lint.yaml
diff --git a/docs/reqstream/linting/linting.yaml b/docs/reqstream/linting/linting.yaml
diff --git a/requirements.yaml b/requirements.yaml
@@ -17,8 +17,7 @@ includes:
   - docs/reqstream/configuration/configuration.yaml
   - docs/reqstream/configuration/version-mark-config.yaml
   - docs/reqstream/configuration/tool-config.yaml
-  - docs/reqstream/linting/linting.yaml
-  - docs/reqstream/linting/lint.yaml
+  - docs/reqstream/configuration/load.yaml
   - docs/reqstream/self-test/self-test.yaml
   - docs/reqstream/self-test/validation.yaml
   - docs/reqstream/self-test/path-helpers.yaml