Synchronize SysML2 design files and update documentation - #35
Merged
Conversation
Manually synchronize agent, standards, and skill files in preparation for adding sysml2 architecture model design information. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add Test-Path-guarded sysml2tools lint block to lint.ps1, matching the check AGENTS.md's CI Quality Tools section already documents as active (safe no-op until docs/sysml2/ exists) - Add line_length = 10000 to .yamlfix.toml to match the template and avoid yamlfix wrapping long YAML lines against .yamllint.yaml Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds docs/sysml2/model/ (one .sysml file per System/Subsystem/Unit plus ots.sysml for the 6 OTS dependencies) and docs/sysml2/views/design-views.sysml (SoftwareStructureView + one per-system view + CliView/SelfTestView, 9 views total). Wires sysml2tools into .config/dotnet-tools.json, .versionmark.yaml, and the build-docs job in .github/workflows/build.yaml (render step before Pandoc HTML generation, plus versionmark capture). Embeds the rendered Structure diagrams into the corresponding docs/design/ files, adds sysml to .cspell.yaml, and adds docs/sysml2/**/*.sysml to .reviewmark.yaml's needs-review list and Decomposition review-set. Validated: dotnet sysml2tools lint (0 errors), dotnet sysml2tools render (9 SVGs produced), dotnet sysml2tools query list --kind "part def" (49 part defs, matching introduction.md's Software Structure tree), and pwsh ./fix.ps1 / pwsh ./lint.ps1 (no new failures). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove the duplicate SoftwareStructureView.svg embed that was placed right after the # Introduction heading, and replace the hand-maintained ASCII Software Structure tree under ## Software Structure with a short explanatory paragraph plus the diagram embed, matching the sysml2-modeling.md standard and DictionaryMark precedent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request makes the SysML2 model under docs/sysml2/ the authoritative, machine-queryable source for ApiMark’s software structure, integrates sysml2tools into CI/build linting and diagram rendering, and updates design/review standards and docs to rely on rendered SysML2 views.
Changes:
- Add SysML2 model + view definitions (
docs/sysml2/**) describing systems/units and artifact-location metadata. - Integrate
sysml2toolsinto linting/version capture and render design diagrams during the docs build. - Update design documentation and standards to embed SysML2-rendered structure diagrams instead of hand-maintained trees.
Reviewed changes
Copilot reviewed 103 out of 103 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| lint.ps1 | Runs sysml2tools lint over docs/sysml2/**/*.sysml when the model folder exists. |
| docs/sysml2/views/design-views.sysml | Defines named views to render software-structure diagrams for design docs. |
| docs/sysml2/model/ots.sysml | Models OTS dependencies and links them to design/verification/requirements artifacts. |
| docs/sysml2/model/api-mark-vhdl/vhdl-generator.sysml | Adds SysML2 unit definition + artifact references for VhdlGenerator. |
| docs/sysml2/model/api-mark-vhdl/vhdl-emitter.sysml | Adds SysML2 unit definition + artifact references for VhdlEmitter. |
| docs/sysml2/model/api-mark-vhdl/vhdl-emitter-single-file.sysml | Adds SysML2 unit definition + artifact references for VhdlEmitterSingleFile. |
| docs/sysml2/model/api-mark-vhdl/vhdl-emitter-gradual-disclosure.sysml | Adds SysML2 unit definition + artifact references for VhdlEmitterGradualDisclosure. |
| docs/sysml2/model/api-mark-vhdl/vhdl-ast-parser.sysml | Adds SysML2 unit definition + artifact references for VhdlAstParser. |
| docs/sysml2/model/api-mark-vhdl/vhdl-ast-model.sysml | Adds SysML2 unit definition + artifact references for VhdlAstModel. |
| docs/sysml2/model/api-mark-vhdl.sysml | Adds SysML2 system definition for ApiMarkVhdlSystem and its contained parts. |
| docs/sysml2/model/api-mark-tool/self-test/validation.sysml | Adds SysML2 unit definition + artifact references for Validation. |
| docs/sysml2/model/api-mark-tool/self-test.sysml | Adds SysML2 subsystem definition for SelfTestSubsystem. |
| docs/sysml2/model/api-mark-tool/program.sysml | Adds SysML2 unit definition + artifact references for Program. |
| docs/sysml2/model/api-mark-tool/cli/context.sysml | Adds SysML2 unit definition + artifact references for CLI Context. |
| docs/sysml2/model/api-mark-tool/cli.sysml | Adds SysML2 subsystem definition for CliSubsystem. |
| docs/sysml2/model/api-mark-tool.sysml | Adds SysML2 system definition for ApiMarkToolSystem. |
| docs/sysml2/model/api-mark-msbuild/api-mark-task.sysml | Adds SysML2 unit definition + artifact references for ApiMarkTask. |
| docs/sysml2/model/api-mark-msbuild.sysml | Adds SysML2 system definition for ApiMarkMsbuildSystem. |
| docs/sysml2/model/api-mark-dot-net/xml-doc-reader.sysml | Adds SysML2 unit definition + artifact references for XmlDocReader. |
| docs/sysml2/model/api-mark-dot-net/type-name-simplifier.sysml | Adds SysML2 unit definition + artifact references for TypeNameSimplifier. |
| docs/sysml2/model/api-mark-dot-net/type-link-resolver.sysml | Adds SysML2 unit definition + artifact references for TypeLinkResolver. |
| docs/sysml2/model/api-mark-dot-net/dot-net-generator.sysml | Adds SysML2 unit definition + artifact references for DotNetGenerator. |
| docs/sysml2/model/api-mark-dot-net/dot-net-emitter.sysml | Adds SysML2 unit definition + artifact references for DotNetEmitter. |
| docs/sysml2/model/api-mark-dot-net/dot-net-emitter-single-file.sysml | Adds SysML2 unit definition + artifact references for DotNetEmitterSingleFile. |
| docs/sysml2/model/api-mark-dot-net/dot-net-emitter-gradual-disclosure.sysml | Adds SysML2 unit definition + artifact references for DotNetEmitterGradualDisclosure. |
| docs/sysml2/model/api-mark-dot-net/dot-net-ast-model.sysml | Adds SysML2 unit definition + artifact references for DotNetAstModel. |
| docs/sysml2/model/api-mark-dot-net.sysml | Adds SysML2 system definition for ApiMarkDotNetSystem. |
| docs/sysml2/model/api-mark-cpp/cpp-type-link-resolver.sysml | Adds SysML2 unit definition + artifact references for CppTypeLinkResolver. |
| docs/sysml2/model/api-mark-cpp/cpp-generator.sysml | Adds SysML2 unit definition + artifact references for CppGenerator. |
| docs/sysml2/model/api-mark-cpp/cpp-emitter.sysml | Adds SysML2 unit definition + artifact references for CppEmitter. |
| docs/sysml2/model/api-mark-cpp/cpp-emitter-single-file.sysml | Adds SysML2 unit definition + artifact references for CppEmitterSingleFile. |
| docs/sysml2/model/api-mark-cpp/cpp-emitter-gradual-disclosure.sysml | Adds SysML2 unit definition + artifact references for CppEmitterGradualDisclosure. |
| docs/sysml2/model/api-mark-cpp/cpp-ast-model.sysml | Adds SysML2 unit definition + artifact references for CppAstModel. |
| docs/sysml2/model/api-mark-cpp/clang-ast-parser.sysml | Adds SysML2 unit definition + artifact references for ClangAstParser. |
| docs/sysml2/model/api-mark-cpp.sysml | Adds SysML2 system definition for ApiMarkCppSystem. |
| docs/sysml2/model/api-mark-core/path-helpers.sysml | Adds SysML2 unit definition + artifact references for PathHelpers. |
| docs/sysml2/model/api-mark-core/i-markdown-writer.sysml | Adds SysML2 unit definition + artifact references for IMarkdownWriter. |
| docs/sysml2/model/api-mark-core/i-markdown-writer-factory.sysml | Adds SysML2 unit definition + artifact references for IMarkdownWriterFactory. |
| docs/sysml2/model/api-mark-core/i-context.sysml | Adds SysML2 unit definition + artifact references for IContext. |
| docs/sysml2/model/api-mark-core/i-api-generator.sysml | Adds SysML2 unit definition + artifact references for IApiGenerator. |
| docs/sysml2/model/api-mark-core/i-api-emitter.sysml | Adds SysML2 unit definition + artifact references for IApiEmitter. |
| docs/sysml2/model/api-mark-core/glob-file-collector.sysml | Adds SysML2 unit definition + artifact references for GlobFileCollector. |
| docs/sysml2/model/api-mark-core/file-markdown-writer.sysml | Adds SysML2 unit definition + artifact references for FileMarkdownWriter. |
| docs/sysml2/model/api-mark-core/file-markdown-writer-factory.sysml | Adds SysML2 unit definition + artifact references for FileMarkdownWriterFactory. |
| docs/sysml2/model/api-mark-core/emit-config.sysml | Adds SysML2 unit definition + artifact references for EmitConfig. |
| docs/sysml2/model/api-mark-core.sysml | Adds SysML2 system definition for ApiMarkCoreSystem. |
| docs/design/introduction.md | Replaces hand-maintained structure tree with an embedded SysML2-rendered overview diagram. |
| docs/design/api-mark-vhdl/vhdl-generator.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-vhdl/vhdl-emitter.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-vhdl/vhdl-emitter-single-file.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-vhdl/vhdl-emitter-gradual-disclosure.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-vhdl/vhdl-ast-parser.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-vhdl/vhdl-ast-model.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-vhdl.md | Embeds rendered ApiMarkVhdlView.svg diagram. |
| docs/design/api-mark-tool/self-test/validation.md | Embeds rendered SelfTestView.svg diagram. |
| docs/design/api-mark-tool/self-test.md | Embeds rendered SelfTestView.svg diagram. |
| docs/design/api-mark-tool/program.md | Embeds rendered ApiMarkToolView.svg diagram. |
| docs/design/api-mark-tool/cli/context.md | Embeds rendered CliView.svg diagram. |
| docs/design/api-mark-tool/cli.md | Embeds rendered CliView.svg diagram. |
| docs/design/api-mark-tool.md | Embeds rendered ApiMarkToolView.svg diagram. |
| docs/design/api-mark-msbuild/api-mark-task.md | Embeds rendered ApiMarkMsbuildView.svg diagram. |
| docs/design/api-mark-msbuild.md | Embeds rendered ApiMarkMsbuildView.svg diagram. |
| docs/design/api-mark-dot-net/xml-doc-reader.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/type-name-simplifier.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/type-link-resolver.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/dot-net-generator.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/dot-net-emitter.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/dot-net-emitter-single-file.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net/dot-net-ast-model.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-dot-net.md | Embeds rendered ApiMarkDotNetView.svg diagram. |
| docs/design/api-mark-cpp/cpp-type-link-resolver.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp/cpp-generator.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp/cpp-emitter.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp/cpp-emitter-single-file.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp/cpp-ast-model.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp/clang-ast-parser.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-cpp.md | Embeds rendered ApiMarkCppView.svg diagram. |
| docs/design/api-mark-core/path-helpers.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/i-markdown-writer.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/i-markdown-writer-factory.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/i-context.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/i-api-generator.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/i-api-emitter.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/glob-file-collector.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/file-markdown-writer.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/file-markdown-writer-factory.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core/emit-config.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| docs/design/api-mark-core.md | Embeds rendered ApiMarkCoreView.svg diagram. |
| AGENTS.md | Updates agent navigation guidance to start from SysML2 model queries. |
| .yamlfix.toml | Adjusts YAML auto-fix configuration (line length). |
| .versionmark.yaml | Adds sysml2tools version capture regex. |
| .reviewmark.yaml | Adds SysML2 model files to review coverage and decomposition review scope. |
| .github/workflows/build.yaml | Captures sysml2tools version and renders SysML2 diagrams before Pandoc. |
| .github/standards/sysml2-modeling.md | Introduces SysML2 modeling/view/metadata standards and build/lint integration rules. |
| .github/standards/software-items.md | Notes SysML2 artifact-location comments for automation/traceability. |
| .github/standards/reviewmark-usage.md | Adds SysML2 files to review scope and clarifies decomposition review inputs. |
| .github/standards/design-documentation.md | Updates design intro requirements to use SysML2-rendered structure diagrams. |
| .github/skills/sysml2tools-query/SKILL.md | Adds a skill guide for querying the SysML2 model with sysml2tools. |
| .github/agents/template-sync.agent.md | Adds docs/sysml2/ as a template-sync work group. |
| .cspell.yaml | Adds sysml to the dictionary. |
| .config/dotnet-tools.json | Pins and registers the demaconsulting.sysml2tools.tool local .NET tool. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…tifact Structure
- Fix all 44 docs/design/**/*.md SysML2 diagram embeds to use bare
filenames (e.g. SoftwareStructureView.svg) instead of path-prefixed
references (generated/..., ../generated/..., ../../generated/...).
sysml2tools renders all SVGs flat into docs/design/generated/, and
Pandoc's --output design.html lands in that same flat folder without
rewriting image paths, so WeasyPrint (which resolves relative image
URLs against the HTML file's own location) was failing to find every
diagram — silently dropping them from the built PDF. Reproduced and
confirmed the failure mode directly with WeasyPrint before/after
(broken paths raised 'Failed to load image ... generated/generated/
...View.svg' errors; fixed paths raise no errors and produce a
visibly larger PDF from the now-embedded diagrams).
- Replace introduction.md's ~80-line enumeration of every companion
artifact file with the terse, pattern-based form the template and
sysml2-modeling.md actually specify (parallel path patterns using
{system-name}/{subsystem}/{item} placeholders), matching the
DictionaryMark precedent. The full enumeration duplicated what the
SysML2 model's artifact-ref comments already provide per-item via
'sysml2tools query describe', and would require manual upkeep on
every unit addition.
Verified: dotnet sysml2tools render, pandoc, and weasyprint all
succeed with the fixed paths; pwsh ./lint.ps1 passes clean (0 errors).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The upstream Agents template is being updated to drop the explicit 'render asTreeDiagram;' statement from every view usage. Verified locally that sysml2tools lint/render/pandoc/weasyprint/fileassert all still succeed without it (render falls back to a different default diagram style — a flat UML-style package/part-def compartment listing rather than the nested containment tree), matching the upcoming template change. 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-based software structure modeling and querying throughout the repository. It adds documentation and standards for using the
sysml2toolsCLI, updates review and design processes to rely on the SysML2 model as the authoritative source of software structure, and ensures artifact-location metadata is consistently available for automation and traceability.The most important changes are:
SysML2 Modeling and Query Tooling:
sysml2toolsCLI as a pinned .NET tool in.config/dotnet-tools.jsonfor querying and validating SysML2 models (docs/sysml2/)..github/skills/sysml2tools-query/SKILL.mdexplaining how to query the SysML2 model to understand the software structure, locate artifacts, and assess change impact.Documentation and Standards Updates:
.github/standards/design-documentation.mdto require SysML2-rendered diagrams as the authoritative software structure, replacing hand-maintained text trees. Added reference tosysml2-modeling.md. [1] [2].github/standards/reviewmark-usage.mdto include.sysmlfiles in review coverage, reference the SysML2 model as the authoritative structure for decomposition reviews, and clarify context files and requirements for review sets. [1] [2] [3] [4] [5]Repository Organization and Vocabulary:
docs/sysml2/as a dedicated work group for SysML2 model files in the agent workflow.sysml.