Add subsystem folder structure for design docs and requirements

[Copilot]

Mirrors structural changes from TemplateDotNetLibrary#73 and ReviewMark#37: organizes design docs and reqstream files into subsystem subdirectories matching the source code layout. Per the software-items.md standard, both subsystems and units have requirements files and design documentation. System requirements are validated through integration tests; subsystem requirements are validated through subsystem-level tests.

Description

Design docs restructured into subsystem folders

• docs/design/context.md → docs/design/cli/context.md
• docs/design/validation.md → docs/design/self-test/validation.md
• docs/design/path-helpers.md → docs/design/utilities/path-helpers.md
• docs/design/program.md and introduction.md remain at root (system-level)
• docs/design/definition.yaml updated with new resource-path entries and input-files paths (subsystem doc before its unit docs)

New subsystem design documentation

Added subsystem-level design markdown files describing each subsystem's overview, units, interfaces, and interactions:

• docs/design/cli/cli.md — Cli subsystem design
• docs/design/self-test/self-test.md — SelfTest subsystem design
• docs/design/utilities/utilities.md — Utilities subsystem design

New system-level requirements file

Added docs/reqstream/templatetool-system.yaml with system-level requirements each linked to IntegrationTest_* tests — Version, Help, Validate (including TRX and JUnit results), Silent, Log, and ErrorHandling.

New and expanded subsystem requirements files

Added and expanded subsystem-level YAML files capturing externally visible subsystem contracts, following the ReviewMark pattern of granular per-feature requirements linked to both subsystem unit tests and integration tests:

• docs/reqstream/cli/subsystem-cli.yaml — expanded to 10 per-feature requirements (Context, Version, Help, Silent, Validate, Results, Log, ErrorOutput, InvalidArgs, ExitCode)
• docs/reqstream/self-test/subsystem-self-test.yaml — added Template-SelfTest-ResultsOutput requirement linking TRX/JUnit results tests
• docs/reqstream/utilities/subsystem-utilities.yaml

requirements.yaml updated to include all subsystem and system yaml files.

.reviewmark.yaml updated

• requirements.yaml added to needs-review
• Unit review sets updated to reference new design doc paths
• Subsystem review sets updated to include unit design docs under each subsystem
• TemplateTool-System review set added, containing system requirements, platform requirements, design introduction, IntegrationTests.cs, Runner.cs, and AssemblyInfo.cs
• IntegrationTests.cs, Runner.cs, and AssemblyInfo.cs moved from the TemplateTool-Program unit review to the TemplateTool-System review set
• TemplateTool-AllRequirements review set added covering requirements.yaml and all reqstream files
• Redundant Platform-Support review set removed (now covered by TemplateTool-System)

AGENTS.md updated

Added design/ folder entry under docs/ with introduction.md called out as the System/Subsystem/Unit breakdown reference (from TemplateDotNetLibrary#73).

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 unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.TemplateDotNetTool --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

No source code changes. All existing test/requirements traceability is preserved and extended; subsystem YAMLs reference existing passing tests, and all IntegrationTest_* tests are now linked as evidence for system-level requirements.

[Malcolmnixon]

@copilot Can you make sure you've correctly identified software-subsystems and software-units as unique items (read .github/standards/software-items.md) as both need requirements and design documentation markdown files. You should also read the .github/standards/reqstream-usage.md and .github/standards/reviewmark-usage.md files.

[Copilot]

@copilot Can you make sure you've correctly identified software-subsystems and software-units as unique items (read .github/standards/software-items.md) as both need requirements and design documentat...

Fixed in ffdfb2a. Per software-items.md, both subsystems and units require requirements files AND design documentation. The initial commit had subsystem requirements files but was missing subsystem design docs. Added:

• docs/design/cli/cli.md — Cli subsystem design (overview, units table, interfaces table, interactions)
• docs/design/self-test/self-test.md — SelfTest subsystem design
• docs/design/utilities/utilities.md — Utilities subsystem design

Also updated docs/design/definition.yaml to include the new subsystem docs in rendered order (each subsystem doc before its unit docs), and corrected the .reviewmark.yaml subsystem review sets to reference their own subsystem design docs (removed the incorrectly placed cross-subsystem program.md from the Cli review set).

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)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js -links', '/tmp/tmp2z6u8djh', '--upgrade', 'pip'] runpy.run_module("pip", run_name="__main__", a (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)

