Synchronize SysML2 design files and update documentation

.config/dotnet-tools.json

@@ -71,6 +71,13 @@
         "fileassert"
       ],
       "rollForward": false
+    },
+    "demaconsulting.sysml2tools.tool": {
+      "version": "0.1.0-beta.5",
+      "commands": [
+        "sysml2tools"
+      ],
+      "rollForward": false
     }
   }
 }

.cspell.yaml

@@ -88,6 +88,7 @@ words:
   - sonar
   - sonarmark
   - subclassable
+  - sysml
   - CODEDOC
   - constexpr
   - cout

.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

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

@@ -0,0 +1,145 @@
+---
+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/model/{system-name}.sysml` — system-level `part def` only (no subsystems/units
+  inline). A repository may contain more than one system.
+- `docs/sysml2/model/{system-name}/{subsystem-name}.sysml` and
+  `docs/sysml2/model/{system-name}/{subsystem-name}/{unit-name}.sysml` — one file per
+  Subsystem/Unit, nested to mirror the same folder depth as that item's companion
+  `docs/design/`, `docs/reqstream/`, and `docs/verification/` files.
+- `docs/sysml2/model/ots.sysml` — off-the-shelf (OTS) dependency parts (present when OTS items
+  exist).
+- `docs/sysml2/model/shared.sysml` — Shared Package parts (present when Shared Package items
+  exist).
+- `docs/sysml2/views/design-views.sysml` — named views rendered for the design document; a
+  sibling of `model/`, not nested inside it. 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; files that
+reopen the same `package Name { ... }` from different files merge into one namespace
+automatically, no `import` required. As of `sysml2tools` 0.1.0-beta.5, every subcommand
+(`lint`, `render`, `query`) expands `*`/`**` glob patterns internally and recurses
+correctly — pass a single **quoted** glob string and let the tool resolve it, rather than
+relying on the shell (quoting works identically in both PowerShell and bash):
+
+```pwsh
+dotnet sysml2tools query list 'docs/sysml2/model/**/*.sysml'
+```
+
+## Artifact-location metadata
+
+Every System/Subsystem/Unit `part def` carries named `comment` elements pointing at its
+companion artifacts (source, test, design, verification, and — for repositories that still
+use ReqStream — requirements file). `query describe` returns every comment attached to
+an element, so one query gets you every artifact location for that item without grepping the
+source tree:
+
+```pwsh
+dotnet sysml2tools query describe -e {SystemName}::{UnitName} 'docs/sysml2/model/**/*.sysml'
+```
+
+```text
+- Documentation: One-line purpose statement for the unit.
+- Comment: Source: src/{Project}/{Subsystem}/{UnitName}.cs
+- Comment: Test: test/{Project}.Tests/{Subsystem}/{UnitName}Tests.cs
+- Comment: Design: docs/design/{system-name}/{subsystem-name}/{unit-name}.md
+- Comment: Verification: docs/verification/{system-name}/{subsystem-name}/{unit-name}.md
+- Comment: Requirements: docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml
+```
+
+Not every item has all five comments — Systems/Subsystems have no `Source` comment, and
+units without a dedicated companion doc point at their parent's doc instead (see the
+Artifact-Location Comments section of `sysml2-modeling.md` for the full rules). Prefer these
+paths over guessing a file location from the unit name; fall back to `grep`/`glob` only when
+a comment is missing or the model is stale.
+
+## Recommended workflow
+
+1. **Discover the system(s) present** — do not assume a fixed name:
+
+   ```pwsh
+   dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.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/model/**/*.sysml'
+   ```
+
+   `describe` lists direct children and every artifact-location comment; repeat on each
+   child to walk deeper, or use `query list` to see the full flat inventory.
+
+3. **Understand a specific unit's purpose and find its files** before opening its source
+   file — `describe` returns both the purpose `doc` and every `Comment:` artifact-location
+   line in one call (see Artifact-location metadata above):
+
+   ```pwsh
+   dotnet sysml2tools query describe -e <QualifiedName> 'docs/sysml2/model/**/*.sysml'
+   ```
+
+4. **Assess impact before editing a unit** — see what depends on it:
+
+   ```pwsh
+   dotnet sysml2tools query used-by -e <QualifiedName> 'docs/sysml2/model/**/*.sysml'
+   dotnet sysml2tools query impact -e <QualifiedName> 'docs/sysml2/model/**/*.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/model/**/*.sysml'
+   ```
+
+6. **Search by name or kind** when the qualified name is unknown:
+
+   ```pwsh
+   dotnet sysml2tools query find --name <PartialOrFullName> 'docs/sysml2/model/**/*.sysml'
+   dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.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 (including its artifact-location
+comments) 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'
+```

.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`

.github/standards/reviewmark-usage.md

@@ -20,7 +20,8 @@ review, organizes them into review-sets, and generates review plans and reports.
 
 - **Lint Configuration**: `dotnet reviewmark --lint`
 - **Elaborate Review-Set**: `dotnet reviewmark --elaborate {review-set}`
-- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce` (exits non-zero if any files are uncovered)
+- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce`
+  (exits non-zero if any files are uncovered)
 
 ## Repository Structure
 
@@ -39,6 +40,7 @@ needs-review:
   - "!**/obj/**"
   - "requirements.yaml"
   - "docs/reqstream/**/*.yaml"
+  - "docs/sysml2/**/*.sysml"
   - "README.md"
   - "docs/user_guide/**/*.md"
   - "docs/design/**/*.md"
@@ -97,7 +99,7 @@ as global context.
 | `{SystemName}-AllRequirements` | Parent system design doc + `docs/reqstream/{system-name}.yaml` |
 | `{SystemName}-{UnitName}` (direct unit) | Parent system design doc + parent system requirements |
 | `{SystemName}-{SubsystemName}` (subsystem) | Parent system design doc + parent system requirements |
-| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs, system + subsystem requirements |
+| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs + requirements |
 
 # Review-Set Organization
 
@@ -119,13 +121,16 @@ placeholders are always PascalCase (e.g., `{SystemName}`).
 
 ## `Decomposition` Review (only one per repository)
 
-- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing promise; the structural mirror of the decomposition decision
+- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing
+  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)
@@ -205,7 +210,8 @@ placeholders are always PascalCase (e.g., `{SystemName}`).
   - Tests (C# example): `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.cs`
   - Source (snake_case C++ example): `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp`
   - Tests (snake_case C++ example): `test/{system_name}_tests[/{subsystem_name}...]/{unit_name}_tests.cpp`
-- **Context Files**: Parent system design + requirements; add subsystem design + requirements for each subsystem level above the unit.
+- **Context Files**: Parent system design + requirements; add subsystem design +
+  requirements for each subsystem level above the unit.
 
 ## `OTS-{OtsName}` Review (one per OTS item)
 

.github/standards/software-items.md

@@ -130,3 +130,8 @@ the item is correct, well-designed, and proven to work:
 - **Verification Design** - HOW the requirements will be tested (applies to all item types)
 - **Source code** - The implementation of the design (local units only; not applicable to OTS or Shared Package)
 - **Tests** - PROOF the item does WHAT it is required to do (applies to all item types)
+
+Where the repository models its software structure in SysML2, each item's part def carries
+`comment` metadata pointing at these same artifact locations (`sourceRef`/`testRef`/
+`designRef`/`verificationRef`/`reqRef`) so agents can query them directly — see
+`sysml2-modeling.md`.