Refactor SysML2 model structure and enhance artifact metadata

.config/dotnet-tools.json

@@ -73,7 +73,7 @@
       "rollForward": false
     },
     "demaconsulting.sysml2tools.tool": {
-      "version": "0.1.0-beta.4",
+      "version": "0.1.0-beta.5",
       "commands": [
         "sysml2tools"
       ],

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

@@ -20,30 +20,65 @@ 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
+- `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/shared.sysml` — Shared Package parts (present when Shared Package items
+- `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;
-  not usually needed for query workflows, but useful to see how diagrams are scoped.
+- `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.
-Note: `sysml2tools` does not expand `*` glob patterns itself; either let the shell
-expand an unquoted wildcard, or list the files explicitly:
+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/*.sysml
+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 now, since this repo
+still uses 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 DictionaryMark::YamlDictionaryLoader 'docs/sysml2/model/**/*.sysml'
+```
+
+```text
+- Documentation: Loads YAML flat-dictionary files.
+- Comment: Source: src/DemaConsulting.DictionaryMark/Dictionary/YamlDictionaryLoader.cs
+- Comment: Test: test/DemaConsulting.DictionaryMark.Tests/Dictionary/YamlDictionaryLoaderTests.cs
+- Comment: Design: docs/design/dictionary-mark/dictionary/yaml-loader.md
+- Comment: Verification: docs/verification/dictionary-mark/dictionary/yaml-loader.md
+- Comment: Requirements: docs/reqstream/dictionary-mark/dictionary/yaml-loader.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/*.sysml
+   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
@@ -52,23 +87,25 @@ dotnet sysml2tools query list docs/sysml2/*.sysml
 2. **Get the full hierarchy** (subsystems and units) for a system found above:
 
    ```pwsh
-   dotnet sysml2tools query describe -e <QualifiedName> docs/sysml2/*.sysml
+   dotnet sysml2tools query describe -e <QualifiedName> 'docs/sysml2/model/**/*.sysml'
    ```
 
-   `describe` lists direct children; repeat on each child to walk deeper, or use
-   `query list` to see the full flat inventory.
+   `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** before opening its source file:
+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/*.sysml
+   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/*.sysml
-   dotnet sysml2tools query impact -e <QualifiedName> docs/sysml2/*.sysml
+   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
@@ -78,24 +115,24 @@ dotnet sysml2tools query list docs/sysml2/*.sysml
 5. **Trace requirements** linked to a unit, if modeled:
 
    ```pwsh
-   dotnet sysml2tools query requirements -e <QualifiedName> docs/sysml2/*.sysml
+   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/*.sysml
-   dotnet sysml2tools query list --kind "part def" docs/sysml2/*.sysml
+   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 in the
-same change (mirrors the existing requirement to keep `docs/design/*.md` and
+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.
 
@@ -104,5 +141,5 @@ standard for full modeling and view-authoring conventions.
 Before committing changes to any `.sysml` file, lint it:
 
 ```pwsh
-dotnet sysml2tools lint docs/sysml2/*.sysml
+dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'
 ```

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

.github/standards/sysml2-modeling.md

@@ -28,33 +28,96 @@ why it exists, and what it depends on.
 
 ```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)
+├── model/
+│   ├── {system-name}.sysml            # system-level part def only (no subsystems/units inline)
+│   ├── {system-name}/
+│   │   ├── {subsystem-name}.sysml     # subsystem part def; nests further for sub-subsystems
+│   │   └── {subsystem-name}/
+│   │       └── {unit-name}.sysml      # one file per unit
+│   ├── 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
+    └── design-views.sysml             # named view usages rendered for the design document
 ```
 
+`docs/sysml2/model/` mirrors the same folder shape as `docs/design/`, `docs/reqstream/`, and
+`docs/verification/` — one `.sysml` file per System/Subsystem/Unit, at the same nesting depth
+as that item's companion design/requirements/verification files. This keeps each file small
+and keeps PRs that touch one unit's model from producing unrelated diffs in unrelated units.
+`docs/sysml2/views/` is a sibling of `model/`, not nested inside it, so a single
+`docs/sysml2/model/**/*.sysml` glob never needs to exclude view files (`sysml2tools` has no
+exclude-glob syntax).
+
 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.
+`docs/sysml2/model/**/*.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.
+invocation — the model spans multiple files and cross-references between them; files sharing
+the same `package Name { ... }` merge into one namespace automatically with no `import`
+required, as long as all files are passed together. As of `sysml2tools` 0.1.0-beta.5,
+`lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into
+subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`)
+and let the tool resolve it — do not rely on the shell to expand it, and do not quote-strip
+the pattern before it reaches the tool. Quoting keeps the behavior identical across
+PowerShell and bash, since neither shell needs to (or reliably does) expand `**` itself.
 
 ## 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`.
+- `{system-name}.sysml` defines one `part def` for the System only, with `part` usages
+  referencing its direct Subsystems/Units (defined in their own files, see below).
+- Each `{subsystem-name}.sysml` / `{unit-name}.sysml` defines exactly one `part def`, with a
+  `doc /* ... */` comment stating its purpose — mirroring what would otherwise be written as
+  prose in `docs/design/introduction.md`'s Software Structure section. Subsystem files add
+  `part` usages for their own direct children (nested subsystems or units), 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.
 
+## Artifact-Location Comments
+
+Every System/Subsystem/Unit `part def` records where its companion artifacts live, as named
+`comment` elements — not `attribute`s (attribute values are not surfaced by `sysml2tools query
+describe`, even in JSON output; comments are). Comments have zero effect on rendered diagrams
+(verified: a part def with several comments attached renders with no extra nodes or size
+change) and are fully returned by `query describe`, in declaration order, as
+`Comment: ...` summary lines — this is how an agent gets every artifact location for a unit
+in a single query, without grepping the source tree.
+
+Use these comment names, in this order, when applicable to the item:
+
+```sysml
+part def {UnitName} {
+    doc /* One-line purpose statement. */
+
+    comment sourceRef /* Source: {path to the unit's source file} */
+    comment testRef /* Test: {path to the unit's test file} */
+    comment designRef /* Design: {path to the unit's design doc} */
+    comment verificationRef /* Verification: {path to the unit's verification doc} */
+    comment reqRef /* Requirements: {path to the unit's reqstream file} */
+}
+```
+
+Not every item has all five:
+
+- **Systems and Subsystems** have no `sourceRef` (no single source file represents a whole
+  system or subsystem) — use `testRef` for the subsystem-level test file when one exists.
+- **Units without a dedicated companion doc** (e.g. small data-model types documented inline
+  within their subsystem's design doc rather than in their own file) point `designRef` /
+  `verificationRef` / `reqRef` at the subsystem-level doc, with a short parenthetical note,
+  e.g. `/* Design: docs/design/{system}/{subsystem}.md (documented as a supporting value type) */`.
+- **Units without a dedicated test file** (exercised only indirectly through another unit's
+  tests) omit `testRef` entirely rather than pointing at an unrelated test file.
+- **OTS items** have no `sourceRef`/`testRef` (no local integration code); use `designRef`
+  (when the optional design doc exists) / `verificationRef` / `reqRef` only.
+
+This is prose-searchable metadata only — it is not a substitute for the authoritative
+requirements/design/verification artifacts, and it does not replace ReqStream as the
+requirements source of truth. (This repository currently keeps requirements traceability in
+ReqStream; a future migration to native SysML2 `requirement`/`satisfy` modeling is a separate,
+not-yet-scheduled change.)
+
 ## Views (`docs/sysml2/views/design-views.sysml`)
 
 Views control what gets rendered into diagrams for the design document. Use named `view`
@@ -101,12 +164,15 @@ whichever produces a single coherent overview diagram.
 
 ## Diagram Embedding
 
-Render with:
+Render with a single quoted recursive glob for the model tree, plus the views file
+(`sysml2tools` 0.1.0-beta.5+ expands and recurses `**` internally, so no shell-side globbing
+or explicit per-file listing is needed):
 
 ```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
+  --output docs/design/generated --format svg `
+  'docs/sysml2/model/**/*.sysml' `
+  'docs/sysml2/views/design-views.sysml'
 ```
 
 With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view
@@ -127,13 +193,18 @@ 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.
+- `sysml2tools lint` 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.
+  Pass a single quoted recursive glob, e.g. `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'`
+  — `sysml2tools` (0.1.0-beta.5+) expands and recurses this itself, so no
+  `Get-ChildItem`/shell-side globbing is needed.
 - 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.
+  are unnecessary since view names are stable by definition. Pass the model and views globs as
+  separate quoted arguments (e.g. `'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`)
+  — plain PowerShell (the default shell) is sufficient; no `shell: bash`/`shopt -s globstar`
+  workaround is needed.
 - Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to
   `.versionmark.yaml`'s captured tool list.
 
@@ -148,7 +219,12 @@ 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
+  in its own file under `docs/sysml2/model/`, at the same folder depth as its companion
+  design/reqstream/verification files, with a purpose `doc` comment
+- [ ] Every Unit-level `part def` has `sourceRef`/`testRef`/`designRef`/`verificationRef`/
+  `reqRef` comments where applicable (see Artifact-Location Comments for documented
+  exceptions); System/Subsystem `part def`s have `testRef`/`designRef`/`verificationRef`/
+  `reqRef` but no `sourceRef`
 - [ ] `docs/sysml2/views/design-views.sysml` uses `view Name { expose ...; }` usages, not
   `view def` definitions
 - [ ] View names follow the `SoftwareStructureView` / `{SystemName}View` /

.github/workflows/build.yaml

@@ -740,13 +740,13 @@ jobs:
         run: mkdir -p docs/design/generated
 
       - name: Render Software Structure diagrams with SysML2Tools
-        shell: bash
+        shell: pwsh
         run: >
           dotnet sysml2tools render
           --output docs/design/generated
           --format svg
-          docs/sysml2/*.sysml
-          docs/sysml2/views/design-views.sysml
+          'docs/sysml2/model/**/*.sysml'
+          'docs/sysml2/views/design-views.sysml'
 
       - name: Generate Design HTML with Pandoc
         shell: bash