Split SysML2 model into separate files with artifact-location metadata#23
Merged
Conversation
…-location metadata - Rewrote sysml2-modeling.md: docs/sysml2/model/ + docs/sysml2/views/ folder split mirroring the folder depth of docs/design/, docs/reqstream/, and docs/verification/ (one file per System/Subsystem/Unit); new Artifact-Location Comments section documenting named comment metadata (sourceRef/testRef/designRef/verificationRef/ reqRef) so agents can query companion-artifact locations via 'sysml2tools query describe' without grepping the source tree; updated Build and Lint Integration and Diagram Embedding sections for sysml2tools 0.1.0-beta.5's native recursive glob expansion (quoted glob strings, no shell: bash/globstar or Get-ChildItem workarounds needed). - Updated the sysml2tools-query skill to match: new model/ paths, new Artifact-location metadata section with a genericized example, and beta.5 quoted-glob examples throughout. - Added a one-sentence cross-reference in software-items.md's Software Item Artifact Model section pointing at the new SysML2 comment metadata. Prototyped and validated in demaconsulting/DictionaryMark before porting here. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the repository’s SysML2 modeling standards and the sysml2tools query skill to reflect a new nested model-file layout under docs/sysml2/model/ and to standardize “artifact-location” metadata stored as named SysML2 comment elements.
Changes:
- Documented the new SysML2 model folder structure (one file per System/Subsystem/Unit) and updated example globs/commands accordingly.
- Standardized artifact-location metadata as named
commentelements (sourceRef,testRef,designRef,verificationRef,reqRef) and documented applicability rules. - Updated query skill guidance and cross-linked standards to encourage agents to use
query describefor artifact discovery.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| src/.github/standards/sysml2-modeling.md | Updates SysML2 model structure guidance, artifact-location comment conventions, and revised sysml2tools command examples/globs. |
| src/.github/standards/software-items.md | Adds a note connecting the software-item artifact model to SysML2 comment metadata conventions. |
| src/.github/skills/sysml2tools-query/SKILL.md | Updates query workflow docs for the new model layout and introduces artifact-location metadata usage via query describe. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+59
to
+61
| required, as long as all files are passed together. As of `sysml2tools` 0.1.0-beta.5, | ||
| `lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into | ||
| subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`) |
Comment on lines
+60
to
+62
| `lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into | ||
| subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`) | ||
| and let the tool resolve it — do not rely on the shell to expand it, and do not quote-strip |
Comment on lines
+40
to
+42
| automatically, no `import` required. As of `sysml2tools` 0.1.0-beta.5, every subcommand | ||
| (`lint`, `render`, `query`) expands `*`/`**` glob patterns internally and recurses | ||
| correctly — pass a single **quoted** glob string and let the tool resolve it, rather than |
Comment on lines
+70
to
+72
| Not every item has all five comments — Systems/Subsystems have no `Source` comment, and | ||
| units without a dedicated companion doc point at their parent's doc instead (see the | ||
| Artifact-Location Comments section of `sysml2-modeling.md` for the full rules). Prefer these |
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 updates the SysML2 modeling and query documentation to reflect a new file organization, clarify artifact-location metadata, and improve instructions for using the
sysml2toolstool. The main themes are: (1) reorganizing SysML2 model files into a nested folder structure that mirrors companion artifacts, (2) standardizing the use of artifact-location comments within model files, and (3) updating all documentation and example commands to use the new structure and tool behaviors.SysML2 model file organization and artifact-location metadata:
docs/sysml2/model/, with one file per system, subsystem, and unit, nested to match the structure of companion design, requirements, and verification documents. This replaces the previous flat structure and keeps changes localized. (src/.github/skills/sysml2tools-query/SKILL.md,src/.github/standards/sysml2-modeling.md) [1] [2]part defin the SysML2 model now includes namedcommentelements (sourceRef,testRef,designRef,verificationRef,reqRef) that point to the locations of related artifacts. This enables agents and scripts to discover all companion files for a given item via a single query. (src/.github/skills/sysml2tools-query/SKILL.md,src/.github/standards/software-items.md,src/.github/standards/sysml2-modeling.md) [1] [2] [3]Documentation and workflow improvements:
'docs/sysml2/model/**/*.sysml') tosysml2tools. The tool now expands globs internally, so shell-side expansion is no longer needed. (src/.github/skills/sysml2tools-query/SKILL.md,src/.github/standards/sysml2-modeling.md) [1] [2] [3]src/.github/skills/sysml2tools-query/SKILL.md,src/.github/standards/sysml2-modeling.md) [1] [2]src/.github/standards/sysml2-modeling.md) [1] [2]These changes make the SysML2 modeling process more maintainable, improve traceability between model elements and their companion artifacts, and simplify the developer workflow for querying, linting, and rendering models.