Add SysML2 modeling standard and update related documentation

.cspell.yaml

@@ -28,6 +28,7 @@ words:
   - SARIF
   - sarifmark
   - sonarmark
+  - sysml
   - versionmark
   - Weasy
   - WeasyPrint

src/.github/agents/template-sync.agent.md

@@ -21,6 +21,8 @@ Delegate each group to a sub-agent.
 # Work Groups
 
 - **Root config files** - all non-collection files at the repository root
+- **`docs/sysml2/`** - SysML2 model files and rendered views (root-level flat folder,
+  not a Pandoc collection)
 - **One group per flat `docs/` folder** - e.g. `docs/build_notes/`, `docs/user_guide/`
 - **One group for root files in each of `docs/design/`, `docs/verification/`,
   `docs/reqstream/`** - e.g. `docs/design/introduction.md` — separate from the

src/.github/skills/sysml2tools-query/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: sysml2tools-query
+description: Query this repository's SysML2 architecture model (docs/sysml2/) to understand software structure, purpose, and relationships before deep-diving into source code. Use this when asked to understand the codebase, find which unit implements something, assess the impact of a change, or trace requirements to code.
+---
+
+# SysML2Tools Query Skill
+
+This repository models its software structure in SysML2 under `docs/sysml2/`. Prefer
+querying this model over grepping/reading source files when you need to understand
+*what* a piece of the system is, *why* it exists, or *what it depends on*.
+
+## Prerequisites
+
+The `sysml2tools` CLI is a local .NET tool pinned in `.config/dotnet-tools.json`.
+Restore it once per session if not already available:
+
+```pwsh
+dotnet tool restore
+```
+
+## Model files
+
+- `docs/sysml2/{system-name}.sysml` — one file per system: subsystems, units, purpose
+  `doc` comments, and dependency usages. A repository may contain more than one system.
+- `docs/sysml2/ots.sysml` — off-the-shelf (OTS) dependency parts (present when OTS items
+  exist).
+- `docs/sysml2/shared.sysml` — Shared Package parts (present when Shared Package items
+  exist).
+- `docs/sysml2/views/design-views.sysml` — named views rendered for the design document;
+  not usually needed for query workflows, but useful to see how diagrams are scoped.
+
+Always pass all `.sysml` files (or a glob covering them) to every `sysml2tools`
+invocation — the model spans multiple files and cross-references between them.
+Note: `sysml2tools` does not expand `*` glob patterns itself; either let the shell
+expand an unquoted wildcard, or list the files explicitly:
+
+```pwsh
+dotnet sysml2tools query list docs/sysml2/*.sysml
+```
+
+## Recommended workflow
+
+1. **Discover the system(s) present** — do not assume a fixed name:
+
+   ```pwsh
+   dotnet sysml2tools query list --kind "part def" docs/sysml2/*.sysml
+   ```
+
+   Look for the top-level part def with no containing part (or the one with the most
+   children) to identify each system's qualified name.
+
+2. **Get the full hierarchy** (subsystems and units) for a system found above:
+
+   ```pwsh
+   dotnet sysml2tools query describe -e <QualifiedName> docs/sysml2/*.sysml
+   ```
+
+   `describe` lists direct children; repeat on each child to walk deeper, or use
+   `query list` to see the full flat inventory.
+
+3. **Understand a specific unit's purpose** before opening its source file:
+
+   ```pwsh
+   dotnet sysml2tools query describe -e <QualifiedName> docs/sysml2/*.sysml
+   ```
+
+4. **Assess impact before editing a unit** — see what depends on it:
+
+   ```pwsh
+   dotnet sysml2tools query used-by -e <QualifiedName> docs/sysml2/*.sysml
+   dotnet sysml2tools query impact -e <QualifiedName> docs/sysml2/*.sysml
+   ```
+
+   Note: this only surfaces structural (typing/containment) references modeled in
+   `.sysml` — not full call-graph/behavioral dependencies. Confirm actual usage in source
+   before making impact-sensitive changes.
+
+5. **Trace requirements** linked to a unit, if modeled:
+
+   ```pwsh
+   dotnet sysml2tools query requirements -e <QualifiedName> docs/sysml2/*.sysml
+   ```
+
+6. **Search by name or kind** when the qualified name is unknown:
+
+   ```pwsh
+   dotnet sysml2tools query find --name <PartialOrFullName> docs/sysml2/*.sysml
+   dotnet sysml2tools query list --kind "part def" docs/sysml2/*.sysml
+   ```
+
+Use `--format json` on any query verb for machine-parsed output.
+
+## Fallback
+
+If the model is stale, doesn't yet cover a unit, or a query returns nothing useful,
+fall back to `grep`/`glob`/reading source directly. When you finish work that adds
+or changes a Unit/Subsystem, update the corresponding `.sysml` model file in the
+same change (mirrors the existing requirement to keep `docs/design/*.md` and
+`docs/reqstream/*.yaml` companion artifacts in sync). See the `sysml2-modeling.md`
+standard for full modeling and view-authoring conventions.
+
+## Validating changes to the model
+
+Before committing changes to any `.sysml` file, lint it:
+
+```pwsh
+dotnet sysml2tools lint docs/sysml2/*.sysml
+```

