chore: update repository to comply with standards

.reviewmark.yaml

@@ -17,43 +17,43 @@ reviews:
   - id: BuildMark-Program
     title: Review of BuildMark Program Unit
     paths:
-      - "docs/reqstream/unit-program.yaml"
+      - "docs/reqstream/program.yaml"
       - "docs/design/program.md"
       - "src/**/Program.cs"
       - "test/**/ProgramTests.cs"
 
   - id: BuildMark-Context
     title: Review of BuildMark Context Unit
     paths:
-      - "docs/reqstream/cli/unit-context.yaml"
+      - "docs/reqstream/cli/context.yaml"
       - "docs/design/cli/context.md"
       - "src/**/Cli/Context.cs"
       - "test/**/Cli/ContextTests.cs"
 
   - id: BuildMark-Validation
     title: Review of BuildMark Validation Unit
     paths:
-      - "docs/reqstream/self-test/unit-validation.yaml"
+      - "docs/reqstream/self-test/validation.yaml"
       - "docs/design/self-test/validation.md"
       - "src/**/SelfTest/Validation.cs"
       - "test/**/SelfTest/ValidationTests.cs"
 
   - id: BuildMark-PathHelpers
     title: Review of BuildMark PathHelpers Unit
     paths:
-      - "docs/reqstream/utilities/unit-path-helpers.yaml"
+      - "docs/reqstream/utilities/path-helpers.yaml"
       - "docs/design/utilities/path-helpers.md"
       - "src/**/Utilities/PathHelpers.cs"
       - "test/**/Utilities/PathHelpersTests.cs"
 
   - id: BuildMark-GitHubRepoConnector
     title: Review of BuildMark GitHubRepoConnector Unit
     paths:
-      - "docs/reqstream/repo-connectors/unit-github-repo-connector.yaml"
+      - "docs/reqstream/repo-connectors/github-repo-connector.yaml"
       - "docs/design/repo-connectors/github-repo-connector.md"
-      - "src/**/GitHub/GitHubRepoConnector.cs"
-      - "src/**/GitHub/GitHubGraphQLClient.cs"
-      - "src/**/GitHub/GitHubGraphQLTypes.cs"
+      - "src/**/RepoConnectors/GitHubRepoConnector.cs"
+      - "src/**/RepoConnectors/GitHub/GitHubGraphQLClient.cs"
+      - "src/**/RepoConnectors/GitHub/GitHubGraphQLTypes.cs"
       - "test/**/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs"
       - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientFindIssueIdsTests.cs"
       - "test/**/RepoConnectors/GitHub/GitHubGraphQLClientGetAllIssuesTests.cs"
@@ -69,47 +69,48 @@ reviews:
   - id: BuildMark-Cli
     title: Review of BuildMark Cli subsystem (command-line interface)
     paths:
-      - "docs/reqstream/cli/subsystem-cli.yaml"
+      - "docs/reqstream/cli/cli.yaml"
       - "docs/design/cli/cli.md"
       - "docs/design/cli/context.md"
       - "docs/design/program.md"
 
   - id: BuildMark-SelfTest
     title: Review of BuildMark SelfTest subsystem (self-validation)
     paths:
-      - "docs/reqstream/self-test/subsystem-self-test.yaml"
+      - "docs/reqstream/self-test/self-test.yaml"
       - "docs/design/self-test/self-test.md"
       - "docs/design/self-test/validation.md"
 
   - id: BuildMark-Utilities
     title: Review of BuildMark Utilities subsystem (shared utilities)
     paths:
-      - "docs/reqstream/utilities/subsystem-utilities.yaml"
+      - "docs/reqstream/utilities/utilities.yaml"
       - "docs/design/utilities/utilities.md"
       - "docs/design/utilities/path-helpers.md"
 
   - id: BuildMark-RepoConnectors
     title: Review of BuildMark RepoConnectors subsystem (repository connectors)
     paths:
