Add SysML2 architecture model support and update documentation

[Malcolmnixon]

This pull request introduces comprehensive improvements to the repository's formal review, design documentation, and SysML2 modeling workflows. The main focus is on integrating SysML2 models into review processes, clarifying documentation standards, and enhancing review set configuration with context and structure. It also adds a new skill for querying SysML2 models and updates spell-checking and tooling configuration.

Key changes:

SysML2 Model Integration and Tooling

• Added a new skill documentation file (.github/skills/sysml2tools-query/SKILL.md) describing how to query the SysML2 architecture model for understanding software structure, relationships, and artifact locations, including recommended workflows and validation steps.
• Added demaconsulting.sysml2tools.tool as a pinned .NET tool in .config/dotnet-tools.json for SysML2 model querying and validation.
• Updated .cspell.yaml to recognize SysML2-related terms and dependencies for spell-checking. [1] [2] [3]

Review Process and ReviewMark Configuration

• Overhauled .github/standards/reviewmark-usage.md to:
  • Include SysML2 model files in review coverage and clarify review set scoping.
  • Add explicit context files for each review set, ensuring reviewers have the necessary orientation without overloading the review scope.
  • Provide detailed review set design principles and naming conventions, including new sections on context management and review-set organization. [1] [2] [3] [4] [5]

Design Documentation Standards

• Updated .github/standards/design-documentation.md to:
  • Reference the new sysml2-modeling.md standard and require SysML2-rendered diagrams for the Software Structure section.
  • Clarify rules about version numbers in design docs, specifying what is and isn't allowed. [1] [2] [3]

Agent and Workflow Updates

• Clarified review agent instructions in .github/agents/formal-review.agent.md to distinguish between context/reference files and files under review, and to reflect the new review artifact workflow.
• Updated .github/agents/template-sync.agent.md to add a work group for SysML2 model files and rendered views.

These changes align the repository's review and documentation workflows with modern model-based engineering practices, streamline reviewer orientation, and ensure that all formal artifacts remain consistent and traceable.

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15]

[Copilot]

Pull request overview

This PR integrates a SysML2 architecture model into FileAssert’s documentation/review workflows and wires SysML2Tools into CI so software-structure diagrams are rendered from the model (rather than maintained as prose).

Changes:

• Added a SysML2 model under docs/sysml2/ (system/subsystem/unit/OTS parts) plus view definitions for rendered design diagrams.
• Integrated SysML2Tools into linting/version capture and CI document generation (rendering SVG views before Pandoc runs).
• Updated standards/agent guidance and refreshed design/verification/user-guide docs to reference the SysML2-driven structure.

Reviewed changes

