Add subsystem folder structure for design docs and requirements

[Copilot]

Applies the subsystem folder structure from TemplateDotNetTool PR #81 to BuildMark, establishing Cli, SelfTest, Utilities, and RepoConnectors as named subsystems with full design, requirements, and review coverage.

Description

Source Reorganization

• Context.cs → Cli/Context.cs
• Validation.cs → SelfTest/Validation.cs
• PathHelpers.cs → Utilities/PathHelpers.cs
• Corresponding test files moved to matching subdirectories (Cli/, SelfTest/, Utilities/)
• RepoConnectors test files moved to their subsystem subdirectory (RepoConnectors/):
  • GitHubRepoConnectorTests.cs → RepoConnectors/GitHub/GitHubRepoConnectorTests.cs
  • MockRepoConnectorTests.cs → RepoConnectors/MockRepoConnectorTests.cs
  • ProcessRunnerTests.cs → RepoConnectors/ProcessRunnerTests.cs
  • RepoConnectorFactoryTests.cs → RepoConnectors/RepoConnectorFactoryTests.cs
• Namespaces unchanged (DemaConsulting.BuildMark)

New docs/design/ Structure

12 design markdown files added:

• introduction.md — Software Structure tree and Folder Layout sections
• program.md — Program unit design
• cli/{cli,context}.md — Cli subsystem + Context unit
• self-test/{self-test,validation}.md — SelfTest subsystem + Validation unit
• utilities/{utilities,path-helpers}.md — Utilities subsystem + PathHelpers unit
• repo-connectors/{repo-connectors,github-repo-connector}.md — RepoConnectors subsystem + GitHubRepoConnector unit
• definition.yaml + title.txt for Pandoc assembly

Design Doc Corrections

• path-helpers.md: SafePathCombine return value corrected from "single absolute path" to the actual Path.Combine result (which may be relative if basePath is relative); algorithm steps updated to accurately reflect the implementation.
• context.md: OpenLogFile description corrected to overwrite mode; missing blank line before ### WriteLine heading fixed (MD022).
• validation.md: Interactions table updated to reflect that PathHelpers is used directly; table column alignment corrected (MD060).

New docs/reqstream/ Structure

17 YAML requirement files extracted from the previous monolithic requirements.yaml:

• buildmark-system.yaml — system-level requirements with children: links pointing down to subsystem requirements
• platform-requirements.yaml — platform support requirements
• unit-program.yaml — Program unit requirements (Version, Help, Validate, Report)
• cli/subsystem-cli.yaml — Cli subsystem requirements with children: links to Context unit requirements
• cli/unit-context.yaml — Context unit requirements (ArgumentParsing, InvalidArgs, Output, Silent, ErrorOutput, ExitCode)
• self-test/subsystem-self-test.yaml — SelfTest subsystem requirements with children: links to Validation unit requirements
• self-test/unit-validation.yaml — Validation unit requirements (Run, TrxOutput, JUnitOutput)
• utilities/subsystem-utilities.yaml — Utilities subsystem requirements with children: links to PathHelpers unit requirements
• utilities/unit-path-helpers.yaml — PathHelpers unit requirements (SafeCombine)
• repo-connectors/subsystem-repo-connectors.yaml — RepoConnectors subsystem requirements with children: links to GitHubRepoConnector unit requirements
• repo-connectors/unit-github-repo-connector.yaml — GitHubRepoConnector unit requirements (BuildInformation, GraphQLClient)
• ots-{mstest,reqstream,buildmark,versionmark,sarifmark,sonarmark}.yaml — OTS items

requirements.yaml is now an includes:-only root file.

Requirements Hierarchy

children: links form a complete traceability chain from system to unit:

• System (buildmark-system.yaml) → children: to Cli, RepoConnectors, SelfTest, Utilities, and Program subsystem/unit requirements
• Cli subsystem (subsystem-cli.yaml) → each feature requirement has children: pointing to the relevant Context unit requirements
• SelfTest subsystem (subsystem-self-test.yaml) → children: to Validation unit requirements
• Utilities subsystem (subsystem-utilities.yaml) → children: to PathHelpers unit requirements
• RepoConnectors subsystem (subsystem-repo-connectors.yaml) → children: to GitHubRepoConnector unit requirements

Unit-level tests (Context_*, PathHelpers_*, Validation_*, GitHubGraphQLClient_*) are linked at the subsystem/unit level; system requirements reference only integration-level tests (IntegrationTest_*, BuildMark_*).

New .reviewmark.yaml