-      - "docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml"   # subsystem requirements
-      - "docs/design/repo-connectors/repo-connectors.md"                  # subsystem design
-      - "docs/design/repo-connectors/github-repo-connector.md"            # GitHubRepoConnector unit design
-      - "src/**/RepoConnectors/IRepoConnector.cs"                         # connector interface
-      - "src/**/RepoConnectors/RepoConnectorBase.cs"                      # connector base class
-      - "src/**/RepoConnectors/RepoConnectorFactory.cs"                   # connector factory
-      - "src/**/RepoConnectors/MockRepoConnector.cs"                      # mock connector
-      - "src/**/RepoConnectors/ProcessRunner.cs"                          # process runner
-      - "test/**/RepoConnectors/MockRepoConnectorTests.cs"                # mock connector tests
-      - "test/**/RepoConnectors/ProcessRunnerTests.cs"                    # process runner tests
-      - "test/**/RepoConnectors/RepoConnectorFactoryTests.cs"             # factory tests
+      - "docs/reqstream/repo-connectors/repo-connectors.yaml"                  # subsystem requirements
+      - "docs/design/repo-connectors/repo-connectors.md"                       # subsystem design
+      - "docs/design/repo-connectors/github-repo-connector.md"                 # GitHubRepoConnector unit design
+      - "src/**/RepoConnectors/IRepoConnector.cs"                              # connector interface
+      - "src/**/RepoConnectors/RepoConnectorBase.cs"                           # connector base class
+      - "src/**/RepoConnectors/RepoConnectorFactory.cs"                        # connector factory
+      - "src/**/RepoConnectors/MockRepoConnector.cs"                           # mock connector
+      - "src/**/RepoConnectors/ProcessRunner.cs"                               # process runner
+      - "test/**/RepoConnectors/MockRepoConnectorTests.cs"                     # mock connector tests
+      - "test/**/RepoConnectors/ProcessRunnerTests.cs"                         # process runner tests
+      - "test/**/RepoConnectors/RepoConnectorFactoryTests.cs"                  # factory tests
 
   # System review
   - id: BuildMark-System
     title: Review of BuildMark system-level behavior and integration
     paths:
-      - "docs/reqstream/buildmark-system.yaml"
+      - "docs/reqstream/system.yaml"
       - "docs/reqstream/platform-requirements.yaml"
       - "docs/design/introduction.md"
+      - "docs/design/system.md"
       - "test/**/IntegrationTests.cs"
       - "test/**/Runner.cs"
       - "test/**/AssemblyInfo.cs"
@@ -125,14 +126,3 @@ reviews:
     paths:
       - "requirements.yaml"
       - "docs/reqstream/**/*.yaml"
-
-  # OTS dependency reviews
-  - id: OTS-Dependencies
-    title: Review of Off-The-Shelf Software Dependencies
-    paths:
-      - "docs/reqstream/ots-mstest.yaml"
-      - "docs/reqstream/ots-reqstream.yaml"
-      - "docs/reqstream/ots-buildmark.yaml"
-      - "docs/reqstream/ots-versionmark.yaml"
-      - "docs/reqstream/ots-sarifmark.yaml"
-      - "docs/reqstream/ots-sonarmark.yaml"

docs/design/system.md

