Skip to content

sync template files and restructure docs/design, docs/reqstream, and docs/user_guide to new standards#176

Merged
Malcolmnixon merged 5 commits intomainfrom
copilot/copy-updated-files-from-template
Apr 5, 2026
Merged

sync template files and restructure docs/design, docs/reqstream, and docs/user_guide to new standards#176
Malcolmnixon merged 5 commits intomainfrom
copilot/copy-updated-files-from-template

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Apr 5, 2026

Pull Request

Description

Syncs updated agent/standards/lint files from the TemplateDotNetTool template, then restructures all design documentation, ReqStream requirements, ReviewMark configuration, and user guide to comply with the updated standards.

Template sync

Binary-copied from demaconsulting/TemplateDotNetTool:

  • AGENTS.md, .github/agents/*.md, .github/standards/*.md
  • lint.sh, lint.bat

Design doc restructure (docs/design/)

Files moved under system-named folders per design-documentation.md standard:

  • spdxtool-system.mdspdx-tool/spdx-tool.md
  • commands/*.mdspdx-tool/commands/*.md
  • self-test/*.mdspdx-tool/self-test/*.md
  • utility.mdspdx-tool/utility/utility.md
  • spdxtool-targets-system.mdspdx-tool-targets/spdx-tool-targets.md

ReqStream restructure (docs/reqstream/)

Same system-named folder reorganization per reqstream-usage.md standard. OTS folder stays at root level. New file added:

  • docs/reqstream/spdx-tool/commands/commands.yaml — Commands subsystem requirements linked to CommandTests.cs/UnknownCommandTests.cs

Requirement hierarchy corrections

Audited and corrected all test-links and children-links to respect the System → Subsystem → Unit hierarchy:

  • System requirements (spdx-tool.yaml): The --validate CLI requirements (SpdxTool-Cmd-Validate/Depth/ResultsTrx/ResultsJUnit) were moved from the SelfTest subsystem file into spdx-tool.yaml. They retain their IntegrationTests.cs system-level test links and now children:-link down to the corresponding SelfTest subsystem requirements.
  • SelfTest subsystem (self-test/self-test.yaml): Replaced with proper subsystem-level requirements (SpdxTool-SelfTest-Validate/Depth/ResultsTrx/ResultsJUnit) that link only to SelfTestTests.cs (subsystem tests calling Validate.Run() directly) and children:-link to the SpdxTool-ST-Orchestrate unit requirement. The validate.yaml orchestrator unit requirement was also corrected to link to SelfTestTests.cs instead of IntegrationTests.cs.
  • Command unit requirements (13 files): All command yaml files that were incorrectly linking to SpdxTool_* tests (in SelfTest/Validate*Tests.cs) have been updated to link exclusively to their corresponding Commands/*Tests.cs unit test methods.
  • Commands subsystem children-links: SpdxTool-Commands-Registry in commands.yaml now children:-links to all 18 command unit requirements.

User guide rename (docs/user_guide/)

Aligned repository layout with the technical-documentation.md standard:

  • docs/guide/docs/user_guide/
  • docs/user_guide/guide.mddocs/user_guide/introduction.md
  • Updated docs/user_guide/definition.yaml internal paths
  • Updated .reviewmark.yaml pattern from docs/guide/**/*.mddocs/user_guide/**/*.md
  • Updated .github/workflows/build.yaml Pandoc and Weasyprint references
  • Updated README.md [user-guide] link

requirements.yaml

All 38 include paths updated to new locations; commands.yaml added.

.reviewmark.yaml

Replaced 9 ad-hoc review-sets with 43 review-sets following the standard hierarchy:

  • Purpose (repo-wide)
  • Per-system: Architecture, Design, AllRequirements
  • Per-subsystem: Commands, SelfTest, Utility
  • Per-unit: 16 command units, 15 self-test units, 2 utility units, Context
  • OTS

Added docs/user_guide/**/*.md to needs-review: patterns so changes to the user guide correctly invalidate prior reviews.

Traceability fix (commands.yaml + CommandTests.cs)

