Add SysML2 model support and restructure related documentation#115
Merged
Conversation
- Scaffold docs/sysml2/ model and design-views with sysml2tools wired into lint.ps1, build.yaml, .config/dotnet-tools.json, .versionmark.yaml - Refactor docs/design/introduction.md to reference the generated SoftwareStructureView diagram instead of a hand-maintained tree, and clarify that OTS dependencies are documented separately and intentionally not modeled as SysML2 parts (build-time/pipeline tooling, not runtime composition) - Embed per-subsystem/unit diagrams across docs/design/template-dot-net-tool/** - Rework .reviewmark.yaml to add docs/sysml2/**/*.sysml to needs-review and add the OTS-SysML2Tools review-set - Document SysML2Tools as an OTS dependency: docs/reqstream/ots/sysml2tools.yaml, docs/design/ots/sysml2tools.md, docs/verification/ots/sysml2tools.md, wired into requirements.yaml, design/verification definition.yaml manifests, and ots.md summary pages - Add sysml, sysml2tools, demaconsulting to .cspell.yaml word list - Bring in agents/standards/skills prep for the SysML2 upgrade (AGENTS.md, sysml2-modeling.md standard, sysml2tools-query skill, updated design-documentation.md/reviewmark-usage.md/software-items.md standards, template-sync.agent.md, removal of unused cpp-language.md/cpp-testing.md standards) Verified via dotnet sysml2tools lint/render, dotnet reqstream/versionmark/ reviewmark --lint, pwsh ./lint.ps1, and a change-review + 11 formal-review passes (gpt-5.4-mini) across every affected review-set; all in-scope findings resolved (remaining findings in Utilities/SelfTest/Cli/Design review-sets are pre-existing issues unrelated to this change). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…style - Trim the Scope section's local-items enumeration to a terser one-liner (matching the template's example and FileAssert's pattern) instead of listing every subsystem/unit individually - Remove the redundant OTS Dependencies bullet list and trailing sentence that followed the Software Structure diagram - that information already lives in Scope, and the template's Software Structure section is only the directing paragraph plus the rendered diagram - Convert Folder Layout from a hand-drawn fenced-tree to the template's bullet-list format - Align Purpose/opening paragraph wording with the template's example phrasing Re-verified clean by the change-review and Decomposition formal-review agents (gpt-5.4-mini) after this restructure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds first-class SysML2 model support to make docs/sysml2/ the authoritative, queryable source for software structure, and wires SysML2 validation/rendering into existing compliance and documentation pipelines.
Changes:
- Introduces a SysML2 model + rendered views (
docs/sysml2/**) and embeds generated SVG diagrams into design documentation. - Adds/pins
sysml2toolsas a local .NET tool and integrates linting/rendering/self-validation intolint.ps1and the CI workflow. - Updates standards, ReviewMark review scopes, and ReqStream/verification/design OTS artifacts to include SysML2Tools; removes C++ standards docs.
Reviewed changes
Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| requirements.yaml | Includes SysML2Tools OTS requirements in the root ReqStream include list. |
| lint.ps1 | Runs sysml2tools lint during the compliance-tools lint phase (when docs/sysml2 exists). |
| docs/verification/ots/sysml2tools.md | Adds SysML2Tools OTS verification evidence document. |
| docs/verification/ots.md | Adds SysML2Tools to the OTS verification evidence index. |
| docs/verification/introduction.md | Updates verification scope to include SysML2Tools; removes the hand-maintained software-structure tree section. |
| docs/verification/definition.yaml | Adds the SysML2Tools verification evidence file to the verification document build inputs. |
| docs/sysml2/views/design-views.sysml | Declares named SysML2 views to render for design diagrams. |
| docs/sysml2/model/template-dot-net-tool/utilities/path-helpers.sysml | Adds SysML2 part definition for PathHelpers with artifact-location comments. |
| docs/sysml2/model/template-dot-net-tool/utilities.sysml | Adds SysML2 part definition for UtilitiesSubsystem and its child part usage. |
| docs/sysml2/model/template-dot-net-tool/self-test/validation.sysml | Adds SysML2 part definition for Validation with artifact-location comments. |
| docs/sysml2/model/template-dot-net-tool/self-test.sysml | Adds SysML2 part definition for SelfTestSubsystem and its child part usage. |
| docs/sysml2/model/template-dot-net-tool/program.sysml | Adds SysML2 part definition for Program with artifact-location comments. |
| docs/sysml2/model/template-dot-net-tool/cli/context.sysml | Adds SysML2 part definition for Context with artifact-location comments. |
| docs/sysml2/model/template-dot-net-tool/cli.sysml | Adds SysML2 part definition for CliSubsystem and its child part usage. |
| docs/sysml2/model/template-dot-net-tool.sysml | Adds SysML2 system-level part definition and composition of subsystems/units. |
| docs/reqstream/ots/sysml2tools.yaml | Adds SysML2Tools OTS requirements for linting and rendering behaviors. |
| docs/design/template-dot-net-tool/utilities/path-helpers.md | Embeds generated Utilities view SVG in PathHelpers design doc. |
| docs/design/template-dot-net-tool/utilities.md | Embeds generated Utilities view SVG in Utilities subsystem design doc. |
| docs/design/template-dot-net-tool/self-test/validation.md | Embeds generated SelfTest view SVG in Validation unit design doc. |
| docs/design/template-dot-net-tool/self-test.md | Embeds generated SelfTest view SVG in SelfTest subsystem design doc. |
| docs/design/template-dot-net-tool/program.md | Embeds generated system view SVG in Program unit design doc. |
| docs/design/template-dot-net-tool/cli/context.md | Embeds generated Cli view SVG in Context unit design doc. |
| docs/design/template-dot-net-tool/cli.md | Embeds generated Cli view SVG in Cli subsystem design doc. |
| docs/design/template-dot-net-tool.md | Embeds generated system view SVG in system-level design doc. |
| docs/design/ots/sysml2tools.md | Adds SysML2Tools OTS integration/design documentation. |
| docs/design/ots.md | Adds SysML2Tools to the OTS design index. |
| docs/design/introduction.md | Switches Software Structure section to a SysML2-rendered diagram and updates narrative/scope formatting. |
| docs/design/definition.yaml | Adds SysML2Tools OTS design doc to the design document build inputs. |
| AGENTS.md | Updates agent navigation guidance to query SysML2 model first; adds docs/sysml2/ to key locations and standards matrix. |
| .versionmark.yaml | Adds version-capture configuration for sysml2tools. |
| .reviewmark.yaml | Adds SysML2 model files to review scopes and introduces an OTS-SysML2Tools review-set. |
| .github/workflows/build.yaml | Captures sysml2tools version; runs SysML2Tools self-validation and renders SVG views before Pandoc builds the Design doc. |
| .github/standards/sysml2-modeling.md | Introduces SysML2 modeling conventions (file layout, artifact-location comments, views, embedding rules, CI integration). |
| .github/standards/software-items.md | Notes SysML2 part-definition comments can reference companion artifact locations for agent querying. |
| .github/standards/reviewmark-usage.md | Adds SysML2 model files to ReviewMark’s needs-review list and Decomposition review scope. |
| .github/standards/design-documentation.md | Requires SysML2-rendered diagrams for Software Structure; clarifies version-number guidance. |
| .github/standards/cpp-testing.md | Removes C++ testing standard doc from the repo. |
| .github/standards/cpp-language.md | Removes C++ language standard doc from the repo. |
| .github/skills/sysml2tools-query/SKILL.md | Adds a skill doc describing how to query the SysML2 model with sysml2tools. |
| .github/agents/template-sync.agent.md | Adds docs/sysml2/ as a dedicated work group for template-sync handling. |
| .cspell.yaml | Adds SysML2-related words to the spelling dictionary. |
| .config/dotnet-tools.json | Pins demaconsulting.sysml2tools.tool and exposes the sysml2tools command as a local .NET tool. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…FileAssert The verification approach previously claimed a missing rendered SVG would break the compiled Design HTML/PDF build - this is incorrect, since Pandoc/WeasyPrint silently omit missing images rather than failing. - Add SysML2Tools_DesignDiagramsSvg FileAssert test asserting the 5 expected rendered SVGs exist in docs/design/generated/ and are well-formed SVG/XML - Wire the new test into Template-OTS-SysML2Tools-Render's evidence - Rewrite the Verification Approach and add a Test Scenario in docs/verification/ots/sysml2tools.md - Update docs/design/ots/sysml2tools.md's Integration Pattern to note FileAssert's role in verifying the render output 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 first-class support for SysML2 architecture modeling and querying throughout the repository, updating standards, workflows, and tools to treat the SysML2 model as the authoritative source for software structure. It also refines design and review standards to reference the SysML2 model, clarifies artifact-location conventions, and adds tooling and documentation for querying the model. Additionally, C++ language and testing standards are removed (presumably moved elsewhere). The most important changes are grouped below.
SysML2 Model Integration and Querying
sysml2toolsCLI as a pinned .NET tool in.config/dotnet-tools.jsonfor querying and validating SysML2 models (sysml2tools), and documented its use in a newsysml2tools-queryskill (.github/skills/sysml2tools-query/SKILL.md). [1] [2]demaconsulting,sysml, andsysml2toolsas valid words. [1] [2]Standards and Review Process Updates
sysml2-modeling.mdconventions, and clarify version number handling in design docs. [1] [2] [3]Work Group and Agent Updates
docs/sysml2/(SysML2 model files and rendered views) in the template-sync agent configuration to ensure proper handling and review.C++ Standards Removal
cpp-language.md,cpp-testing.md) from the repository, indicating a possible migration or deprecation. [1] [2]