@@ -0,0 +1,96 @@
+# BuildMark System Design
+
+## Overview
+
+BuildMark is a .NET command-line tool that generates markdown build notes from
+GitHub repository metadata. It queries GitHub's GraphQL API to retrieve commits,
+issues, pull requests, and version tags, then formats the results as a structured
+markdown report suitable for embedding in release documentation.
+
+## System Architecture
+
+BuildMark is composed of four subsystems and a top-level entry point:
+
+| Component            | Kind      | Responsibility                                           |
+|----------------------|-----------|----------------------------------------------------------|
+| `Program`            | Unit      | Entry point; dispatches to handlers based on CLI flags   |
+| `Cli`                | Subsystem | Command-line argument parsing and output channel control |
+| `RepoConnectors`     | Subsystem | Repository metadata retrieval via the GitHub GraphQL API |
+| `SelfTest`           | Subsystem | Built-in self-validation test framework                  |
+| `Utilities`          | Subsystem | Shared path combination helpers                          |
+
+## External Interfaces
+
+| Interface       | Direction | Protocol / Format                                   |
+|-----------------|-----------|-----------------------------------------------------|
+| Command line    | Input     | POSIX-style flags parsed by `Context`               |
+| GitHub GraphQL  | Output    | HTTPS POST to `https://api.github.com/graphql`      |
+| Markdown report | Output    | File written to `--report` path, UTF-8 markdown     |
+| Log file        | Output    | Optional file written to `--log` path, plain text   |
+| Test results    | Output    | TRX or JUnit XML written to `--results` path        |
+| Exit code       | Output    | 0 = success, 1 = error                              |
+
+## Data Flow
+
+```text
+[Command Line Args]
+        │
+        ▼
+  Context (Cli)          ← parses flags, opens log file
+        │
+        ▼
+  Program.Run()
+        ├─ --version  →  writes version to stdout
+        ├─ --help     →  writes usage to stdout
+        ├─ --validate →  Validation (SelfTest) → writes results to --results file
+        └─ (default)  →  ProcessBuildNotes()
+                              │
+                              ▼
+                   RepoConnectorFactory
+                              │
+                              ▼
+                   GitHubRepoConnector   ←─── GitHub GraphQL API
+                              │
+                              ▼
+                   BuildInformation.ToMarkdown()
+                              │
+                              ▼
+                   [Markdown Report File]
+```
+
+## System-Wide Design Constraints
+
+- **Target framework**: .NET 8, .NET 9, and .NET 10
+- **Platform support**: Windows, Linux, macOS
+- **Packaging**: Published as a .NET global tool (`dotnet tool install`)
+- **Authentication**: GitHub token supplied via `GH_TOKEN` environment variable,
+  `GITHUB_TOKEN` environment variable, or `gh auth token` CLI fallback
+- **No GUI**: All interaction is through the command line; no interactive prompts
+- **Self-contained**: No external configuration files required for normal operation
+
+## Integration Patterns
+
+### GitHub GraphQL Client
+
+`GitHubRepoConnector` uses `GitHubGraphQLClient` to issue paginated GraphQL
+queries over HTTPS. Authentication is via `Authorization: bearer <token>` header.
+The connector retrieves:
+
+- All tags (for identifying version boundaries)
+- Commits in the requested range
+- Issues referenced by commits
+- Pull requests in the requested range
+- Releases (for known-issues data)
+
+### Self-Validation
+
+The `--validate` flag invokes `Validation.Run`, which exercises core tool
+functionality using a `MockRepoConnector` and writes a standard TRX or JUnit XML
+results file. This allows operators to verify the tool works correctly in their
+environment without requiring a live GitHub connection.
+
+### Report Generation
+
+`BuildInformation.ToMarkdown` converts the in-memory build data model into a
+markdown string. The heading depth is configurable via `--report-depth`, allowing
+the report to be embedded at any level in a larger document.

requirements.yaml

@@ -1,19 +1,19 @@
 ---
 includes:
-  - docs/reqstream/buildmark-system.yaml
+  - docs/reqstream/system.yaml
   - docs/reqstream/platform-requirements.yaml
-  - docs/reqstream/unit-program.yaml
-  - docs/reqstream/cli/subsystem-cli.yaml
-  - docs/reqstream/cli/unit-context.yaml
-  - docs/reqstream/self-test/subsystem-self-test.yaml
-  - docs/reqstream/self-test/unit-validation.yaml
-  - docs/reqstream/utilities/subsystem-utilities.yaml
-  - docs/reqstream/utilities/unit-path-helpers.yaml
-  - docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml
-  - docs/reqstream/repo-connectors/unit-github-repo-connector.yaml
-  - docs/reqstream/ots-mstest.yaml
-  - docs/reqstream/ots-reqstream.yaml
-  - docs/reqstream/ots-buildmark.yaml
-  - docs/reqstream/ots-versionmark.yaml
-  - docs/reqstream/ots-sarifmark.yaml
-  - docs/reqstream/ots-sonarmark.yaml
+  - docs/reqstream/program.yaml
+  - docs/reqstream/cli/cli.yaml
+  - docs/reqstream/cli/context.yaml
+  - docs/reqstream/self-test/self-test.yaml
+  - docs/reqstream/self-test/validation.yaml
+  - docs/reqstream/utilities/utilities.yaml
+  - docs/reqstream/utilities/path-helpers.yaml
+  - docs/reqstream/repo-connectors/repo-connectors.yaml
+  - docs/reqstream/repo-connectors/github-repo-connector.yaml
+  - docs/reqstream/ots/mstest.yaml
+  - docs/reqstream/ots/reqstream.yaml
+  - docs/reqstream/ots/buildmark.yaml
+  - docs/reqstream/ots/versionmark.yaml
+  - docs/reqstream/ots/sarifmark.yaml
+  - docs/reqstream/ots/sonarmark.yaml