Update for SysML2 changes and enhance design/verification documentation - #54
Merged
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Introduce sysml2tools: pin in .config/dotnet-tools.json and .versionmark.yaml, wire lint into lint.ps1, and run render in build.yaml. - Add docs/sysml2/model (system, subsystems, units, OTS parts) and docs/sysml2/views/design-views.sysml, matching the FileAssert precedent. - Extensively rewrite docs/design/introduction.md and docs/verification/introduction.md to describe the SysML2 model, clarify OTS documentation scope (source-integrated vs. build-pipeline-only tooling), and reference the sysml2tools-query skill. - Rewrite .reviewmark.yaml with review-sets aligned to the new SysML2-driven structure. - Add design/verification/reqstream companion docs for the SysML2Tools, NuGet.Caching, and TestResults OTS items. - Split non-standard composite (tests-less) requirement nodes into atomic parent/child requirements to satisfy the every-requirement-has-a-test quality gate, and fix a PathHelpers.SafePathCombine absolute-path bypass found during formal review, plus assorted design/verification documentation accuracy fixes. - Bump DemaConsulting.NuGet.Caching to 1.3.0 (authentication bug-fix release). All 16 formal-review sets and the change-review agent pass; full build, test suite (270 tests), reqstream, reviewmark, and lint.ps1 are clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Another authentication-related bug-fix release. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends NuGet Cache Tool’s Continuous Compliance workflow by introducing SysML2 modeling support (model sources, linting, rendering, and verification evidence) and aligning agent/standards documentation to consistently track requirements/design/verification artifacts. It also tightens path-safety behavior and strengthens self-test validation so it verifies real cached package paths.
Changes:
- Add SysML2 architecture model sources + CI integration (lint, render, self-validation) and companion OTS requirements/design/verification artifacts.
- Update PathHelpers to reject rooted “relative” paths and enhance self-test cache-package validation to verify a real cached directory exists.
- Standardize/modernize tests and documentation to rely on ReqStream trace matrices (removing embedded “Requirements Coverage” lists in many docs).
Reviewed changes
Copilot reviewed 98 out of 98 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/DemaConsulting.NuGet.CacheTool.Tests/Utilities/UtilitiesTests.cs | Refactors assertions to explicit AAA style; adjusts temp-dir lifecycle test. |
| test/DemaConsulting.NuGet.CacheTool.Tests/Utilities/TemporaryDirectoryTests.cs | Renames tests and adds constructor-failure test with OS-specific permission manipulation. |
| test/DemaConsulting.NuGet.CacheTool.Tests/Utilities/PathHelpersTests.cs | Adds rooted-path rejection test and refactors AAA structure. |
| test/DemaConsulting.NuGet.CacheTool.Tests/SelfTest/ValidationTests.cs | Adds regression test ensuring cache-package self-test success is meaningful. |
| test/DemaConsulting.NuGet.CacheTool.Tests/SelfTest/SelfTestTests.cs | Adds unsupported results-extension scenario coverage. |
| test/DemaConsulting.NuGet.CacheTool.Tests/ProgramTests.cs | Minor AAA comment consistency. |
| test/DemaConsulting.NuGet.CacheTool.Tests/IntegrationTests.cs | Ensures temp file created by GetTempFileName() is cleaned up after extension change. |
| test/DemaConsulting.NuGet.CacheTool.Tests/Cli/ContextTests.cs | Refactors AAA sections and strengthens assertion structure in a few tests. |
| src/DemaConsulting.NuGet.CacheTool/Utilities/TemporaryDirectory.cs | Documents thread-safety expectations and wraps directory-creation failures. |
| src/DemaConsulting.NuGet.CacheTool/Utilities/PathHelpers.cs | Rejects rooted relativePath up front before combining paths. |
| src/DemaConsulting.NuGet.CacheTool/SelfTest/Validation.cs | Improves cache-package validator to extract/validate a real cached directory path. |
| src/DemaConsulting.NuGet.CacheTool/DemaConsulting.NuGet.CacheTool.csproj | Updates DemaConsulting.NuGet.Caching dependency version. |
| requirements.yaml | Adds SysML2Tools OTS requirements include. |
| lint.ps1 | Adds sysml2tools lint step for docs/sysml2/**/*.sysml. |
| docs/verification/ots/xunit.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/weasyprint.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/versionmark.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/test-results.md | Adds OTS verification evidence for DemaConsulting.TestResults. |
| docs/verification/ots/sysml2tools.md | Adds OTS verification evidence for SysML2Tools. |
| docs/verification/ots/sonarmark.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/sarifmark.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/reviewmark.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/reqstream.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/pandoc.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/nuget-caching.md | Adds OTS verification evidence for DemaConsulting.NuGet.Caching. |
| docs/verification/ots/fileassert.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots/buildmark.md | Removes embedded requirements-coverage list; keeps scenario-based verification content. |
| docs/verification/ots.md | Expands OTS table to include new OTS items (SysML2Tools, runtime deps). |
| docs/verification/nuget-cache-tool/utilities/temporary-directory.md | Updates scenarios + removes embedded requirements-coverage list in favor of ReqStream matrix. |
| docs/verification/nuget-cache-tool/utilities/path-helpers.md | Adds rooted-path scenario; removes embedded requirements-coverage list. |
| docs/verification/nuget-cache-tool/utilities.md | Updates acceptance criteria to reference ReqStream matrix instead of inline mapping. |
| docs/verification/nuget-cache-tool/self-test/validation.md | Removes embedded requirements-coverage list in favor of ReqStream matrix. |
| docs/verification/nuget-cache-tool/self-test.md | Adds unsupported results-extension scenario and removes embedded mapping. |
| docs/verification/nuget-cache-tool/program.md | Removes embedded requirements-coverage list in favor of ReqStream matrix. |
| docs/verification/nuget-cache-tool/cli/context.md | Splits invalid-argument coverage into more specific requirement IDs. |
| docs/verification/nuget-cache-tool/cli.md | Updates wording to scenario-based verification; removes embedded mapping. |
| docs/verification/nuget-cache-tool.md | Renames sections and clarifies limitations of merged stdout/stderr in integration tests. |
| docs/verification/introduction.md | Re-scopes OTS coverage and clarifies where pipeline-only OTS verification lives. |
| docs/verification/definition.yaml | Adds new OTS verification docs to Pandoc inputs. |
| docs/sysml2/views/design-views.sysml | Defines SysML2 views rendered into design documentation diagrams. |
| docs/sysml2/model/ots.sysml | Models runtime OTS dependencies (NuGet.Caching, TestResults) and artifact refs. |
| docs/sysml2/model/nuget-cache-tool/utilities/temporary-directory.sysml | Adds SysML2 part def + artifact-location comments for TemporaryDirectory. |
| docs/sysml2/model/nuget-cache-tool/utilities/path-helpers.sysml | Adds SysML2 part def + artifact-location comments for PathHelpers. |
| docs/sysml2/model/nuget-cache-tool/utilities.sysml | Adds SysML2 Utilities subsystem composition. |
| docs/sysml2/model/nuget-cache-tool/self-test/validation.sysml | Adds SysML2 part def + artifact-location comments for Validation unit. |
| docs/sysml2/model/nuget-cache-tool/self-test.sysml | Adds SysML2 SelfTest subsystem composition. |
| docs/sysml2/model/nuget-cache-tool/program.sysml | Adds SysML2 part def + artifact-location comments for Program unit. |
| docs/sysml2/model/nuget-cache-tool/cli/context.sysml | Adds SysML2 part def + artifact-location comments for Context unit. |
| docs/sysml2/model/nuget-cache-tool/cli.sysml | Adds SysML2 CLI subsystem composition. |
| docs/sysml2/model/nuget-cache-tool.sysml | Adds SysML2 system model (parts for subsystems/units + runtime OTS). |
| docs/reqstream/ots/test-results.yaml | Splits TestResults requirement into TRX vs JUnit requirements with distinct tests. |
| docs/reqstream/ots/sysml2tools.yaml | Adds SysML2Tools OTS requirements (lint + render). |
| docs/reqstream/nuget-cache-tool/utilities/temporary-directory.yaml | Re-structures and expands requirements (constructor failure + disposal split). |
| docs/reqstream/nuget-cache-tool/utilities.yaml | Updates referenced TemporaryDirectory requirement IDs and adds new ones. |
| docs/reqstream/nuget-cache-tool/program.yaml | Updates child requirement reference to new invalid-argument requirement ID. |
| docs/reqstream/nuget-cache-tool/cli/context.yaml | Splits invalid-argument requirement into specific cases with per-test mapping. |
| docs/reqstream/nuget-cache-tool/cli.yaml | Updates invalid-argument hierarchy and clarifies stderr requirement wording. |
| docs/reqstream/nuget-cache-tool.yaml | Refines system-level invalid-argument and stderr/log interaction narratives and child links. |
| docs/design/ots/test-results.md | Updates design to match new serializer usage (string-returning APIs). |
| docs/design/ots/sysml2tools.md | Adds SysML2Tools OTS design and pipeline integration pattern. |
| docs/design/ots/nuget-caching.md | Renames headings and removes “version constraints” section. |
| docs/design/ots.md | Expands OTS overview to include SysML2Tools and clarifies qualification strategy. |
| docs/design/nuget-cache-tool/utilities/temporary-directory.md | Embeds UtilitiesView diagram in unit design doc. |
| docs/design/nuget-cache-tool/utilities/path-helpers.md | Updates algorithm description for rooted-path rejection and adds callers/dependencies sections. |
| docs/design/nuget-cache-tool/utilities.md | Embeds UtilitiesView diagram in subsystem design doc. |
| docs/design/nuget-cache-tool/self-test/validation.md | Updates data model description + embeds SelfTestView diagram. |
| docs/design/nuget-cache-tool/self-test.md | Embeds SelfTestView diagram and clarifies Validation output semantics. |
| docs/design/nuget-cache-tool/program.md | Embeds NuGetCacheToolView diagram and renames “Interactions” section to “Dependencies”. |
| docs/design/nuget-cache-tool/cli/context.md | Embeds CliView diagram; updates error-handling exception type; adds callers/dependencies. |
| docs/design/nuget-cache-tool/cli.md | Embeds CliView diagram and clarifies dependency directionality wording. |
| docs/design/nuget-cache-tool.md | Embeds NuGetCacheToolView diagram and refines interface text (stderr behavior). |
| docs/design/introduction.md | Replaces ASCII structure with SysML2-rendered diagram and expands scope explanation. |
| docs/design/definition.yaml | Adds docs/design/generated resource path and includes SysML2Tools OTS design doc. |
| AGENTS.md | Updates repo metadata keys, adds US English rule, and prioritizes SysML2 model as navigation aid. |
| .versionmark.yaml | Adds sysml2tools tool-version capture regex. |
| .reviewmark.yaml | Adds sysml2 paths + reorganizes review sets and adds context files. |
| .github/workflows/build.yaml | Adds sysml2tools to captured versions; adds sysml2tools self-validation + render steps. |
| .github/standards/verification-documentation.md | Updates mandatory sections and removes inline requirements-coverage mapping requirement. |
| .github/standards/testing-principles.md | Minor cleanup of introductory text. |
| .github/standards/technical-documentation.md | Streamlines guidance and clarifies ordering and formatting rules. |
| .github/standards/sysml2-modeling.md | Adds SysML2 modeling standard (structure, view conventions, embedding rules). |
| .github/standards/software-items.md | Clarifies placeholder forms and adds SysML2 comment metadata guidance reference. |
| .github/standards/reviewmark-usage.md | Updates ReviewMark guidance (context files, review set organization, sysml2 inclusion). |
| .github/standards/reqstream-usage.md | Updates section nesting guidance and traceability expectations. |
| .github/standards/design-documentation.md | Updates required “Software Structure” to be SysML2-derived; adds “Dependencies/Callers” convention. |
| .github/standards/csharp-testing.md | Minor cleanup of redundant headings. |
| .github/standards/csharp-language.md | Minor cleanup of redundant headings. |
| .github/standards/coding-principles.md | Minor cleanup/clarification of anti-patterns and documentation requirements. |
| .github/skills/sysml2tools-query/SKILL.md | Adds skill guide for querying SysML2 model. |
| .github/agents/template-sync.agent.md | Expands template-sync scope to include sysml2 and clarifies orchestration/reporting. |
| .github/agents/quality.agent.md | Adds verification-doc compliance section and planning artifact cross-referencing. |
| .github/agents/planning.agent.md | Introduces new planning agent definition and report template. |
| .github/agents/lint-fix.agent.md | Standardizes report template to include **Report** path. |
| .github/agents/implementation.agent.md | Updates implementation agent to use new planning agent and standardized reporting. |
| .github/agents/formal-review.agent.md | Standardizes report template and clarifies review flow. |
| .github/agents/developer.agent.md | Adds verification/docs/readme/user guide to companion-artifact expectations; standardizes report template. |
| .cspell.yaml | Adds sysml/sysml2tools dictionary entries. |
| .config/dotnet-tools.json | Adds demaconsulting.sysml2tools.tool local tool definition. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ssues - Remove TemporaryDirectory_Constructor_DirectoryCreationFails_ThrowsInvalidOperationException and its OS-permission-manipulation helpers (icacls on Windows, chmod-equivalent on Unix). Forcing Directory.CreateDirectory to fail via real filesystem permission changes is flaky and platform-fragile (confirmed by GitHub's automated PR review flagging both the Environment.UserName identity assumption and the unread icacls process streams/exit code). The constructor's InvalidOperationException wrapping is now documented as a defensive guard verified by code inspection rather than an automated test. - Remove the corresponding NuGetCache-TemporaryDirectory-Constructor-CreationFailure requirement and its children-list reference, and update the design/verification docs accordingly. - Fix design-doc accuracy issues found during Design/Architecture re-review: remove an embedded literal version number from the CachePackage self-test table row (design docs must not embed version numbers), remove an inaccurate PathHelpers Callers entry from Context's design doc, and clarify docs/design/introduction.md's Scope section to explicitly call out SysML2Tools as the one build-time-only OTS tool with a dedicated design document. - Add 'unwritable' to the cspell dictionary. All affected formal-review sets (Utilities-TemporaryDirectory, Design, Architecture) re-verified clean; build and full test suite (267 tests) pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…r leaks - docs/verification/introduction.md: correct Scope wording so SysML2Tools is described as build/pipeline-integrated only (invoked via lint.ps1 and build.yaml), not source-integrated like the two runtime OTS packages; explicitly exclude the test project from scope per standard. - docs/verification/nuget-cache-tool/self-test/validation.md: add missing Validation_Run_CachePackageSelfTest_PassesWithRealCachedPackagePath scenario. - TemporaryDirectoryTests.cs, UtilitiesTests.cs: wrap TemporaryDirectory usage in try/finally so the directory is not leaked if an assertion or setup step throws before the explicit Dispose() call. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…l review - docs/design/nuget-cache-tool/cli.md: correct SelfTest dependency direction from Upstream to Downstream (pre-existing error from the original SysML2 rollout, caught by both a local code-review pass and GitHub PR review). - docs/reqstream/nuget-cache-tool/self-test/validation.yaml: add missing Validation_Run_CachePackageSelfTest_PassesWithRealCachedPackagePath test linkage to NuGetCache-Validation-SelfValidation requirement. - TemporaryDirectoryTests.cs, UtilitiesTests.cs: route finally-block cleanup through tmpDir.Dispose() (idempotent, suppresses non-fatal IO errors) instead of calling Directory.Delete directly, avoiding cleanup exceptions masking real assertion failures. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ments
- docs/verification/nuget-cache-tool/{program,self-test,cli/context,
self-test/validation,utilities/path-helpers}.md: Acceptance Criteria
bullets still referenced the removed 'Requirements Coverage' section;
reworded to reference the ReqStream trace matrix instead, matching the
convention already used in utilities/temporary-directory.md.
- docs/verification/nuget-cache-tool/self-test/validation.md: corrected
Test Environment claim that no network connectivity is required — the
CachePackageSelfTest scenario may need network access to cache a package
not already present locally.
- docs/reqstream/nuget-cache-tool.yaml,
docs/reqstream/nuget-cache-tool/platform-requirements.yaml: reworded
compound 'shall build and run' platform requirements to 'shall run',
since the linked per-platform test evidence only proves runtime
execution, not build success.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
test/DemaConsulting.NuGet.CacheTool.Tests/Cli/ContextTests.cs: Context_Create_WithoutColonInPackage_ThrowsArgumentException asserted only Assert.NotNull(exception), which Assert.Throws already guarantees and does not verify the diagnostic message. Changed to assert the exception message contains 'Unsupported argument', matching the sibling Context_Create_UnknownArgument_ThrowsArgumentException test, since both invalid-argument paths share the same throw site in Context.cs's parser. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…sign docs docs/design/ots.md and docs/design/ots/sysml2tools.md described SysML2Tools as a '.NET dotnet global tool' in four places, contradicting the correct statement elsewhere in the same files that it is installed as a .NET local tool pinned in .config/dotnet-tools.json and restored with 'dotnet tool restore' (never 'dotnet tool install -g'). All four references corrected to 'local tool'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
RunCachePackageTest previously used Contains-based substring matching to verify a cached package path referenced the expected package id/version, which could produce false positives (e.g. version '0.1.0' matching '0.1.0-beta' or '10.1.0'). Extracted the check into an internal ValidateCachePackagePath method that compares the directory name (version) and parent directory name (package id) exactly, case-insensitively. Added direct unit tests for ValidateCachePackagePath covering exact match, version-suffix and version-prefix substring collisions, and wrong package id, so a regression to substring matching would be caught even though the existing integration-style test only asserts on printed text and exit code. Updated design doc, verification doc, and reqstream traceability for the new method and tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
docs/design/nuget-cache-tool/cli/context.md's Error Handling section said Program.Main only catches ArgumentException, but Program.Main also catches InvalidOperationException (e.g. when the log file cannot be opened). Updated the doc to describe both exception types. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…y tests The nullable-returning Path.GetFileName/Path.GetDirectoryName results were previously assigned to var-typed locals. While this compiles cleanly with 0 warnings (var infers the correct nullable type and string.Equals safely handles null), a PR reviewer raised nullability-clarity concerns. Made the nullability explicit with string? declarations and an explicit null-check before combining GetDirectoryName with GetFileName. Added two new boundary-case unit tests: one exercising the genuine null-parent-directory branch (root path '/'), and one exercising the distinct empty-string-parent-directory case (bare relative name '0.1.0'). A local code-review agent caught that the original single test used the wrong input to claim null-branch coverage; corrected before landing. Updated design/verification docs and reqstream traceability for the two new tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces significant improvements to the agent orchestration and quality assurance workflow, with a focus on more rigorous planning, companion artifact tracking, and reporting. It adds a new custom planning agent, updates the implementation and quality agents to use its outputs, and enhances the handling of verification documentation and user-facing artifacts. Several agent report templates are standardized, and additional support for SysML2 tooling is included.
Key changes include:
Agent Workflow and Planning Enhancements
planningagent (.github/agents/planning.agent.md) that investigates the codebase, produces a verified implementation plan, identifies all required companion artifacts, and rates assumptions and risks. The agent saves a detailed report and provides a structured summary for downstream agents.Quality Assurance and Artifact Coverage
**Report**field with the path to the saved log file for traceability. [1] [2] [3]Template Synchronization and Standards
docs/sysml2/for SysML2 models and views, and clarifies groupings for root files indocs/design/,docs/verification/, anddocs/reqstream/. Standards selection and template matching logic are improved.Tooling and Spellchecking
demaconsulting.sysml2tools.toolto.config/dotnet-tools.jsonfor SysML2 model processing..cspell.yamlto recognizesysmlandsysml2toolsas valid words.