sync template files and restructure docs/design, docs/reqstream, and docs/user_guide to new standards#176
Conversation
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>
|
@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>
Fixed in commit 3a50d7d. The audit found three categories of violations that have been corrected: System requirements ( SelfTest subsystem requirements ( Command unit requirements (13 files): All command yaml files that were linking to Children-links: |
There was a problem hiding this comment.
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 underdocs/reqstream/{system}/..., updating rootrequirements.yamlincludes. - Added/updated subsystem + unit requirement YAMLs (Commands/SelfTest/Utility) and expanded
.reviewmark.yamlinto 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.
|
@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>
Applied in commit 01ad6d7: renamed |
There was a problem hiding this comment.
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_ReportsWorkflowOnlyErroris 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 thistests: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_ReportsWorkflowOnlyErroris 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 thistests: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_ReportsWorkflowOnlyErroris 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 thistests: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_ReportsWorkflowOnlyErroris 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 thistests: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.
|
@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>
Done in commit 606e76c:
|
There was a problem hiding this comment.
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.
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/*.mdlint.sh,lint.batDesign doc restructure (
docs/design/)Files moved under system-named folders per
design-documentation.mdstandard:spdxtool-system.md→spdx-tool/spdx-tool.mdcommands/*.md→spdx-tool/commands/*.mdself-test/*.md→spdx-tool/self-test/*.mdutility.md→spdx-tool/utility/utility.mdspdxtool-targets-system.md→spdx-tool-targets/spdx-tool-targets.mdReqStream restructure (
docs/reqstream/)Same system-named folder reorganization per
reqstream-usage.mdstandard. OTS folder stays at root level. New file added:docs/reqstream/spdx-tool/commands/commands.yaml— Commands subsystem requirements linked toCommandTests.cs/UnknownCommandTests.csRequirement hierarchy corrections
Audited and corrected all test-links and children-links to respect the System → Subsystem → Unit hierarchy:
spdx-tool.yaml): The--validateCLI requirements (SpdxTool-Cmd-Validate/Depth/ResultsTrx/ResultsJUnit) were moved from the SelfTest subsystem file intospdx-tool.yaml. They retain theirIntegrationTests.cssystem-level test links and nowchildren:-link down to the corresponding SelfTest subsystem requirements.self-test/self-test.yaml): Replaced with proper subsystem-level requirements (SpdxTool-SelfTest-Validate/Depth/ResultsTrx/ResultsJUnit) that link only toSelfTestTests.cs(subsystem tests callingValidate.Run()directly) andchildren:-link to theSpdxTool-ST-Orchestrateunit requirement. Thevalidate.yamlorchestrator unit requirement was also corrected to link toSelfTestTests.csinstead ofIntegrationTests.cs.SpdxTool_*tests (inSelfTest/Validate*Tests.cs) have been updated to link exclusively to their correspondingCommands/*Tests.csunit test methods.SpdxTool-Commands-Registryincommands.yamlnowchildren:-links to all 18 command unit requirements.User guide rename (
docs/user_guide/)Aligned repository layout with the
technical-documentation.mdstandard:docs/guide/→docs/user_guide/docs/user_guide/guide.md→docs/user_guide/introduction.mddocs/user_guide/definition.yamlinternal paths.reviewmark.yamlpattern fromdocs/guide/**/*.md→docs/user_guide/**/*.md.github/workflows/build.yamlPandoc and Weasyprint referencesREADME.md[user-guide]linkrequirements.yamlAll 38 include paths updated to new locations;
commands.yamladded..reviewmark.yamlReplaced 9 ad-hoc review-sets with 43 review-sets following the standard hierarchy:
Purpose(repo-wide)Architecture,Design,AllRequirementsCommands,SelfTest,UtilityContextOTSAdded
docs/user_guide/**/*.mdtoneeds-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_ThrowsException→Command_GetMapString_MissingEntry_ReturnsNullto accurately reflect that the method returns null for missing entries (not throw). Updated the correspondingtests:link incommands.yamlfor unambiguous requirement→test traceability.Type of Change
Related Issues
Pre-Submission Checklist
Before submitting this pull request, ensure you have completed the following:
Build and Test
dotnet build --configuration Releasedotnet test --configuration Releasedotnet run --project src/DemaConsulting.SpdxTool --configuration Release --framework net10.0--no-build -- --validateCode Quality
dotnet format --verify-no-changesQuality Checks
Please run the following checks before submitting:
./lint.sh(Unix/macOS) orcmd /c lint.bat/./lint.bat(Windows)Testing
Documentation
Additional Notes
dotnet reqstream --lintpasses cleanly after these changes.