Renamed the misleading test Command_GetMapString_MissingEntry_ThrowsExceptionCommand_GetMapString_MissingEntry_ReturnsNull to accurately reflect that the method returns null for missing entries (not throw). Updated the corresponding tests: link in commands.yaml for unambiguous requirement→test traceability.

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.SpdxTool --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

dotnet reqstream --lint passes cleanly after these changes.

Copilot AI and others added 2 commits April 5, 2026 15:36
Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/2d68e269-bffa-4090-8d83-493ea0bd5485

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
…andards

Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/b0d7cbbd-e149-4563-8535-5d05bee7e30f

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
@Malcolmnixon
Copy link
Copy Markdown
Member

@copilot Have you confirmed that all System requirements test-links only to the System dedicated test-suite (IntegrationTests) and 'children' requirements-links only to the subsystem or top-level unit requirements used to satisfy the system requirement.

Have you confirmed that all Subsystem requirements test-links only to the Subsystems dedicated test-suites and 'children' requirements-links only to the unit requirements used to satisfy the subsystem requirement.

Have you confirmed that all Unit requirements test-links only to the Units dedicated test-suites.

…erarchy standards

Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/0bfb938b-cb98-4f20-893f-8c78ca9abc15

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Apr 5, 2026

@copilot Have you confirmed that all System requirements test-links only to the System dedicated test-suite (IntegrationTests) and 'children' requirements-links only to the subsystem or top-level unit...

Fixed in commit 3a50d7d. The audit found three categories of violations that have been corrected:

System requirements (spdx-tool.yaml): The --validate CLI requirements (SpdxTool-Cmd-Validate/Depth/ResultsTrx/ResultsJUnit) were incorrectly placed in the SelfTest subsystem file and linked to IntegrationTests.cs system tests. These have been moved to spdx-tool.yaml, keep their links to IntegrationTests.cs (system-level), and now children:-link down to the new SelfTest subsystem requirements.

SelfTest subsystem requirements (self-test/self-test.yaml): Replaced with proper subsystem-level requirements (SpdxTool-SelfTest-Validate/Depth/ResultsTrx/ResultsJUnit) that link only to SelfTestTests.cs (subsystem-level tests calling Validate.Run() directly) and children:-link to the SpdxTool-ST-Orchestrate unit requirement. The validate.yaml orchestrator unit requirement was also fixed to link to SelfTestTests.cs instead of IntegrationTests.cs.