[Malcolmnixon]

@copilot If you examine https://github.com/demaconsulting/ReviewMark you'll notice that subsystems have tests to test the subsystem requirements, and the IntegrationTests tests the system requirements. Please review them and apply the same considerations to this repository (subsystem tests, integration tests, and test linkage to requirements).

[Copilot]

@copilot If you examine https://github.com/demaconsulting/ReviewMark you'll notice that subsystems have tests to test the subsystem requirements, and the IntegrationTests tests the system requirements...

Addressed in e4fc97f. Applied the same pattern as ReviewMark:

System requirements (docs/reqstream/templatetool-system.yaml, new): system-level requirements each linked to IntegrationTest_* tests — Version, Help, Validate (TRX + JUnit), Silent, Log, ErrorHandling.

Subsystem requirements — expanded to granular per-feature requirements linked to subsystem unit tests and integration tests:

• subsystem-cli.yaml: expanded from 1 coarse requirement to 10 (Context, Version, Help, Silent, Validate, Results, Log, ErrorOutput, InvalidArgs, ExitCode), each with context unit tests + relevant integration tests
• subsystem-self-test.yaml: added Template-SelfTest-ResultsOutput (linking to TRX/JUnit results tests + integration tests); fixed Template-SelfTest-Qualification test list

.reviewmark.yaml: added TemplateTool-System review set containing templatetool-system.yaml, platform requirements, design introduction, IntegrationTests.cs, Runner.cs, and AssemblyInfo.cs; moved those test infrastructure files out of the Program unit review; updated subsystem review sets to include unit design docs under each subsystem; added TemplateTool-AllRequirements review set; added requirements.yaml to needs-review.

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)

[Copilot]

Pull request overview

This PR reorganizes design documentation and ReqStream requirements into subsystem-aligned folder structures (Cli, SelfTest, Utilities) to mirror the source layout and improve review/traceability organization across requirements → design → tests.

Changes:

• Added system- and subsystem-level ReqStream YAML files and included them from requirements.yaml.
• Added subsystem/unit design markdown under docs/design/<subsystem>/ and updated docs/design/definition.yaml to include the new paths.
• Updated .reviewmark.yaml review sets to reflect the new documentation structure; updated AGENTS.md to document the design folder.

Reviewed changes

Copilot reviewed 11 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
requirements.yaml	Includes the new system + subsystem reqstream YAML files in the root include list.
docs/reqstream/templatetool-system.yaml	New system-level requirements linked to integration tests.
docs/reqstream/cli/subsystem-cli.yaml	New/expanded Cli subsystem requirements linked to unit + integration tests.
docs/reqstream/self-test/subsystem-self-test.yaml	New SelfTest subsystem requirements, including results output requirement.
docs/reqstream/utilities/subsystem-utilities.yaml	New Utilities subsystem requirements for safe path handling.
docs/design/definition.yaml	Adds subsystem design directories to resource-path and updates input-files ordering/paths.
docs/design/cli/cli.md	New Cli subsystem design doc.
docs/design/cli/context.md	New Context unit design doc under Cli subsystem.
docs/design/self-test/self-test.md	New SelfTest subsystem design doc.
docs/design/self-test/validation.md	New Validation unit design doc under SelfTest subsystem.
docs/design/utilities/utilities.md	New Utilities subsystem design doc.
docs/design/utilities/path-helpers.md	New PathHelpers unit design doc under Utilities subsystem.
.reviewmark.yaml	Adds requirements.yaml to review scope and updates/extends review-set groupings for system/subsystems.
AGENTS.md	Documents docs/design/ and points to introduction.md as the system/subsystem/unit breakdown reference.

---

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