Add SysML2 architecture model support and OTS documentation#196
Merged
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Scaffold docs/sysml2/model and docs/sysml2/views for the ReqStream system, its 5 subsystems (Cli, Modeling, Tracing, SelfTest, Utilities), 15 units, and the 3 library OTS dependencies (YamlDotNet, FileSystemGlobbing, TestResults) modeled as SysML2 part defs. - Wire demaconsulting.sysml2tools.tool into .config/dotnet-tools.json, .versionmark.yaml, lint.ps1, and .github/workflows/build.yaml (self- validation and SVG render steps, tool version capture). - Rework docs/design/introduction.md to replace the hand-maintained ASCII software structure tree with the generated SoftwareStructureView diagram, and embed per-subsystem/unit diagrams across docs/design/reqstream.md and docs/design/reqstream/**. - Rework .reviewmark.yaml per the updated reviewmark-usage.md standard: split Purpose/Decomposition review-sets, add context blocks to all ReqStream-* review-sets, and add docs/sysml2/**/*.sysml to needs-review.
- Add docs/reqstream/ots/sysml2tools.yaml, docs/design/ots/sysml2tools.md, and docs/verification/ots/sysml2tools.md as full OTS companion artifacts for the sysml2tools dotnet tool itself. - Wire the new files into requirements.yaml, docs/design/definition.yaml, docs/verification/definition.yaml, docs/design/ots.md, and docs/verification/ots.md, plus a new OTS-SysML2Tools review-set in .reviewmark.yaml (added in the previous commit). - Add sysml, sysml2tools, and demaconsulting to .cspell.yaml.
…LI/design doc drift
- docs/design/ots/sysml2tools.md: fix self-contradiction (global vs local tool),
correct CI job/step references (build-docs job, self-validation + render steps).
- docs/design/introduction.md: remove SysML2Tools from the in-scope OTS design
items list to match the SysML2 model boundary; document it (and other
pipeline OTS tools) as out-of-scope build-pipeline tooling with companion
artifacts and a dedicated ReviewMark review-set instead.
- docs/reqstream/reqstream/modeling.yaml: remove the misplaced
ReqStream-Utilities-SafePath child reference from
ReqStream-Modeling-MultiFileLoading (belongs to the Utilities subsystem).
- docs/design/reqstream/tracing.md: correct TraceMatrix.Export depth
documentation - only a lower bound of 1 is enforced, no upper bound of 6.
- docs/design/reqstream.md: document --version/-v, --help/-h/-?, and
--results/--result aliases to match Context.cs and cli/context.md.
- docs/design/reqstream/utilities.md: document GlobMatcher null-input
behavior (ArgumentNullException for null patterns collection, silent skip
of null elements).
- docs/verification/reqstream/{modeling,tracing,utilities,utilities/path-helpers}.md:
remove hand-maintained Requirements Coverage tables per
verification-documentation.md standard (coverage lives in the ReqStream
trace matrix, not verification docs); reworded acceptance-criteria text
that referenced the removed tables.
Restructure RequirementsLoader into a two-pass load: pass 1 recursively builds the full requirements tree across all includes without resolving mappings; pass 2 resolves all deferred mappings against the complete requirements dictionary. Unresolved mapping IDs now emit a lint Error instead of being silently dropped. Adds tests covering mapping resolution across includes and the new unresolved-mapping-id lint error.
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request adds first-class SysML v2 architecture model support to ReqStream’s Continuous Compliance workflow, integrating a new sysml2tools local tool into linting/build pipelines and shifting “software structure” documentation to diagrams rendered from the SysML2 model. It also tightens agent orchestration/reporting and improves requirements-loading behavior around deferred mapping resolution across includes.
Changes:
- Integrate SysML2Tools into CI/lint/version capture and add SysML2 model + views under
docs/sysml2/, with design docs embedding rendered SVGs. - Improve requirements loading by deferring mapping resolution until after all included files are loaded, and add regression tests for cross-file mappings and unknown mapping IDs.
- Update ReviewMark configuration, agent templates, and documentation/standards to reflect the SysML2-first workflow and revised verification documentation expectations.
Reviewed changes
Copilot reviewed 83 out of 83 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| test/DemaConsulting.ReqStream.Tests/Modeling/RequirementsLoaderTests.cs | Adds regression tests for deferred mapping resolution across includes and for unknown mapping IDs. |
| src/DemaConsulting.ReqStream/Modeling/RequirementsLoader.cs | Implements a two-pass load (build tree then resolve mappings) and reports unknown mapping IDs as errors. |
| requirements.yaml | Includes SysML2Tools OTS requirements file in the root requirements set. |
| lint.ps1 | Adds SysML2Tools linting for docs/sysml2/**/*.sysml in compliance tooling. |
| docs/verification/reqstream/utilities/path-helpers.md | Updates acceptance criteria wording to rely on ReqStream trace matrix rather than embedded coverage tables. |
| docs/verification/reqstream/utilities.md | Removes embedded requirements coverage table references; points to ReqStream trace matrix. |
| docs/verification/reqstream/tracing.md | Removes embedded requirements coverage table references; points to ReqStream trace matrix. |
| docs/verification/reqstream/modeling.md | Removes embedded requirements coverage table references; points to ReqStream trace matrix. |
| docs/verification/ots/sysml2tools.md | Adds verification evidence document for the SysML2Tools OTS item. |
| docs/verification/ots.md | Adds SysML2Tools to the OTS verification overview table. |
| docs/verification/introduction.md | Documents SysML2Tools as an OTS item under verification scope. |
| docs/verification/definition.yaml | Adds SysML2Tools verification doc to verification document build inputs. |
| docs/sysml2/views/design-views.sysml | Defines rendered SysML2 views used to generate design-document diagrams. |
| docs/sysml2/model/reqstream/utilities/temporary-directory.sysml | Adds SysML2 part definition for TemporaryDirectory with companion artifact references. |
| docs/sysml2/model/reqstream/utilities/path-helpers.sysml | Adds SysML2 part definition for PathHelpers with companion artifact references. |
| docs/sysml2/model/reqstream/utilities/glob-matcher.sysml | Adds SysML2 part definition for GlobMatcher with companion artifact references. |
| docs/sysml2/model/reqstream/utilities.sysml | Adds SysML2 part definition for Utilities subsystem and its contained units. |
| docs/sysml2/model/reqstream/tracing/trace-matrix.sysml | Adds SysML2 part definition for TraceMatrix with companion artifact references. |
| docs/sysml2/model/reqstream/tracing.sysml | Adds SysML2 part definition for Tracing subsystem and its contained unit(s). |
| docs/sysml2/model/reqstream/self-test/validation.sysml | Adds SysML2 part definition for Validation with companion artifact references. |
| docs/sysml2/model/reqstream/self-test.sysml | Adds SysML2 part definition for SelfTest subsystem and its contained unit(s). |
| docs/sysml2/model/reqstream/program.sysml | Adds SysML2 part definition for Program with companion artifact references. |
| docs/sysml2/model/reqstream/modeling/section.sysml | Adds SysML2 part definition for Section with companion artifact references. |
| docs/sysml2/model/reqstream/modeling/requirements.sysml | Adds SysML2 part definition for Requirements with companion artifact references. |
| docs/sysml2/model/reqstream/modeling/requirements-loader.sysml | Adds SysML2 part definition for RequirementsLoader with companion artifact references. |
| docs/sysml2/model/reqstream/modeling/requirement.sysml | Adds SysML2 part definition for Requirement with companion artifact references. |
| docs/sysml2/model/reqstream/modeling/load-result.sysml | Adds SysML2 part definition for LoadResult with companion artifact references. |
| docs/sysml2/model/reqstream/modeling/lint-issue.sysml | Adds SysML2 part definition for LintIssue with companion artifact references. |
| docs/sysml2/model/reqstream/modeling.sysml | Adds SysML2 part definition for Modeling subsystem and its contained units. |
| docs/sysml2/model/reqstream/cli/context.sysml | Adds SysML2 part definition for CLI Context with companion artifact references. |
| docs/sysml2/model/reqstream/cli.sysml | Adds SysML2 part definition for CLI subsystem and its contained unit(s). |
| docs/sysml2/model/reqstream.sysml | Adds SysML2 system model for ReqStream, including subsystems/units and OTS runtime deps. |
| docs/sysml2/model/ots.sysml | Adds SysML2 model for OTS runtime dependencies (YamlDotNet/FileSystemGlobbing/TestResults). |
| docs/reqstream/reqstream/modeling.yaml | Adjusts modeling requirements structure (removes an unrelated Utilities requirement child entry). |
| docs/reqstream/ots/sysml2tools.yaml | Adds OTS requirements for SysML2Tools lint/render behaviors. |
| docs/design/reqstream/utilities/temporary-directory.md | Embeds Utilities view diagram in unit design doc. |
| docs/design/reqstream/utilities/path-helpers.md | Embeds Utilities view diagram in unit design doc. |
| docs/design/reqstream/utilities/glob-matcher.md | Embeds Utilities view diagram in unit design doc. |
| docs/design/reqstream/utilities.md | Embeds Utilities view diagram and clarifies GlobMatcher contract details. |
| docs/design/reqstream/tracing/trace-matrix.md | Embeds Tracing view diagram in unit design doc. |
| docs/design/reqstream/tracing.md | Embeds Tracing view diagram and clarifies depth constraints/behavior. |
| docs/design/reqstream/self-test/validation.md | Embeds SelfTest view diagram in unit design doc. |
| docs/design/reqstream/self-test.md | Embeds SelfTest view diagram in subsystem design doc. |
| docs/design/reqstream/program.md | Embeds ReqStream system view diagram in design doc. |
| docs/design/reqstream/modeling/section.md | Embeds Modeling view diagram in unit design doc. |
| docs/design/reqstream/modeling/requirements.md | Embeds Modeling view diagram in unit design doc. |
| docs/design/reqstream/modeling/requirements-loader.md | Embeds Modeling view diagram in unit design doc. |
| docs/design/reqstream/modeling/requirement.md | Embeds Modeling view diagram in unit design doc. |
| docs/design/reqstream/modeling/load-result.md | Embeds Modeling view diagram in unit design doc. |
| docs/design/reqstream/modeling/lint-issue.md | Embeds Modeling view diagram in unit design doc. |
| docs/design/reqstream/modeling.md | Embeds Modeling view diagram in subsystem design doc. |
| docs/design/reqstream/cli/context.md | Embeds CLI view diagram in unit design doc. |
| docs/design/reqstream/cli.md | Embeds CLI view diagram in subsystem design doc. |
| docs/design/reqstream.md | Embeds ReqStream view diagram and updates CLI/options documentation. |
| docs/design/ots/sysml2tools.md | Adds OTS design doc describing SysML2Tools integration (lint/self-validate/render). |
| docs/design/ots.md | Documents SysML2Tools as an intentional exception among pipeline tools in OTS design chapter. |
| docs/design/introduction.md | Replaces hand-maintained structure tree with SysML2-rendered diagram and updates scope narrative. |
| docs/design/definition.yaml | Adds SysML2Tools OTS design doc to design document build inputs. |
| AGENTS.md | Updates agent guidance to prefer SysML2 model queries; adds planning-agent usage and sysml2 folder reference. |
| .versionmark.yaml | Adds version capture rule for demaconsulting.sysml2tools.tool. |
| .reviewmark.yaml | Adds docs/sysml2/**/*.sysml to review-needed files and introduces global/per-review context. |
| .github/workflows/build.yaml | Captures sysml2tools version and adds self-validation + render steps before Pandoc design generation. |
| .github/standards/verification-documentation.md | Updates verification doc standards (mandatory sections; coverage tracked via ReqStream trace matrix). |
| .github/standards/testing-principles.md | Minor standards doc cleanup (removes redundant header text). |
| .github/standards/technical-documentation.md | Clarifies/condenses documentation standards and formatting guidance. |
| .github/standards/sysml2-modeling.md | Adds a full SysML2 modeling standard (structure, views, embedding, lint/render integration). |
| .github/standards/software-items.md | Updates placeholder/naming guidance and notes SysML2 comment metadata for artifact locations. |
| .github/standards/reviewmark-usage.md | Updates ReviewMark guidance to include context and SysML2 coverage, plus clarified review-set patterns. |
| .github/standards/reqstream-usage.md | Clarifies matching paths across requirements/design/verification and updates examples. |
| .github/standards/design-documentation.md | Updates design doc standards to require SysML2-rendered structure diagrams (not text trees). |
| .github/standards/csharp-testing.md | Minor standards doc cleanup (removes redundant header text). |
| .github/standards/csharp-language.md | Minor standards doc cleanup (removes redundant header text). |
| .github/standards/coding-principles.md | Minor standards doc cleanup/wording adjustments. |
| .github/skills/sysml2tools-query/SKILL.md | Adds a skill guide for querying the SysML2 model via sysml2tools query. |
| .github/agents/template-sync.agent.md | Updates template-sync agent orchestration to include SysML2 docs grouping and improved reporting. |
| .github/agents/quality.agent.md | Updates quality agent to cross-check planning artifact table and adds verification-doc compliance checks. |
| .github/agents/planning.agent.md | Adds a new planning agent definition and structured planning/reporting template. |
| .github/agents/lint-fix.agent.md | Updates lint-fix agent report template to include the log report path. |
| .github/agents/implementation.agent.md | Switches implementation orchestration to use the new planning agent and updates report structure. |
| .github/agents/formal-review.agent.md | Updates formal-review agent workflow and report template to include the log report path. |
| .github/agents/developer.agent.md | Updates developer agent guidance/report template and expands companion artifact categories. |
| .cspell.yaml | Adds SysML2-related words for spell checking. |
| .config/dotnet-tools.json | Adds demaconsulting.sysml2tools.tool local tool dependency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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 several improvements and clarifications to the agent orchestration and reporting process, adds a new planning agent, and updates quality and review requirements to ensure more comprehensive coverage and traceability. It also refines the handling of companion artifacts and reporting, and expands spell checking and tool configuration.
Key changes include:
Agent Process and Reporting Improvements
planning.agent.mdfile defining a new planning agent that investigates the codebase, produces a verified implementation plan, and identifies all required companion artifacts, with a structured reporting template. (.github/agents/planning.agent.md)**Report**field pointing to the generated log file for traceability. (.github/agents/developer.agent.md, .github/agents/formal-review.agent.md, .github/agents/lint-fix.agent.md, .github/agents/quality.agent.md) [1] [2] [3] [4]Companion Artifact and Quality Requirements
Template Synchronization and Documentation
docs/sysml2/, root files indocs/design/,docs/verification/,docs/reqstream/), clarified template matching, and refined error handling for missing templates. (.github/agents/template-sync.agent.md)Tooling and Spell Checking
demaconsulting.sysml2tools.toolto.config/dotnet-tools.jsonfor SysML2 model support. (.config/dotnet-tools.json).cspell.yamlto include new domain-specific words (e.g.,demaconsulting,sysml,sysml2tools) for improved spell checking. (.cspell.yaml) [1] [2]These changes collectively strengthen the planning, traceability, and reporting around code changes, ensuring that all required artifacts are identified, produced, and validated as part of the development workflow.