Align documentation, fix requirement ID contractions, and enforce requirements linkage hierarchy

README.md

@@ -114,6 +114,7 @@ Options:
   -?, -h, --help               Display this help message
   --silent                     Suppress console output
   --validate                   Run self-validation
+  --lint                       Validate .buildmark.yaml and exit
   --results <file>             Write validation results (TRX or JUnit format)
   --log <file>                 Write output to log file
   --build-version <version>    Specify the build version
@@ -162,9 +163,10 @@ enabling version-controlled configuration.
 
 The file has three top-level sections:
 
-- **`connector`** — declares the repository connector type (`github`, `azure-devops`, or
-  `github+azure-devops`) and per-connector settings such as URL overrides, repository identifiers,
-  and token environment variable names.
+- **`connector`** — declares the repository connector type and per-connector settings such as URL
+  overrides, repository identifiers, and token environment variable names. Current releases support
+  the `github` connector. Azure DevOps connector values are reserved for future support and are not
+  yet implemented.
 - **`sections`** — defines the ordered list of sections that will appear in the generated build
   notes, each identified by an `id` and a `title`.
 - **`rules`** — an ordered list of match/route rules. Each rule can match on `label` and/or
@@ -177,22 +179,14 @@ Example `.buildmark.yaml`:
 # Repository Connector Settings
 connector:
   # Type of repository
-  type: github+azure-devops   # "github" | "azure-devops" | "github+azure-devops"
+  type: github
 
-  # GitHub settings (used for github or github+azure-devops)
+  # GitHub settings
   github:
     url: https://github.mycompany.com   # optional; defaults to https://api.github.com
     repository: owner/repo
     token-env: GH_TOKEN
 
-  # Azure DevOps settings (used for azure-devops or github+azure-devops)
-  azure-devops:
-    url: https://ado.mycompany.com      # optional; defaults to https://dev.azure.com
-    organization: MyOrg
-    project: MyProject
-    repository: MyRepo
-    token-env: AZURE_DEVOPS_TOKEN
-
 # Build Notes sections
 sections:
   - id: changes