src/.github/standards/design-documentation.md

@@ -8,6 +8,8 @@ globs: ["docs/design/**/*.md"]
 
 - **`technical-documentation.md`** - General technical documentation standards
 - **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package)
+- **`sysml2-modeling.md`** - SysML2 model and view conventions feeding the Software Structure
+  section
 
 # Folder Structure
 
@@ -37,7 +39,8 @@ Must include:
 
 - **Purpose**: audience and compliance drivers
 - **Scope**: items covered and explicitly excluded (no test projects)
-- **Software Structure**: text tree showing all Systems/Subsystems/Units/OTS/Shared items
+- **Software Structure**: diagram(s) rendered from the SysML2 model under `docs/sysml2/`,
+  per `sysml2-modeling.md` — not a hand-maintained text tree
 - **Folder Layout**: text tree showing source folder structure
 - **Companion Artifact Structure**: parallel paths for requirements, design, verification, source, tests
 - **References** _(if applicable)_: external standards or specifications - only in `introduction.md`

src/.github/standards/reviewmark-usage.md

@@ -40,6 +40,7 @@ needs-review:
   - "!**/obj/**"
   - "requirements.yaml"
   - "docs/reqstream/**/*.yaml"
+  - "docs/sysml2/**/*.sysml"
   - "README.md"
   - "docs/user_guide/**/*.md"
   - "docs/design/**/*.md"
@@ -124,11 +125,12 @@ placeholders are always PascalCase (e.g., `{SystemName}`).
   promise; the structural mirror of the decomposition decision
 - **Title**: "Review that {SystemName} Decomposition Addresses the Stated Purpose"
 - **ID**: `Decomposition` (no system prefix — one per repository)
-- **Scope**: introduction.md (the decomposition narrative) and requirements.yaml
-  (the structural tree); no system-level detail
+- **Scope**: introduction.md (the decomposition narrative), the SysML2 model (the
+  authoritative structural tree), and requirements.yaml; no system-level detail
 - **File Path Patterns**:
   - Root requirements: `requirements.yaml`
   - Design introduction: `docs/design/introduction.md`
+  - SysML2 model: `docs/sysml2/**/*.sysml`
 - **Context Files**: `README.md`, `docs/user_guide/**/*.md`
 
 ## `{SystemName}-Architecture` Review (one per system)

src/.github/standards/sysml2-modeling.md