Command unit requirements (13 files): All command yaml files that were linking to SpdxTool_* tests (which are SelfTest/Validate*Tests.cs tests) have been updated to link exclusively to the corresponding Commands/*Tests.cs unit tests (e.g. AddPackage_InWorkflowWithRelationship_AddsPackageAndRelationship, Validate_ValidSpdxDocument_Succeeds, etc.).

Children-links: SpdxTool-Commands-Registry in commands.yaml now children:-links to all 18 command unit requirements, confirming that all registered commands are covered.

@Malcolmnixon Malcolmnixon self-requested a review April 5, 2026 16:33
@Malcolmnixon Malcolmnixon marked this pull request as ready for review April 5, 2026 16:33
Copilot AI review requested due to automatic review settings April 5, 2026 16:33
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR syncs agent/standards/linting files from the TemplateDotNetTool template and restructures the repository’s design and ReqStream documentation into the updated “system/subsystem/unit” folder hierarchy, including expanded ReviewMark review-sets.

Changes:

  • Restructured design docs under docs/design/{system}/... and ReqStream requirements under docs/reqstream/{system}/..., updating root requirements.yaml includes.
  • Added/updated subsystem + unit requirement YAMLs (Commands/SelfTest/Utility) and expanded .reviewmark.yaml into a full hierarchical review-set catalog.
  • Updated lint scripts and refreshed agent/standards guidance files from the template.

Reviewed changes

Copilot reviewed 35 out of 91 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
requirements.yaml Updates includes to new ReqStream hierarchy and adds Commands subsystem requirements include.
lint.sh Restructures lint execution into python/npm/dotnet sections with skip-on-failure behavior.
lint.bat Mirrors lint.sh structure for Windows with skip-on-failure sections.
docs/reqstream/spdx-tool/utility/utility.yaml Adds Utility subsystem requirements (SafePathCombine + Wildcard).
docs/reqstream/spdx-tool/spdx-tool.yaml Adds system-level CLI self-validation requirements and links to subsystem children.
docs/reqstream/spdx-tool/self-test/self-test.yaml Adds SelfTest subsystem-level requirements (validate/depth/results formats).
docs/reqstream/spdx-tool/self-test/validate.yaml Updates orchestrator unit requirement test links to SelfTest unit tests.
docs/reqstream/spdx-tool/self-test/validate-add-package.yaml Adds unit requirement for ValidateAddPackage step.
docs/reqstream/spdx-tool/self-test/validate-add-relationship.yaml Adds unit requirement for ValidateAddRelationship step.
docs/reqstream/spdx-tool/self-test/validate-basic.yaml Adds unit requirement for ValidateBasic step.
docs/reqstream/spdx-tool/self-test/validate-copy-package.yaml Adds unit requirement for ValidateCopyPackage step.
docs/reqstream/spdx-tool/self-test/validate-diagram.yaml Adds unit requirement for ValidateDiagram step.
docs/reqstream/spdx-tool/self-test/validate-find-package.yaml Adds unit requirement for ValidateFindPackage step.
docs/reqstream/spdx-tool/self-test/validate-get-version.yaml Adds unit requirement for ValidateGetVersion step.
docs/reqstream/spdx-tool/self-test/validate-hash.yaml Adds unit requirement for ValidateHash step.
docs/reqstream/spdx-tool/self-test/validate-ntia.yaml Adds unit requirement for ValidateNtia step.
docs/reqstream/spdx-tool/self-test/validate-query.yaml Adds unit requirement for ValidateQuery step.
docs/reqstream/spdx-tool/self-test/validate-rename-id.yaml Adds unit requirement for ValidateRenameId step.
docs/reqstream/spdx-tool/self-test/validate-run-nuget-workflow.yaml Adds unit requirement for ValidateRunNuGetWorkflow step.
docs/reqstream/spdx-tool/self-test/validate-to-markdown.yaml Adds unit requirement for ValidateToMarkdown step.
docs/reqstream/spdx-tool/self-test/validate-update-package.yaml Adds unit requirement for ValidateUpdatePackage step.
docs/reqstream/spdx-tool/commands/commands.yaml Adds Commands subsystem requirements and children-links to command units.
docs/reqstream/spdx-tool/commands/add-package.yaml Updates AddPackage unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/add-relationship.yaml Updates AddRelationship unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/copy-package.yaml Updates CopyPackage unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/diagram.yaml Updates Diagram unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/find-package.yaml Updates FindPackage unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/get-version.yaml Updates GetVersion unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/hash.yaml Updates Hash unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/help.yaml Adds Help unit requirement file in new location.
docs/reqstream/spdx-tool/commands/print.yaml Adds Print unit requirement file in new location.
docs/reqstream/spdx-tool/commands/query.yaml Updates Query unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/rename-id.yaml Updates RenameId unit requirement test links to command unit tests.
docs/reqstream/spdx-tool/commands/run-workflow.yaml Updates RunWorkflow unit requirement test links to RunWorkflow unit tests.
docs/reqstream/spdx-tool/commands/set-variable.yaml Adds SetVariable unit requirement file in new location.
docs/reqstream/spdx-tool/commands/to-markdown.yaml Updates ToMarkdown unit requirement test links to unit tests.
docs/reqstream/spdx-tool/commands/update-package.yaml Updates UpdatePackage unit requirement test links to unit tests.
docs/reqstream/spdx-tool/commands/validate.yaml Updates Validate unit requirement test links to Validate unit tests.
docs/reqstream/spdx-tool/platform-requirements.yaml Adds platform/runtime requirements with source-filtered test evidence.
docs/reqstream/spdx-tool-targets/spdx-tool-targets.yaml Adds Targets system requirements in new location.
docs/reqstream/self-test/self-test.yaml Removes old SelfTest requirements file from prior hierarchy.
docs/design/introduction.md Updates documented design/reqstream paths to new hierarchy.
docs/design/spdx-tool/spdx-tool.md Adds system-level design doc in new folder structure.
docs/design/spdx-tool/utility/utility.md Adds Utility subsystem design doc.
docs/design/spdx-tool/self-test/self-test.md Adds SelfTest subsystem design doc.
docs/design/spdx-tool/self-test/validate.md Adds SelfTest orchestrator (Validate.cs) unit design doc.
docs/design/spdx-tool/self-test/validate-add-package.md Adds unit design doc for ValidateAddPackage.
docs/design/spdx-tool/self-test/validate-add-relationship.md Adds unit design doc for ValidateAddRelationship.
docs/design/spdx-tool/self-test/validate-basic.md Adds unit design doc for ValidateBasic.
docs/design/spdx-tool/self-test/validate-copy-package.md Adds unit design doc for ValidateCopyPackage.
docs/design/spdx-tool/self-test/validate-diagram.md Adds unit design doc for ValidateDiagram.
docs/design/spdx-tool/self-test/validate-find-package.md Adds unit design doc for ValidateFindPackage.
docs/design/spdx-tool/self-test/validate-get-version.md Adds unit design doc for ValidateGetVersion.
docs/design/spdx-tool/self-test/validate-hash.md Adds unit design doc for ValidateHash.
docs/design/spdx-tool/self-test/validate-ntia.md Adds unit design doc for ValidateNtia.
docs/design/spdx-tool/self-test/validate-query.md Adds unit design doc for ValidateQuery.
docs/design/spdx-tool/self-test/validate-rename-id.md Adds unit design doc for ValidateRenameId.
docs/design/spdx-tool/self-test/validate-run-nuget-workflow.md Adds unit design doc for ValidateRunNuGetWorkflow.
docs/design/spdx-tool/self-test/validate-to-markdown.md Adds unit design doc for ValidateToMarkdown.
docs/design/spdx-tool/self-test/validate-update-package.md Adds unit design doc for ValidateUpdatePackage.
docs/design/spdx-tool/commands/commands.md Adds Commands subsystem design doc.
docs/design/spdx-tool/commands/add-package.md Adds AddPackage unit design doc.
docs/design/spdx-tool/commands/add-relationship.md Adds AddRelationship unit design doc.
docs/design/spdx-tool/commands/copy-package.md Adds CopyPackage unit design doc.
docs/design/spdx-tool/commands/diagram.md Adds Diagram unit design doc.
docs/design/spdx-tool/commands/find-package.md Adds FindPackage unit design doc.
docs/design/spdx-tool/commands/get-version.md Adds GetVersion unit design doc.
docs/design/spdx-tool/commands/hash.md Adds Hash unit design doc.
docs/design/spdx-tool/commands/help.md Adds Help unit design doc.
docs/design/spdx-tool/commands/print.md Adds Print unit design doc.
docs/design/spdx-tool/commands/query.md Adds Query unit design doc.
docs/design/spdx-tool/commands/rename-id.md Adds RenameId unit design doc.
docs/design/spdx-tool/commands/run-workflow.md Adds RunWorkflow unit design doc.
docs/design/spdx-tool/commands/set-variable.md Adds SetVariable unit design doc.
docs/design/spdx-tool/commands/to-markdown.md Adds ToMarkdown unit design doc.
docs/design/spdx-tool/commands/update-package.md Adds UpdatePackage unit design doc.
docs/design/spdx-tool/commands/validate.md Adds Validate unit design doc.
docs/design/spdx-tool-targets/spdx-tool-targets.md Adds Targets system design doc.
AGENTS.md Updates agent guidance and repository structure references to new standards.
.reviewmark.yaml Replaces ad-hoc review-sets with a hierarchical set covering systems/subsystems/units.
.github/standards/technical-documentation.md Updates documentation layout standard to system-folder hierarchy.
.github/standards/design-documentation.md Updates design doc layout standard to system-folder hierarchy.
.github/standards/reqstream-usage.md Updates ReqStream folder hierarchy + clarifies test-linkage hierarchy.
.github/standards/reviewmark-usage.md Updates ReviewMark guidance to hierarchical review-set structure.
.github/standards/software-items.md Adds naming guidance when hierarchy name collisions occur.
.github/standards/csharp-testing.md Updates AAA guidance and adds hierarchical test naming patterns.
.github/agents/repo-consistency.agent.md Syncs agent report template placeholders/formatting.
.github/agents/quality.agent.md Adds explicit Result field requirement and normalizes placeholders.
.github/agents/implementation.agent.md Clarifies orchestrator context requirements and normalizes placeholders.
.github/agents/developer.agent.md Adds lint-fix step requirement and normalizes placeholders.
.github/agents/code-review.agent.md Normalizes placeholders and clarifies elaborate command formatting.

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

@Malcolmnixon
Copy link
Copy Markdown
Member

@copilot apply changes based on the comments in this thread

…on.md

Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/ee10c32f-291a-48b8-9984-34bcc3958200

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Apr 5, 2026

@copilot apply changes based on the comments in this thread

Applied in commit 01ad6d7: renamed docs/guide/docs/user_guide/ and guide.mdintroduction.md, updating all references across definition.yaml, .reviewmark.yaml, build.yaml, and README.md.

Copilot AI changed the title sync template files and restructure docs/design + docs/reqstream to new standards sync template files and restructure docs/design, docs/reqstream, and docs/user_guide to new standards Apr 5, 2026
@Malcolmnixon Malcolmnixon requested a review from Copilot April 5, 2026 17:08
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 38 out of 96 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (4)

docs/reqstream/spdx-tool/commands/get-version.yaml:18

  • The referenced test GetVersion_OnCommandLine_ReportsWorkflowOnlyError is misnamed: it asserts a successful CLI invocation and checks the returned version string (exit code 0). Since ReqStream evidence and review artifacts surface test names, this is likely to confuse auditors/readers. Rename the test to reflect its behavior (and update this tests: link), or link to a correctly named test if one exists.
    docs/reqstream/spdx-tool/commands/find-package.yaml:18
  • The referenced test FindPackage_OnCommandLine_ReportsWorkflowOnlyError is misnamed: it asserts a successful CLI invocation and checks the returned package ID (exit code 0). Since ReqStream evidence and review artifacts surface test names, this is likely to confuse auditors/readers. Rename the test to reflect its behavior (and update this tests: link), or link to a correctly named test if one exists.
    docs/reqstream/spdx-tool/commands/copy-package.yaml:18
  • The referenced test CopyPackage_OnCommandLine_ReportsWorkflowOnlyError is misnamed: it asserts a successful CLI invocation and verifies the destination SPDX now contains both packages (exit code 0). Since ReqStream evidence and review artifacts surface test names, this is likely to confuse auditors/readers. Rename the test to reflect its behavior (and update this tests: link), or link to a correctly named test if one exists.
    docs/reqstream/spdx-tool/commands/add-relationship.yaml:20
  • The referenced test AddRelationship_OnCommandLine_ReportsWorkflowOnlyError is misnamed: it asserts a successful CLI invocation and verifies the relationship was added (exit code 0). Since ReqStream evidence and review artifacts surface test names, this is likely to confuse auditors/readers. Rename the test to reflect its behavior (and update this tests: link), or link to a correctly named test if one exists.

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

@Malcolmnixon
Copy link
Copy Markdown
Member

@copilot apply changes based on the comments in this thread

Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/32af83d4-f78d-4562-942b-4dae1f07732e

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Apr 5, 2026

@copilot apply changes based on the comments in this thread

Done in commit 606e76c:

  • Renamed Command_GetMapString_MissingEntry_ThrowsExceptionCommand_GetMapString_MissingEntry_ReturnsNull in CommandTests.cs and updated the matching test link in commands.yaml
  • Added docs/user_guide/**/*.md to needs-review: in .reviewmark.yaml so user guide changes correctly invalidate prior reviews

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 39 out of 97 changed files in this pull request and generated no new comments.


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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants