demaconsulting · Malcolmnixon · May 4, 2026 · May 4, 2026 · May 4, 2026 · May 4, 2026
diff --git a/.reviewmark.yaml b/.reviewmark.yaml
diff --git a/docs/design/build-mark/program.md b/docs/design/build-mark/program.md
@@ -43,7 +43,7 @@ method applies the following priority order:
 2. Print the application banner (version and copyright).
 3. If `context.Help` is set, print the usage message and return.
 4. If `context.Validate` is set, delegate to `Validation.Run(context)` and return.
-5. If `context.Lint` is set, call `BuildMarkConfigReader.ReadAsync`, call
+5. If `context.Lint` is set, call `LoadConfiguration()`, call
    `result.ReportTo(context)`, and return.
 6. Otherwise, call `ProcessBuildNotes(context)` to generate the build report.
 

diff --git a/docs/design/build-mark/version/version.md b/docs/design/build-mark/version/version.md
@@ -22,20 +22,20 @@ The Version subsystem is composed of six units:
 ```text
 VersionTag (raw repository tag)
     ↓ (extraction)
-VersionSemantic (parsed semantic version)  
+VersionSemantic (parsed semantic version)
     ↓ (normalization)
 VersionComparable (optimized comparison)
     ↓ (range operations)
 VersionInterval / VersionIntervalSet (version ranges)
-    ↓ (build association)  
+    ↓ (build association)
 VersionCommitTag (version + commit hash)
 ```
 
 ## Design Principles
 
 ### Semantic Versioning Compliance
 