@@ -0,0 +1,159 @@
+---
+name: SysML2 Modeling
+description: Follow these standards when creating or modifying the SysML2 architecture
+  model, its rendered views, or the software structure it feeds into design documentation.
+globs: ["docs/sysml2/**/*.sysml"]
+---
+
+# SysML2 Modeling Standard
+
+## Required Standards
+
+Read these standards first before applying this standard:
+
+- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package)
+- **`design-documentation.md`** - Design document structure that embeds the diagrams this
+  standard produces
+
+## Purpose
+
+The repository's software structure is modeled in SysML2 under `docs/sysml2/` rather than
+hand-maintained as prose or an ASCII tree. The model is the authoritative, machine-queryable
+source of structure; rendered diagrams and `docs/design/introduction.md`'s narrative are
+generated/derived artifacts. AI agents should query the model (see `sysml2tools-query`
+skill) before deep-diving into source code to understand what a piece of the system is,
+why it exists, and what it depends on.
+
+## Repository Structure
+
+```text
+docs/sysml2/
+├── {system-name}.sysml           # one file per system: subsystems, units, doc comments
+├── ots.sysml                     # OTS dependency parts (optional; if OTS items exist)
+├── shared.sysml                  # Shared Package parts (optional; if Shared Packages exist)
+└── views/
+    └── design-views.sysml        # named view usages rendered for the design document
+```
+
+There is no separate "stable entry point" file — a repository may contain multiple systems,
+so no single alias name would generalize. Agents discover the system(s) present by running
+`query list --kind "part def"` or `query find` (see the `sysml2tools-query` skill) over
+`docs/sysml2/*.sysml`, not by assuming a fixed name.
+
+Always pass the full set of `.sysml` files (or an equivalent glob) to every `sysml2tools`
+invocation — the model spans multiple files and cross-references between them. Note:
+`sysml2tools` does not expand `*` glob patterns itself; either let the shell expand an
+unquoted wildcard, or list files explicitly in scripts/CI.
+
+## Model Content
+
+- `{system-name}.sysml` defines one `part def` per System, Subsystem, and Unit, with a
+  `doc /* ... */` comment on each stating its purpose — mirroring what would otherwise be
+  written as prose in `docs/design/introduction.md`'s Software Structure section.
+- Subsystems nest as `part` usages inside their parent's `part def`, matching the Software
+  Item Hierarchy in `software-items.md`.
+- `ots.sysml` / `shared.sysml` define one `part def` per OTS item / Shared Package, referenced
+  as `part` usages from the system(s) that depend on them.
+
+## Views (`docs/sysml2/views/design-views.sysml`)
+
+Views control what gets rendered into diagrams for the design document. Use named `view`
+**usages** (not `view def` **definitions**) — `expose` is only valid inside a usage:
+
+```sysml
+package {SystemName} {
+    view SoftwareStructureView {
+        expose {SystemName};         // whole package: system + subsystems + units
+        render asTreeDiagram;
+    }
+
+    view {SystemName}View {
+        expose {SystemName}System;   // system def only, not expanded into subsystems
+        render asTreeDiagram;
+    }
+
+    view {SubsystemName}View {
+        expose {SubsystemName};      // one subsystem def only
+        render asTreeDiagram;
+    }
+}
+```
+
+**Critical distinction** (do not confuse these — this cost significant trial-and-error to
+discover): `expose <name>;` is what scopes a rendered diagram's content (the union of the
+named element's containment subtree). `render <kind>;` selects a rendering *style* (e.g.
+`asTreeDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named
+`view Name { ... }` **usage**; it is a syntax/semantic error inside a `view def Name { ... }`
+**definition**. `expose` targets must be `::`-qualified or locally-resolvable names, not
+dotted member-access chains (`expose foo.bar;` is invalid — use `expose Bar;`).
+
+**Naming convention** — one `View` suffix per rendered diagram, no `System`/`Subsystem`
+suffix duplication:
+
+- `SoftwareStructureView` - full detail: every system, subsystem, and unit in one diagram
+- `{SystemName}View` - one per system, direct members only (not expanded into subsystems)
+- `{SubsystemName}View` - one per subsystem (at any nesting depth), that subsystem's own
+  members only
+
+When a repository has multiple systems, `SoftwareStructureView` may expose each system's
+package individually (`expose {SystemNameA}; expose {SystemNameB};`) or the whole workspace,
+whichever produces a single coherent overview diagram.
+
+## Diagram Embedding
+
+Render with:
+
+```pwsh
+dotnet sysml2tools render `
+  docs/sysml2/{system-name}.sysml docs/sysml2/ots.sysml docs/sysml2/shared.sysml `
+  docs/sysml2/views/design-views.sysml --output docs/design/generated --format svg
+```
+
+With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view
+in one invocation, one file per view, using each view's own name as the filename
+(`{ViewName}.svg`) — no post-render rename step is needed.
+
+Embed diagrams in `docs/design/` per this rule: every design doc for an item embeds the
+diagram for the narrowest view that still shows that item's own immediate structure —
+
+- `docs/design/introduction.md` — `SoftwareStructureView.svg` (the full-detail overview)
+- `docs/design/{system-name}.md` and every unit doc for a unit directly under the system
+  (no subsystem parent) — `{SystemName}View.svg`
+- `docs/design/{system-name}/{subsystem-name}.md` and every unit doc nested under that
+  subsystem (at any depth) — `{SubsystemName}View.svg`
+
+Place the image directly under the file's top-level heading, before its first prose
+subsection, e.g. `![{Name} Structure]({ViewName}.svg)`.
+
+## Build and Lint Integration
+
+- `sysml2tools lint docs/sysml2/*.sysml` belongs in `lint.ps1`'s compliance-tools section,
+  **not** as a separate step in the CI design-document job — `lint.ps1` gates every later
+  job (including document generation) transitively, so linting the model there is both
+  earlier and non-duplicated.
+- The CI design-document job renders the views (see the render command above) before running
+  Pandoc, so generated SVGs exist before HTML generation. Rename/stable-filename workarounds
+  are unnecessary since view names are stable by definition.
+- Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to
+  `.versionmark.yaml`'s captured tool list.
+
+## Fallback
+
+If the model is stale, doesn't yet cover an item, or a query returns nothing useful, fall
+back to `grep`/`glob`/reading source directly. When work adds or changes a Unit/Subsystem,
+update the corresponding `.sysml` model file in the same change — this mirrors the existing
+requirement to keep `docs/design/*.md` and `docs/reqstream/*.yaml` companion artifacts in
+sync.
+
+## Quality Checks
+
+- [ ] Every System/Subsystem/Unit in `docs/design/introduction.md` has a matching `part def`
+  in `docs/sysml2/{system-name}.sysml` with a purpose `doc` comment
+- [ ] `docs/sysml2/views/design-views.sysml` uses `view Name { expose ...; }` usages, not
+  `view def` definitions
+- [ ] View names follow the `SoftwareStructureView` / `{SystemName}View` /
+  `{SubsystemName}View` convention
+- [ ] `sysml2tools lint` passes on all `.sysml` files
+- [ ] Rendered diagrams are embedded in every design doc per the Diagram Embedding rule
+- [ ] `sysml2tools` is present in `lint.ps1`, `.config/dotnet-tools.json`, and
+  `.versionmark.yaml`

src/AGENTS.md

@@ -27,6 +27,7 @@
 │   ├── requirements_doc/
 │   ├── requirements_report/
 │   ├── reqstream/
+│   ├── sysml2/
 │   ├── user_guide/
 │   └── verification/
 ├── src/
@@ -50,10 +51,12 @@ This repository follows a reference template for structure and file conventions.
 
 # Codebase Navigation (ALL Agents)
 
-When working with source code, design, or requirements artifacts, read
-`docs/design/introduction.md` first. It provides the software structure,
-folder layout, and companion artifact locations. Use it as the primary map
-before searching the filesystem.
+When working with source code, design, or requirements artifacts, query the SysML2
+architecture model under `docs/sysml2/` first (see the `sysml2tools-query` skill) to
+understand software structure, purpose, and relationships. Fall back to
+`docs/design/introduction.md` for the human-facing narrative, folder layout, and
+companion artifact locations, and use it as the primary map when the model doesn't
+yet cover something.
 
 # Key Configuration Files
 
@@ -68,6 +71,7 @@ before searching the filesystem.
 - **`package.json`** - Node.js dependencies for formatting tools
 - **`requirements.yaml`** - Root requirements file with includes
 - **`pip-requirements.txt`** - Python dependencies for yamllint and yamlfix
+- **`docs/sysml2/`** - SysML2 architecture model; authoritative source for software structure
 - **`fix.ps1`** - Applies all auto-fixers silently (dotnet format, markdown, YAML). Always exits 0.
 - **`build.ps1`** - Builds the solution and runs all tests.
 
@@ -86,6 +90,7 @@ from `.github/standards/`. Use this matrix to determine which to load:
 - **Design docs**: `software-items.md`, `design-documentation.md`, `technical-documentation.md`
 - **Verification docs**: `software-items.md`, `verification-documentation.md`, `technical-documentation.md`
 - **Review configuration**: `software-items.md`, `reviewmark-usage.md`
+- **Software structure**: `sysml2-modeling.md`
 - **Any documentation**: `technical-documentation.md`
 
 Load only the standards relevant to your specific task scope.
@@ -140,7 +145,7 @@ responsibility - invoke the lint-fix agent once before submitting a pull request
 ## CI Quality Tools
 
 CI runs `lint.ps1` which checks: markdownlint-cli2, cspell, yamllint, dotnet format,
-reqstream, versionmark, and reviewmark.
+reqstream, versionmark, reviewmark, and sysml2tools.
 
 # Scope Discipline (ALL Agents Must Follow)