13 named review-sets covering all units, subsystems, system integration, design documents, all requirements, and OTS dependencies — following the [Product]-[Unit], [Product]-[Subsystem], [Product]-System, [Product]-Design, [Product]-AllRequirements, and OTS-Dependencies patterns. The BuildMark-RepoConnectors subsystem review includes source and test files for the full subsystem.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.BuildMark --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• All linters pass: ./lint.sh (Unix/macOS) or cmd /c lint.bat / ./lint.bat (Windows)

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

The software structure tree in docs/design/introduction.md:

BuildMark (System)
├── Program (Unit)
├── Cli (Subsystem)
│   └── Context (Unit)
├── SelfTest (Subsystem)
│   └── Validation (Unit)
├── Utilities (Subsystem)
│   └── PathHelpers (Unit)
└── RepoConnectors (Subsystem)
    └── GitHubRepoConnector (Unit)

Root-level data model classes (BuildInformation, ItemInfo, Version, VersionTag, WebLink) are not moved — they remain at the system level as they are not independently subsystem-owned.

The test project mirrors the source subsystem layout: all subsystem test files are now organized under their respective subsystem subdirectories (Cli/, SelfTest/, Utilities/, RepoConnectors/).

[Malcolmnixon]

@copilot I'm not seeing subsystem tests.

[Malcolmnixon]

@copilot Please review all requirements and their linking, and make sure:

children links go "down" in the software structure
children links go to relevant child requirement IDs.

[Copilot]

@copilot I'm not seeing subsystem tests.

The RepoConnectors subsystem test files were still at the root level — added in 137ab5c. They're now organized under RepoConnectors/ to match the source structure:

• GitHubRepoConnectorTests.cs → RepoConnectors/GitHub/GitHubRepoConnectorTests.cs
• MockRepoConnectorTests.cs → RepoConnectors/MockRepoConnectorTests.cs
• ProcessRunnerTests.cs → RepoConnectors/ProcessRunnerTests.cs
• RepoConnectorFactoryTests.cs → RepoConnectors/RepoConnectorFactoryTests.cs

The .reviewmark.yaml BuildMark-RepoConnectors subsystem review was also expanded to include the source and test files for the full subsystem.

[Copilot]

@copilot Please review all requirements and their linking, and make sure:

children links go "down" in the software structure
...

Fixed in 83156d4. All subsystem and unit requirement files were empty — they now have actual requirements, and children: links flow down through the hierarchy:

• System (buildmark-system.yaml) → children: point to Cli/RepoConnectors/SelfTest/Utilities/Program subsystem/unit requirements
• Cli subsystem (subsystem-cli.yaml) → each feature requirement has children: pointing to the relevant Context unit requirements
• SelfTest subsystem (subsystem-self-test.yaml) → children: point to Validation unit requirements
• Utilities subsystem (subsystem-utilities.yaml) → children: point to PathHelpers unit requirements
• RepoConnectors subsystem (subsystem-repo-connectors.yaml) → children: point to GitHubRepoConnector unit requirements

The unit requirement files (unit-context.yaml, unit-validation.yaml, unit-path-helpers.yaml, unit-github-repo-connector.yaml, unit-program.yaml) are leaf nodes with no further children. dotnet reqstream --lint and yamllint both pass.

[Copilot]

Pull request overview

Establishes an explicit subsystem-based structure for BuildMark (Cli, SelfTest, Utilities, RepoConnectors) and adds corresponding design + requirement artifacts to support traceability and review coverage across the tool.

Changes:

• Reorganizes source and test code into subsystem folders while keeping namespaces unchanged.
• Splits the monolithic requirements.yaml into a ReqStream include tree under docs/reqstream/, with system→subsystem→unit children: traceability.
• Adds a structured docs/design/ set (Pandoc assembly inputs) and introduces .reviewmark.yaml review sets to cover system/subsystems/units and OTS items.

Reviewed changes

