Add SysML2 architecture model support and update documentation

.config/dotnet-tools.json

@@ -61,6 +61,12 @@
       "commands": [
         "fileassert"
       ]
+    },
+    "demaconsulting.sysml2tools.tool": {
+      "version": "0.1.0-beta.5",
+      "commands": [
+        "sysml2tools"
+      ]
     }
   }
 }

.cspell.yaml

@@ -28,7 +28,9 @@ words:
   - dogfooding
   - enation
   - fileassert
+  - filesystemglobbing
   - fontconfig
+  - htmlagilitypack
   - initialise
   - initialized
   - initialisation
@@ -38,6 +40,7 @@ words:
   - Pango
   - pandoc
   - pandoctool
+  - pdfpig
   - recognized
   - recognise
   - recognises
@@ -53,12 +56,15 @@ words:
   - serialises
   - sonarcloud
   - sonarmark
+  - sysml
+  - sysml2tools
   - unrecognized
   - unrecognised
   - versionmark
   - Weasyprint
   - weasyprinttool
   - xunit
+  - yamldotnet
   - yamlfix
 
 # Exclude common build artifacts, dependencies, and vendored third-party code

.github/agents/formal-review.agent.md

@@ -31,12 +31,14 @@ standards from the selection matrix in AGENTS.md.
 1. Download the review checklist from
    <https://github.com/demaconsulting/ContinuousCompliance/raw/refs/heads/main/docs/review-template/review-template.md>.
    If the download fails, report the failure rather than proceeding without the template.
-2. Use `dotnet reviewmark --elaborate {review-set}` to get the files to review
-3. Review all files holistically, checking for cross-file consistency and
-   compliance with the review checklist
-4. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`.
+2. Run `dotnet reviewmark --elaborate {review-set}`. Read all files listed under
+   `## Context` first — these are reference material, not under review — then review
+   all files listed under `## Files` holistically, using the context to understand
+   the intended role and scope within the broader system, and checking for cross-file
+   consistency and compliance with the review checklist.
+3. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`.
    This directory holds formal review artifacts, not agent logs.
-5. Generate a completion report per the AGENTS.md reporting requirements.
+4. Generate a completion report per the AGENTS.md reporting requirements.
 
 # Report Template
 

.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
 
@@ -30,15 +32,15 @@ docs/design/
 
 All sections in every file are mandatory; write "N/A - {justification}" rather than removing any.
 Determine subsystem vs. unit classification from `docs/design/introduction.md` — folder depth does not determine classification.
-Do not record version numbers anywhere in design documentation — version information is managed in SBOMs.
 
 # introduction.md (MANDATORY)
 
 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`
@@ -98,6 +100,12 @@ For each Shared Package, create `docs/design/shared/{package-name}.md` (`##` hea
 - Use Mermaid diagrams to supplement (not replace) text
 - Use verbal cross-references ("see _Parser Design_") - not markdown hyperlinks (break in PDF)
 - Provide sufficient detail for formal code review
+- Do not record version numbers in design documentation — they go stale with dependency updates and
+  are managed in SBOMs. Version numbers are pinned release versions (e.g., `1.2.3`, `v2.0.1`).
+  The following are **not** version numbers and are permitted:
+  - Language/platform standards: `netstandard2.0`, `net10.0`, `C++20`, `C# 12` (stable standard identifiers)
+  - Protocol standards: `TLS 1.3`, `HTTP/2` (stable specifications)
+  - Placeholders: `0.0.0` (signals "not yet assigned")
 
 # Quality Checks