@@ -233,6 +227,9 @@ rules:
   - route: changes
 ```
 
+Azure DevOps connector configuration is reserved for future support and should not be used with the
+current release.
+
 For more detail see the [User Guide](https://github.com/demaconsulting/BuildMark/blob/main/docs/user_guide/introduction.md).
 
 ## Self Validation

docs/design/build-mark/build-notes/build-notes.md

@@ -16,14 +16,14 @@ calls `BuildInformation.ToMarkdown` to write the final report file.
 |----------------------|-----------------------------------|---------------------------------------------------|
 | `BuildInformation`   | `BuildNotes/BuildInformation.cs`  | Top-level build data model and markdown renderer  |
 | `ItemInfo`           | `BuildNotes/ItemInfo.cs`          | Single issue or pull request in the report        |
-| `VersionTag`         | `BuildNotes/VersionTag.cs`        | Pairs a `Version` with its commit hash            |
+| `VersionTag`         | `BuildNotes/VersionTag.cs`        | Pairs a `VersionInfo` with its commit hash        |
 | `WebLink`            | `BuildNotes/WebLink.cs`           | Hyperlink used for the full-changelog entry       |
 
 ## Interactions
 
 | Unit / Subsystem    | Role                                                              |
 |---------------------|-------------------------------------------------------------------|
-| `Utilities`         | Supplies the `Version` type used by `VersionTag`                  |
+| `Utilities`         | Supplies the `VersionInfo` type used by `VersionTag`              |
 | `RepoConnectors`    | Connectors construct and populate `BuildInformation` records      |
 | `Program`           | Calls `BuildInformation.ToMarkdown` to produce the report file    |
 | `SelfTest`          | `Validation` creates `BuildInformation` records during self-tests |

docs/design/build-mark/build-notes/version-tag.md

@@ -3,26 +3,26 @@
 ## Overview
 
 `VersionTag` is a record in the BuildNotes subsystem that pairs a parsed
-`Version` value from the Utilities subsystem with the Git commit hash at which
+`VersionInfo` value from the Utilities subsystem with the Git commit hash at which
 that version tag was created. It is used to identify the baseline and current
 version boundaries when assembling a `BuildInformation` record.
 
 ## Data Model
 
 ```csharp
 public record VersionTag(
-    Version VersionInfo,
+    VersionInfo VersionInfo,
     string CommitHash);
 ```
 
-| Property      | Type      | Description                                    |
-|---------------|-----------|------------------------------------------------|
-| `VersionInfo` | `Version` | Parsed version information for this tag        |
-| `CommitHash`  | `string`  | Git commit hash at the point this tag was made |
+| Property      | Type          | Description                                    |
+|---------------|---------------|------------------------------------------------|
+| `VersionInfo` | `VersionInfo` | Parsed version information for this tag        |
+| `CommitHash`  | `string`      | Git commit hash at the point this tag was made |
 
 ## Interactions
 
-- `Utilities` supplies the `Version` type that carries parsed version details.
+- `Utilities` supplies the `VersionInfo` type that carries parsed version details.
 - `BuildInformation` uses `VersionTag` for `BaselineVersionTag` and
   `CurrentVersionTag`.
 - `RepoConnectors` construct `VersionTag` records from repository data.

docs/design/build-mark/cli/cli.md

@@ -26,6 +26,7 @@ subsystems receive a `Context` from the caller rather than creating one themselv
 | `Help`                | Property | Set when `--help` / `-h` / `-?` flag is present    |
 | `Silent`              | Property | Set when `--silent` flag is present                |
 | `Validate`            | Property | Set when `--validate` flag is present              |
+| `Lint`                | Property | Set when `--lint` flag is present                  |
 | `BuildVersion`        | Property | Value of `--build-version` argument                |
 | `ReportFile`          | Property | Value of `--report` argument                       |
 | `ReportDepth`         | Property | Value of `--report-depth` argument (default: 1)    |

docs/design/build-mark/cli/context.md

@@ -20,6 +20,7 @@ so that any open log file is properly flushed and closed.
 | `Help`               | `bool` | `false` | `-?` / `-h` / `--help`   |
 | `Silent`             | `bool` | `false` | `--silent`               |
 | `Validate`           | `bool` | `false` | `--validate`             |
+| `Lint`               | `bool` | `false` | `--lint`                 |
 | `IncludeKnownIssues` | `bool` | `false` | `--include-known-issues` |
 
 ### Parsed Arguments

docs/design/build-mark/repo-connectors/repo-connectors.md

@@ -24,9 +24,9 @@ subsystem alongside `GitHub` and `Mock`.
   the appropriate connector
 - `ItemRouter` — `RepoConnectors/ItemRouter.cs` — shared item-routing logic for
   all connectors
-- `ItemControlsParser` — `ItemControls/ItemControlsParser.cs` — parses
+- `ItemControlsParser` — `RepoConnectors/ItemControlsParser.cs` — parses
   buildmark blocks from item description bodies
-- `ItemControlsInfo` — `ItemControls/ItemControlsInfo.cs` — data record holding
+- `ItemControlsInfo` — `RepoConnectors/ItemControlsInfo.cs` — data record holding
   visibility, type, and version-set values
 
 ## Subsystems

docs/design/build-mark/utilities/utilities.md

@@ -4,8 +4,8 @@
 
 The Utilities subsystem provides shared helper classes used across the BuildMark
 system. It contains `PathHelpers` for safe path combination with traversal
-prevention, `ProcessRunner` for executing external shell commands, `Version` for
-parsing repository tags into normalized semantic version data, and
+prevention, `ProcessRunner` for executing external shell commands, `VersionInfo`
+for parsing repository tags into normalized semantic version data, and
 `VersionInterval`/`VersionIntervalSet` for parsing mathematical version interval
 expressions and testing whether specific versions fall inside them.
 
@@ -15,7 +15,7 @@ expressions and testing whether specific versions fall inside them.
 |----------------------|-----------------------------------|---------------------------------------|
 | `PathHelpers`        | `Utilities/PathHelpers.cs`        | Safe path combination                 |
 | `ProcessRunner`      | `Utilities/ProcessRunner.cs`      | External process execution            |
-| `Version`            | `Utilities/Version.cs`            | Repository tag parser                 |
+| `VersionInfo`        | `Utilities/VersionInfo.cs`        | Repository tag parser                 |
 | `VersionInterval`    | `Utilities/VersionInterval.cs`    | Version interval parser               |
 | `VersionIntervalSet` | `Utilities/VersionIntervalSet.cs` | Ordered version interval collection   |
 
@@ -34,34 +34,34 @@ expressions and testing whether specific versions fall inside them.
 | `RunAsync(command, arguments)`    | Method | Run a process and return stdout; throws on failure      |
 | `TryRunAsync(command, arguments)` | Method | Run a process and return stdout, or null on any failure |
 
-`Version` exposes the following static methods:
+`VersionInfo` exposes the following static methods:
 
-| Member             | Kind   | Description                                                       |
-|--------------------|--------|-------------------------------------------------------------------|
-| `TryCreate(tag)`   | Method | Parse a repository tag and return a normalized `Version`, or null |
-| `Create(tag)`      | Method | Parse a repository tag and throw if the tag is not recognized     |
+| Member           | Kind   | Description                                                             |
+|------------------|--------|-------------------------------------------------------------------------|
+| `TryCreate(tag)` | Method | Parse a repository tag and return a normalized `VersionInfo`, or null   |
+| `Create(tag)`    | Method | Parse a repository tag and throw if the tag is not recognized           |
 
 `VersionInterval` exposes the following methods:
 
 | Member                    | Kind   | Description                                                   |
 |---------------------------|--------|---------------------------------------------------------------|
 | `Parse(text)`             | Method | Parse a single interval token; returns null if invalid        |
 | `Contains(version)`       | Method | Test whether a semantic version string falls inside interval  |
-| `Contains(versionInfo)`   | Method | Test whether a BuildMark `Version` falls inside interval      |
+| `Contains(versionInfo)`   | Method | Test whether a BuildMark `VersionInfo` falls inside interval  |
 
 `VersionIntervalSet` exposes the following methods:
 
 | Member                    | Kind   | Description                                                             |
 |---------------------------|--------|-------------------------------------------------------------------------|
 | `Parse(text)`             | Method | Parse a comma-separated interval string into an ordered collection      |
 | `Contains(version)`       | Method | Test whether a semantic version string falls inside any contained range |
-| `Contains(versionInfo)`   | Method | Test whether a BuildMark `Version` falls inside any contained range     |
+| `Contains(versionInfo)`   | Method | Test whether a BuildMark `VersionInfo` falls inside any contained range |
 
 ## Interactions
 
-`PathHelpers`, `ProcessRunner`, and `Version` have no dependencies on other
+`PathHelpers`, `ProcessRunner`, and `VersionInfo` have no dependencies on other
 BuildMark subsystems. `VersionInterval` and `VersionIntervalSet` may consume
-`Version` instances through their `Contains(Version)` overloads. The subsystem
-is consumed by any unit that needs safe path combination, external process
-execution, version parsing, version interval parsing, or version containment
-checks.
+`VersionInfo` instances through their `Contains(VersionInfo)` overloads. The
+subsystem is consumed by any unit that needs safe path combination, external
+process execution, version parsing, version interval parsing, or version
+containment checks.

docs/design/build-mark/utilities/version-interval.md

@@ -96,10 +96,10 @@ Tests whether a semantic version string falls within the interval:
    is `false`.
 7. Return `true` otherwise.
 
-### `VersionInterval.Contains(Version version) → bool`
+### `VersionInterval.Contains(VersionInfo version) → bool`
 
 Convenience overload for callers that already hold a parsed BuildMark
-`Version`. This overload delegates to `Contains(string)` using
+`VersionInfo`. This overload delegates to `Contains(string)` using
 `version.SemanticVersion`.
 
 ### `VersionIntervalSet.Contains(string version) → bool`
@@ -111,10 +111,10 @@ Tests whether a semantic version string falls within any interval in the set:
 3. Return `true` as soon as any interval contains the candidate version.
 4. Return `false` when no interval matches.
 
-### `VersionIntervalSet.Contains(Version version) → bool`
+### `VersionIntervalSet.Contains(VersionInfo version) → bool`
 
 Convenience overload for callers that already hold a parsed BuildMark
-`Version`. This overload delegates to `Contains(string)` using
+`VersionInfo`. This overload delegates to `Contains(string)` using
 `version.SemanticVersion`.
 
 ## Parsing Examples
@@ -130,5 +130,5 @@ Convenience overload for callers that already hold a parsed BuildMark
 
 `VersionInterval` and `VersionIntervalSet` are general-purpose utility types.
 They are created by `ItemControlsParser`, stored on `ItemControlsInfo`, and may
-consume BuildMark `Version` instances through their `Contains(Version)`
+consume BuildMark `VersionInfo` instances through their `Contains(VersionInfo)`
 overloads.

docs/design/build-mark/utilities/version.md

@@ -1,16 +1,16 @@
-# Version
+# VersionInfo
 
 ## Overview
 
-`Version` is a record in the Utilities subsystem that parses repository tag
+`VersionInfo` is a record in the Utilities subsystem that parses repository tag
 strings into normalized semantic version data. It accepts optional tag
 prefixes, optional pre-release labels, and optional build metadata, and it
 exposes the parsed result in a form reusable across connectors and reporting.
 
 ## Data Model
 
 ```csharp