-All version processing strictly adheres to [Semantic Versioning 2.0.0](https://semver.org/) specification
+All version processing strictly adheres to Semantic Versioning 2.0.0 (<https://semver.org/>) specification
 to ensure predictable and industry-standard behavior.
 
 ### Performance Optimization
@@ -48,7 +48,7 @@ through construction-time parsing and cached segment arrays.
 Each version type serves a specific purpose with clear boundaries:
 
 - **VersionTag**: Raw string from repository
-- **VersionSemantic**: Validated SemVer structure  
+- **VersionSemantic**: Validated SemVer structure
 - **VersionComparable**: Optimized for comparison operations
 - **VersionInterval**: Range queries and filtering
 - **VersionCommitTag**: Build metadata association
@@ -69,7 +69,7 @@ Each version type serves a specific purpose with clear boundaries:
 Version subsystem processes raw repository tags from GitHub and other sources,
 extracting semantic versions for build boundary determination.
 
-### Build Notes  
+### Build Notes
 
 Provides VersionCommitTag associations that link semantic versions to specific commit hashes for build information generation.
 

diff --git a/docs/design/introduction.md b/docs/design/introduction.md
@@ -45,7 +45,7 @@ BuildMark (System)
 │   └── ProcessRunner (Unit)
 ├── Version (Subsystem)
 │   ├── VersionComparable (Unit)
-│   ├── VersionSemantic (Unit)  
+│   ├── VersionSemantic (Unit)
 │   ├── VersionTag (Unit)
 │   ├── VersionInterval (Unit)
 │   ├── VersionIntervalSet (Unit)
@@ -156,6 +156,4 @@ Throughout this document:
 ## References
 
 - See the BuildMark User Guide for user-facing documentation.
-- [BuildMark Repository][repo]
-
-[repo]: https://github.com/demaconsulting/BuildMark
+- See the BuildMark repository at <https://github.com/demaconsulting/BuildMark>.
diff --git a/docs/reqstream/build-mark/build-mark.yaml b/docs/reqstream/build-mark/build-mark.yaml
@@ -365,6 +365,48 @@ sections:
               - BuildMark-BuildNotes-ReportModel
               - BuildMark-Program-Report
 
+          - id: BuildMark-Report-BaselinePreRelease
+            title: >-
+              The tool shall select the previous tag with a different commit hash as the
+              baseline when generating build notes for a pre-release version.
+            justification: |
+              When two pre-release tags point to the same commit, using the immediately
+              preceding tag as the baseline would produce an empty changelog. Selecting
+              the most recent predecessor with a different commit hash ensures a meaningful
+              changelog is always generated for pre-release builds.
+            tests:
+              - BuildMark_Report_BaselinePreRelease_SkipsSameCommitPredecessor
+            children:
+              - BuildMark-RepoConnectorBase-BaselinePreRelease
+
+          - id: BuildMark-Report-BaselineRelease
+            title: >-
+              The tool shall select the previous release tag as the baseline when
+              generating build notes for a release version, skipping all pre-release tags.
+            justification: |
+              Release notes should cover all changes since the last stable release, not
+              just changes since the most recent pre-release. Skipping pre-release
+              predecessors when selecting the baseline ensures completeness and correctness
+              of the generated release notes.
+            tests:
+              - BuildMark_Report_ShowsVersionRangeFromPreviousRelease
+            children:
+              - BuildMark-RepoConnectorBase-BaselineRelease
+
+          - id: BuildMark-Report-BaselineFirstRelease
+            title: >-
+              The tool shall generate build notes from the beginning of repository history
+              when no previous version tag qualifies as a baseline.
+            justification: |
+              When a project publishes its first release there is no predecessor tag.
+              Treating the absence of a qualifying baseline as "generate from the start
+              of history" ensures that the first release still receives meaningful, complete
+              build notes rather than an error or an empty report.
+            tests:
+              - BuildMark_Report_BaselineFirstRelease_GeneratesFromBeginningOfHistory
+            children:
+              - BuildMark-RepoConnectorBase-BaselineNoHistory
+
           - id: BuildMark-Report-Hyperlinks
             title: The tool shall include hyperlinks to issues and pull requests.
             justification: |

diff --git a/docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.yaml b/docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.yaml
@@ -10,9 +10,8 @@ sections:
     requirements:
       - id: BuildMark-AzureDevOps-RestClient
         title: >-
-          The AzureDevOpsRestClient shall retrieve repository details, commits, tags,
-          pull requests, and work items from the Azure DevOps API, including support
-          for paginated responses.
+          The AzureDevOpsRestClient shall retrieve repository data using the Azure DevOps
+          REST API, including support for paginated responses.
         justification: |
           The Azure DevOps REST API returns large result sets in pages. The client must
           transparently follow pagination to retrieve complete repository data so that

diff --git a/docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops.yaml b/docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops.yaml
@@ -13,10 +13,8 @@ sections:
     requirements:
       - id: BuildMark-AzureDevOps-SubSystem
         title: >-
-          The AzureDevOps sub-subsystem shall provide a repository connector that implements
-          the IRepoConnector interface, retrieves build information from Azure DevOps, supports
-          URL parsing, item controls, configurable routing rules, REST API access, and work
-          item mapping.
+          The AzureDevOps sub-subsystem shall implement the IRepoConnector interface
+          for Azure DevOps repositories.
         justification: |
           Generating build notes from Azure DevOps repositories requires a dedicated sub-subsystem
           that can authenticate to the Azure DevOps REST API, retrieve commits, tags, pull

diff --git a/docs/reqstream/build-mark/repo-connectors/github/github-graphql-client.yaml b/docs/reqstream/build-mark/repo-connectors/github/github-graphql-client.yaml
@@ -11,8 +11,8 @@ sections:
     requirements:
       - id: BuildMark-GitHub-GraphQLClient
         title: >-
-          The GitHubGraphQLClient shall retrieve commits, releases, tags, pull requests,
-          and issues from the GitHub repository, including support for paginated responses.
+          The GitHubGraphQLClient shall retrieve repository data using the GitHub GraphQL API,
+          including support for paginated responses.
         justification: |
           The GitHub API returns large result sets in pages. The client must transparently
           follow pagination cursors to retrieve all commits, releases, tags, pull requests,

diff --git a/docs/reqstream/build-mark/repo-connectors/github/github.yaml b/docs/reqstream/build-mark/repo-connectors/github/github.yaml
@@ -13,9 +13,8 @@ sections:
     requirements:
       - id: BuildMark-GitHub-SubSystem
         title: >-
-          The GitHub sub-subsystem shall provide a repository connector that implements
-          the IRepoConnector interface, retrieves build information from GitHub, supports
-          item controls, description body retrieval, and configurable routing rules.
+          The GitHub sub-subsystem shall implement the IRepoConnector interface
+          for GitHub repositories.
         justification: |
           Generating build notes from GitHub repositories requires a dedicated sub-subsystem
           that can authenticate to the GitHub API, retrieve commits, releases, tags, pull

diff --git a/docs/reqstream/build-mark/repo-connectors/repo-connector-base.yaml b/docs/reqstream/build-mark/repo-connectors/repo-connector-base.yaml
@@ -63,3 +63,45 @@ sections:
         tests:
           - RepoConnectorBase_FindVersionIndex_DifferentPrefixSameVersion_ReturnsCorrectIndex
           - RepoConnectorBase_FindVersionIndex_VersionNotInList_ReturnsMinusOne
+
+      - id: BuildMark-RepoConnectorBase-BaselinePreRelease
+        title: >-
+          For a pre-release target version, RepoConnectorBase shall select the most
+          recent preceding tag with a different commit hash as the baseline, skipping
+          tags that share the same commit hash to avoid generating empty changelogs.
+        justification: |
+          When multiple pre-release tags are created from the same commit (e.g., a tag
+          is renamed or recreated), using such a tag as the baseline would produce an
+          empty changelog because the commit range would be empty. By skipping tags with
+          the same commit hash, BuildMark always produces a meaningful changelog for
+          pre-release builds.
+        tests:
+          - RepoConnectorBase_FindBaselineForPreRelease_SameCommitSkipped_ReturnsPreviousDistinctCommit
+          - RepoConnectorBase_FindBaselineForPreRelease_AllSameCommit_ReturnsNull
+
+      - id: BuildMark-RepoConnectorBase-BaselineRelease
+        title: >-
+          For a release target version, RepoConnectorBase shall select the most recent
+          preceding release tag as the baseline, skipping all pre-release tags.
+        justification: |
+          Release notes should describe changes since the previous stable release, not
+          since the most recent pre-release candidate. Skipping pre-release tags when
+          selecting the baseline ensures that the generated changelog covers the complete
+          set of changes that went into the release.
+        tests:
+          - RepoConnectorBase_FindBaselineForRelease_SkipsPreReleaseTags_ReturnsPreviousReleaseTag
+          - RepoConnectorBase_FindBaselineForRelease_NoPreviousRelease_ReturnsNull
+
+      - id: BuildMark-RepoConnectorBase-BaselineNoHistory
+        title: >-
+          When no qualifying baseline tag exists in the version history,
+          RepoConnectorBase shall return null to indicate that build notes should be
+          generated from the beginning of repository history.
+        justification: |
+          The first release in a repository has no predecessor tag, so there is no
+          meaningful baseline from which to compute a changelog. Returning null allows
+          the connector to generate build notes covering the complete repository history
+          up to the first release, rather than producing an error or an empty report.
+        tests:
+          - RepoConnectorBase_FindBaselineForRelease_NoPreviousVersion_ReturnsNull
+          - RepoConnectorBase_FindBaselineForPreRelease_NoPreviousVersion_ReturnsNull
diff --git a/docs/user_guide/cli-reference.md b/docs/user_guide/cli-reference.md
@@ -14,7 +14,7 @@
 | `--build-version <ver>` | Specify the build version for report generation |
 | `--report <file>` | Export build notes to a markdown file |
 | `--depth <n>` | Set markdown heading depth (default: 1) |
-| `--include-known-issues` | Include open bugs as known issues |
+| `--include-known-issues` | Include known issues (open bugs, plus closed bugs with matching affected-versions). |
 
 ## Display Options
 
@@ -89,7 +89,8 @@ buildmark --build-version v1.2.3 --report build-notes.md --depth 2
 
 ### `--include-known-issues`
 
-Include known issues in the generated report. Known issues are open bugs in the GitHub repository.
+Include known issues in the generated report. Known issues are open bugs in the repository,
+plus closed bugs whose `affected-versions` field intersects the current build version.
 
 ```bash
 buildmark --build-version v1.2.3 --report build-notes.md --include-known-issues