Copilot reviewed 79 out of 80 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lint.ps1	Adds SysML2Tools linting to the compliance-tool lint step when docs/sysml2 exists.
docs/verification/ots.md	Expands OTS verification narrative to include additional production libraries.
docs/verification/introduction.md	Removes the hand-maintained software-structure tree from verification intro.
docs/verification/definition.yaml	Adds additional verification inputs (more unit/OTS verification docs).
docs/user_guide/introduction.md	Updates ZIP assertion schema documentation (zip.files[] and nested assertions).
docs/sysml2/views/design-views.sysml	Defines named SysML2 views to render into design-document SVGs.
docs/sysml2/model/shared.sysml	Adds Shared Package modeling and artifact-location comments.
docs/sysml2/model/ots.sysml	Adds OTS dependency modeling and artifact-location comments.
docs/sysml2/model/file-assert/utilities/zip-file-container.sysml	Models ZipFileContainer with source/test/design/verification/req references.
docs/sysml2/model/file-assert/utilities/temporary-directory.sysml	Models TemporaryDirectory with artifact references.
docs/sysml2/model/file-assert/utilities/path-helpers.sysml	Models PathHelpers with artifact references.
docs/sysml2/model/file-assert/utilities/i-file-container.sysml	Models IFileContainer with artifact references.
docs/sysml2/model/file-assert/utilities/directory-file-container.sysml	Models DirectoryFileContainer with artifact references.
docs/sysml2/model/file-assert/utilities.sysml	Models Utilities subsystem composition (parts for helpers/containers).
docs/sysml2/model/file-assert/selftest/validation.sysml	Models Validation unit with artifact references.
docs/sysml2/model/file-assert/selftest.sysml	Models SelfTest subsystem and its child unit.
docs/sysml2/model/file-assert/program.sysml	Models Program unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-zip-assert.sysml	Models FileAssertZipAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-yaml-assert.sysml	Models FileAssertYamlAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-xml-assert.sysml	Models FileAssertXmlAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-text-assert.sysml	Models FileAssertTextAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-test.sysml	Models FileAssertTest unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-rule.sysml	Models FileAssertRule unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-pdf-assert.sysml	Models FileAssertPdfAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-json-assert.sysml	Models FileAssertJsonAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-html-assert.sysml	Models FileAssertHtmlAssert unit with artifact references.
docs/sysml2/model/file-assert/modeling/file-assert-file.sysml	Models FileAssertFile unit with artifact references.
docs/sysml2/model/file-assert/modeling.sysml	Models Modeling subsystem composition (parts for assertion units).
docs/sysml2/model/file-assert/configuration/file-assert-data.sysml	Models FileAssertData unit with artifact references.
docs/sysml2/model/file-assert/configuration/file-assert-config.sysml	Models FileAssertConfig unit with artifact references.
docs/sysml2/model/file-assert/configuration.sysml	Models Configuration subsystem composition.
docs/sysml2/model/file-assert/cli/i-context.sysml	Models IContext unit with artifact references.
docs/sysml2/model/file-assert/cli/context.sysml	Models Context unit with artifact references.
docs/sysml2/model/file-assert/cli.sysml	Models Cli subsystem composition.
docs/sysml2/model/file-assert.sysml	Adds top-level FileAssertSystem model tying together subsystems, OTS, and shared package.
docs/design/ots.md	Expands OTS design to include production libraries and updates OTS categorization text.
docs/design/introduction.md	Replaces prose software-structure tree with SysML2-rendered diagram embedding and updated narrative.
docs/design/file-assert/utilities/zip-file-container.md	Embeds Utilities view diagram in unit design doc.
docs/design/file-assert/utilities/temporary-directory.md	Embeds Utilities view diagram in unit design doc.
docs/design/file-assert/utilities/path-helpers.md	Embeds Utilities view diagram in unit design doc.
docs/design/file-assert/utilities/i-file-container.md	Embeds Utilities view diagram in unit design doc.
docs/design/file-assert/utilities/directory-file-container.md	Embeds Utilities view diagram in unit design doc.
docs/design/file-assert/utilities.md	Embeds Utilities view diagram in subsystem design doc.
docs/design/file-assert/selftest/validation.md	Embeds SelfTest view diagram in unit design doc.
docs/design/file-assert/selftest.md	Embeds SelfTest view diagram in subsystem design doc.
docs/design/file-assert/program.md	Embeds system-level view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-zip-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-yaml-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-xml-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-text-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-test.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-rule.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-pdf-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-json-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-html-assert.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling/file-assert-file.md	Embeds Modeling view diagram in unit design doc.
docs/design/file-assert/modeling.md	Embeds Modeling view diagram in subsystem design doc.
docs/design/file-assert/configuration/file-assert-data.md	Embeds Configuration view diagram in unit design doc.
docs/design/file-assert/configuration/file-assert-config.md	Embeds Configuration view diagram in unit design doc.
docs/design/file-assert/configuration.md	Embeds Configuration view diagram in subsystem design doc.
docs/design/file-assert/cli/i-context.md	Embeds Cli view diagram in unit design doc.
docs/design/file-assert/cli/context.md	Embeds Cli view diagram in unit design doc.
docs/design/file-assert/cli.md	Embeds Cli view diagram in subsystem design doc.
docs/design/file-assert.md	Embeds system-level view diagram in system design doc.
docs/design/definition.yaml	Updates design-collection input list (new docs included; OTS-dependencies doc removed).
docs/design/file-assert/ots-dependencies.md	Removes the older OTS dependencies design document (superseded by new OTS structure).
AGENTS.md	Updates agent navigation guidance to prefer querying the SysML2 model first.
.versionmark.yaml	Adds SysML2Tools to version capture rules.
.reviewmark.yaml	Adds SysML2 model files to review coverage and refactors review-set context/scoping.
.gitignore	Ignores docs/design/generated/ (rendered SVG outputs).
.github/workflows/build.yaml	Adds SysML2Tools to version capture list and renders SysML2 views before Pandoc design build.
.github/standards/sysml2-modeling.md	Introduces modeling/view/rendering standards for SysML2 structure.
.github/standards/software-items.md	Notes SysML2 comment metadata as a discoverability aid for artifact locations.
.github/standards/reviewmark-usage.md	Updates ReviewMark guidance to include SysML2 model files and contextual review-set design.
.github/standards/design-documentation.md	Requires SysML2-rendered diagrams for the Software Structure section; clarifies version-number rules.
.github/skills/sysml2tools-query/SKILL.md	Adds a skill doc describing SysML2Tools query workflows for agents/reviewers.
.github/agents/template-sync.agent.md	Adds docs/sysml2/ as a template-sync work group.
.github/agents/formal-review.agent.md	Clarifies how to treat ReviewMark “context” vs “files under review”.
.cspell.yaml	Adds SysML2-related terms and dependency names to the spell-check dictionary.
.config/dotnet-tools.json	Pins SysML2Tools (demaconsulting.sysml2tools.tool) as a local .NET tool.

Comments suppressed due to low confidence (1)

docs/verification/ots.md:21

• SysML2Tools is now part of the CI pipeline (diagram rendering) and lint process, but it is not listed in the OTS verification strategy/items here. As written, the document suggests the pipeline is verified without accounting for the SysML2 model lint/render step that feeds into Pandoc inputs.

Please add SysML2Tools to the OTS lists and provide per-item verification evidence/docs (and requirements/design companions if you treat it as an OTS item like the other dotnet tools).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 84 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

docs/verification/ots.md:41

• Use US English spelling: change “artefacts” to “artifacts” in the qualification-evidence section.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 84 changed files in this pull request and generated 3 comments.