Add SysML2 architecture model and enhance documentation compliance#110
Merged
Conversation
…gaps - Wire sysml2tools into dotnet-tools.json, .versionmark.yaml, lint.ps1, and the build.yaml design job (render Software Structure diagrams to docs/design/generated before Pandoc HTML generation) - Add docs/sysml2/ model (system + Demo unit) and design-views (Software Structure and TemplateDotNetLibrary views) - Embed rendered SVG diagrams in docs/design/introduction.md and the system/unit design docs - Extensively refactor docs/design/introduction.md to follow the template (Purpose, Scope, Software Structure, Folder Layout, Document Conventions, Companion Artifact Structure, References) - Extensively refactor .reviewmark.yaml with new context blocks and review-sets (Purpose, Decomposition, Architecture, Design, Verification, AllRequirements, Demo, and per-OTS-item sets) - Move system-level design/reqstream/verification docs to top level to match the reference template convention, fix heading depths and mandatory sections in design/verification docs, and add the missing OTS design (docs/design/ots.md + docs/design/ots/*.md) and verification (docs/verification/ots.md) documentation - Remove an unrequested/untraceable NuGet package metadata interface claim from the system design flagged by formal review Verified via dotnet reqstream/versionmark/reviewmark/sysml2tools --lint, markdownlint-cli2, cspell, yamllint, dotnet format, and formal-review agents (gpt-5.4-mini) across all affected review-sets. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a SysML2-based architecture model under docs/sysml2/, integrates SysML2Tools into linting/CI, and updates documentation/standards to enforce stricter structure and traceability expectations across requirements, design, verification, and review-sets.
Changes:
- Added a SysML2 model + rendered design views, and integrated SysML2Tools into
lint.ps1and the CI docs build. - Restructured and expanded design/verification documentation (including new OTS overview + per-OTS design docs) and updated Pandoc definition manifests.
- Updated agent orchestration docs/templates and multiple standards to formalize heading-depth rules, review-set structure, and artifact expectations.
Reviewed changes
Copilot reviewed 51 out of 52 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| requirements.yaml | Updates root ReqStream include path for system-level requirements. |
| lint.ps1 | Adds SysML2Tools linting when docs/sysml2 exists. |
| docs/verification/template-dot-net-library/demo.md | Adjusts heading depth/structure and replaces requirements-coverage table with acceptance criteria. |
| docs/verification/template-dot-net-library.md | Renames “Strategy” → “Approach” and removes requirements-coverage table. |
| docs/verification/ots.md | Adds repository-level OTS verification overview document. |
| docs/verification/introduction.md | Updates verification intro prose and companion-artifact structure wording. |
| docs/verification/definition.yaml | Updates verification document assembly inputs and adds ots.md. |
| docs/sysml2/views/design-views.sysml | Defines named views for rendered design diagrams. |
| docs/sysml2/model/template-dot-net-library/demo.sysml | Adds SysML2 unit part definition for Demo with artifact references. |
| docs/sysml2/model/template-dot-net-library.sysml | Adds SysML2 system part definition + composition. |
| docs/reqstream/template-dot-net-library.yaml | Adds system-level requirements file for the Template DotNet Library. |
| docs/design/template-dot-net-library/demo.md | Enhances unit design doc and embeds SysML2-generated diagram. |
| docs/design/template-dot-net-library.md | Updates system design structure and embeds SysML2-generated diagram. |
| docs/design/ots/xunit.md | Adds OTS integration design for xUnit. |
| docs/design/ots/weasyprint.md | Adds OTS integration design for WeasyPrint. |
| docs/design/ots/versionmark.md | Adds OTS integration design for VersionMark. |
| docs/design/ots/sonarmark.md | Adds OTS integration design for SonarMark. |
| docs/design/ots/sarifmark.md | Adds OTS integration design for SarifMark. |
| docs/design/ots/reviewmark.md | Adds OTS integration design for ReviewMark. |
| docs/design/ots/reqstream.md | Adds OTS integration design for ReqStream. |
| docs/design/ots/pandoc.md | Adds OTS integration design for Pandoc. |
| docs/design/ots/fileassert.md | Adds OTS integration design for FileAssert. |
| docs/design/ots/buildmark.md | Adds OTS integration design for BuildMark. |
| docs/design/ots.md | Adds repository-level OTS integration design overview document. |
| docs/design/introduction.md | Updates design intro to reference SysML2 model and embeds rendered diagram. |
| docs/design/definition.yaml | Updates design document assembly inputs to include new system-level + OTS docs. |
| AGENTS.md | Updates agent guidance to prefer SysML2 model, adds sysml2 folder, and standardizes reporting fields. |
| .versionmark.yaml | Adds SysML2Tools version extraction to VersionMark configuration. |
| .reviewmark.yaml | Expands needs-review patterns and refactors review-sets (adds SysML2 coverage). |
| .github/workflows/build.yaml | Adds SysML2Tools rendering step and captures tool version for sysml2tools. |
| .github/standards/verification-documentation.md | Updates verification-doc structure rules and mandatory section expectations. |
| .github/standards/testing-principles.md | Trims redundant header content; keeps core testing principles. |
| .github/standards/technical-documentation.md | Adds explicit heading-depth rule and clarifies generated-folder policy. |
| .github/standards/sysml2-modeling.md | Introduces SysML2 modeling standard (structure, views, build/lint integration). |
| .github/standards/software-items.md | Extends item taxonomy (adds Shared Package) and updates artifact model. |
| .github/standards/reviewmark-usage.md | Updates ReviewMark conventions (context files, patterns, hierarchy) and adds SysML2 coverage. |
| .github/standards/reqstream-usage.md | Updates ReqStream structure guidance (system file at root; shared packages) and examples. |
| .github/standards/design-documentation.md | Updates design-doc structure rules to incorporate SysML2-derived structure and heading-depth rule. |
| .github/standards/csharp-testing.md | Trims redundant header text; keeps quality checks. |
| .github/standards/csharp-language.md | Trims redundant header text; keeps examples/standards. |
| .github/standards/coding-principles.md | Tightens wording and formatting of core coding principles and anti-patterns. |
| .github/skills/sysml2tools-query/SKILL.md | Adds a skill guide for querying the SysML2 model via SysML2Tools. |
| .github/agents/template-sync.agent.md | Adds a new template-sync orchestrator agent definition. |
| .github/agents/software-architect.agent.md | Updates terminology to include Shared Package. |
| .github/agents/quality.agent.md | Expands quality checklist to include planning-table cross-references and verification docs. |
| .github/agents/planning.agent.md | Adds a new planning agent definition and report template. |
| .github/agents/lint-fix.agent.md | Standardizes lint-fix report metadata fields. |
| .github/agents/implementation.agent.md | Refactors implementation agent to use the new planning agent and updated report fields. |
| .github/agents/formal-review.agent.md | Clarifies ReviewMark file ordering (context vs files) and standardizes report metadata. |
| .github/agents/developer.agent.md | Adds template-counterpart check for newly created files and standardizes report metadata. |
| .cspell.yaml | Adds “sysml” to spelling dictionary. |
| .config/dotnet-tools.json | Adds demaconsulting.sysml2tools.tool as a local .NET tool. |
Comments suppressed due to low confidence (1)
docs/design/template-dot-net-library.md:5
- This SVG is generated by SysML2Tools into
docs/design/generated/, not alongside this markdown file. As written, the image reference will be broken in the rendered Design document unless it points at the generated folder.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add sysml2tools as an OTS item, mirroring the other pipeline tools: create docs/reqstream/ots/sysml2tools.yaml, docs/design/ots/sysml2tools.md, docs/verification/ots/sysml2tools.md; wire into requirements.yaml, docs/design/definition.yaml, docs/verification/definition.yaml, docs/design/ots.md, docs/verification/ots.md, docs/design/introduction.md, and add an OTS-SysML2Tools review-set to .reviewmark.yaml - Fix References sections in docs/design/introduction.md and docs/verification/introduction.md to use document-name-only bullets instead of direct URL links to internal docs/ source files, per the technical-documentation.md standard, as flagged by formal review - Remove an unrequested/untraceable NuGet package metadata interface claim from the system design flagged by formal review Verified via dotnet reqstream/reviewmark/sysml2tools --lint, markdownlint-cli2, cspell, yamllint, dotnet format, and formal-review agents (gpt-5.4-mini) across all affected review-sets, including the new OTS-SysML2Tools set. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…Assert SVG checks - build.yaml referenced SysML2Tools_LintSelfTest/SysML2Tools_RenderSvgSelfTest requirement evidence, but never ran dotnet sysml2tools --validate to produce that TRX, causing ReqStream --enforce to fail CI with 2 unsatisfied requirements. Add the missing "Run SysML2Tools self-validation" step in the design-docs job, matching FileAssert's reference implementation placement (before the render step). - Add direct FileAssert checks (SysML2Tools_SoftwareStructureViewSvg, SysML2Tools_TemplateDotNetLibraryViewSvg) asserting each rendered view's SVG exists in docs/design/generated/ and is well-formed XML with an <svg> root element, strengthening Template-OTS-SysML2Tools-Render's evidence beyond the tool's internal self-test fixture. - Update docs/design/ots/sysml2tools.md and docs/verification/ots/sysml2tools.md to document the new FileAssert-based verification evidence. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 55 out of 56 changed files in this pull request and generated 8 comments.
Comments suppressed due to low confidence (1)
docs/design/template-dot-net-library.md:55
- The system design’s build/verification OTS dependency list omits SysML2Tools, even though this PR adds SysML2Tools integration (lint + render) and dedicated design/verification artifacts. The Dependencies section should include SysML2Tools for completeness and to keep it consistent with docs/design/ots.md and docs/design/ots/sysml2tools.md.
All 11 OTS verification documents started at heading depth 1 (# {Item} Verification)
instead of depth 2, inconsistent with docs/design/ots/*.md (which correctly start at
depth 2) and with the sibling FileAssert repository's reference implementation. Shift
each file's headings down one level: top heading is now ##, with Required
Functionality/Verification Approach/Test Scenarios/Requirements Coverage at ### and
individual test scenario names at ####.
Verified via markdownlint-cli2, cspell, dotnet reviewmark --lint, and formal-review
agents (gpt-5.4-mini) on TemplateDotNetLibrary-Verification and OTS-SysML2Tools.
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 automation framework, focusing on enhanced traceability, structured planning, and more rigorous quality validation. Key changes include the addition of a dedicated planning agent, expanded and clarified reporting templates for all agents, and stricter enforcement of companion artifact deliverables across the development lifecycle. The quality assessment process is now more comprehensive, with explicit checks for verification documentation, review sets, and repository structure compliance.
Agent Workflow and Orchestration Enhancements:
planning.agent.mdthat defines a structured process for codebase investigation, implementation planning, companion artifact identification, risk and feasibility analysis, and explicit reporting of unknowns. The planning agent produces a detailed report and a lean summary for downstream agents.Quality Assessment and Compliance Improvements:
Reporting and Documentation Consistency:
**Report**field referencing the saved artifact and consistent summary sections. [1] [2] [3] [4]Tooling and Configuration Updates:
demaconsulting.sysml2tools.toolto.config/dotnet-tools.jsonand updated spelling configuration to recognize "sysml". [1] [2]These changes collectively strengthen the project's compliance automation, traceability, and quality assurance processes.