Copilot reviewed 31 out of 41 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/DemaConsulting.BuildMark.Tests/Utilities/PathHelpersTests.cs	Adds/moves unit tests for PathHelpers.SafePathCombine.
test/DemaConsulting.BuildMark.Tests/SelfTest/ValidationTests.cs	Adds/moves self-test validation output tests (TRX/JUnit + error handling).
test/DemaConsulting.BuildMark.Tests/RepoConnectors/RepoConnectorFactoryTests.cs	Adds/moves tests for connector factory creation behavior.
test/DemaConsulting.BuildMark.Tests/RepoConnectors/ProcessRunnerTests.cs	Adds/moves process execution tests for repo connector support utilities.
test/DemaConsulting.BuildMark.Tests/RepoConnectors/MockRepoConnectorTests.cs	Adds/moves tests for the mock connector used by self-test and dev flows.
test/DemaConsulting.BuildMark.Tests/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs	Adds/moves GitHub connector tests into the RepoConnectors subsystem layout.
test/DemaConsulting.BuildMark.Tests/Cli/ContextTests.cs	Adds/moves CLI context parsing/output/exit-code tests into Cli/.
src/DemaConsulting.BuildMark/Utilities/PathHelpers.cs	Introduces/moves safe path-combine helper under Utilities subsystem folder.
src/DemaConsulting.BuildMark/SelfTest/Validation.cs	Introduces/moves self-validation runner under SelfTest subsystem folder.
src/DemaConsulting.BuildMark/Cli/Context.cs	Introduces/moves CLI context (arg parsing + output routing) under Cli subsystem folder.
requirements.yaml	Converts root requirements file into an includes:-only aggregator.
docs/reqstream/utilities/unit-path-helpers.yaml	Adds unit-level requirements for PathHelpers.
docs/reqstream/utilities/subsystem-utilities.yaml	Adds Utilities subsystem requirements and links down to unit requirements.
docs/reqstream/unit-program.yaml	Adds Program unit requirements (version/help/validate/report).
docs/reqstream/self-test/unit-validation.yaml	Adds Validation unit requirements for self-test execution and results output.
docs/reqstream/self-test/subsystem-self-test.yaml	Adds SelfTest subsystem requirements with children: traceability to Validation.
docs/reqstream/repo-connectors/unit-github-repo-connector.yaml	Adds GitHubRepoConnector unit requirements with test evidence links.
docs/reqstream/repo-connectors/subsystem-repo-connectors.yaml	Adds RepoConnectors subsystem requirements covering GitHub/mock/factory/process runner.
docs/reqstream/platform-requirements.yaml	Adds platform/runtime support requirements (Windows/Linux/macOS + net8/net9/net10).
docs/reqstream/ots-versionmark.yaml	Splits OTS requirement for VersionMark into its own file.
docs/reqstream/ots-sonarmark.yaml	Splits OTS requirement for SonarMark into its own file.
docs/reqstream/ots-sarifmark.yaml	Splits OTS requirement for SarifMark into its own file.
docs/reqstream/ots-reqstream.yaml	Splits OTS requirement for ReqStream into its own file.
docs/reqstream/ots-mstest.yaml	Splits OTS requirement for MSTest into its own file.
docs/reqstream/ots-buildmark.yaml	Splits OTS requirement for BuildMark into its own file.
docs/reqstream/cli/unit-context.yaml	Adds Context unit requirements (parsing/output/silent/stderr/exit code).
docs/reqstream/cli/subsystem-cli.yaml	Adds Cli subsystem requirements with children: links to Context requirements.
docs/reqstream/buildmark-system.yaml	Adds system-level requirements with subsystem/unit traceability links.
docs/design/utilities/utilities.md	Adds Utilities subsystem design chapter.
docs/design/utilities/path-helpers.md	Adds PathHelpers unit design chapter.
docs/design/title.txt	Adds Pandoc title metadata for design document assembly.
docs/design/self-test/validation.md	Adds Validation unit design chapter.
docs/design/self-test/self-test.md	Adds SelfTest subsystem design chapter.
docs/design/repo-connectors/repo-connectors.md	Adds RepoConnectors subsystem design chapter.
docs/design/repo-connectors/github-repo-connector.md	Adds GitHubRepoConnector unit design chapter.
docs/design/program.md	Adds Program unit design chapter.
docs/design/introduction.md	Adds design document introduction including software structure + folder layout.
docs/design/definition.yaml	Adds Pandoc assembly definition listing input files/resources/templates.
docs/design/cli/context.md	Adds Context unit design chapter.
docs/design/cli/cli.md	Adds Cli subsystem design chapter.
.reviewmark.yaml	Adds ReviewMark configuration defining review sets for units/subsystems/system/design/requirements/OTS.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Malcolmnixon]

@copilot Please fix linting issues

[Copilot]

@copilot Please fix linting issues

The linting issues were fixed in 1f2bb41:

• MD022 (missing blank line before heading): added blank line before ### WriteLine in context.md
• MD060 (table column style): corrected trailing spaces in the PathHelpers table row in validation.md to align with the header/separator

All lint tools pass locally (markdownlint-cli2, yamllint, cspell, dotnet format). The latest CI run shows action_required (waiting for manual approval), with no failed jobs.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)