-public partial record Version(
+public partial record VersionInfo(
     string Tag,
     string FullVersion,
     string SemanticVersion,
@@ -33,21 +33,21 @@ and bare `2.0.0-beta.1`.
 
 ## Methods
 
-### `TryCreate(tag) → Version?`
+### `TryCreate(tag) → VersionInfo?`
 
 Static factory method. Attempts to parse the supplied tag string into a
-`Version` record. Returns `null` if the tag does not match a recognized version
+`VersionInfo` record. Returns `null` if the tag does not match a recognized version
 format.
 
-### `Create(tag) → Version`
+### `Create(tag) → VersionInfo`
 
 Static factory method. Calls `TryCreate` and throws `ArgumentException` when the
 tag does not match the supported version pattern.
 
 ## Interactions
 
-| Unit / Subsystem    | Role                                                             |
-|---------------------|------------------------------------------------------------------|
-| `RepoConnectors`    | Call `TryCreate` or `Create` when parsing repository tags        |
-| `BuildNotes`        | `VersionTag` carries parsed `Version` data for report boundaries |
-| `VersionInterval`   | Consumes `Version.SemanticVersion` via `Contains(Version)`       |
+| Unit / Subsystem  | Role                                                                  |
+|-------------------|-----------------------------------------------------------------------|
+| `RepoConnectors`  | Call `TryCreate` or `Create` when parsing repository tags             |
+| `BuildNotes`      | `VersionTag` carries parsed `VersionInfo` data for report boundaries  |
+| `VersionInterval` | Consumes `VersionInfo.SemanticVersion` via `Contains(VersionInfo)`    |

docs/design/introduction.md

@@ -43,7 +43,7 @@ BuildMark (System)
 ├── Utilities (Subsystem)
 │   ├── PathHelpers (Unit)
 │   ├── ProcessRunner (Unit)
-│   ├── Version (Unit)
+│   ├── VersionInfo (Unit)
 │   ├── VersionInterval (Unit)
 │   └── VersionIntervalSet (Unit)
 ├── Configuration (Subsystem)
@@ -93,7 +93,7 @@ src/DemaConsulting.BuildMark/
 ├── Utilities/
 │   ├── PathHelpers.cs                       — safe path combination utilities
 │   ├── ProcessRunner.cs                     — process runner for Git commands
-│   ├── Version.cs                           — semantic version parser and normalized model
+│   ├── VersionInfo.cs                       — semantic version parser and normalized model
 │   ├── VersionInterval.cs                   — single version interval model and parser
 │   └── VersionIntervalSet.cs                — ordered set of version intervals
 ├── Configuration/