Clarify OtsSoftwareTests and improve project overview and hierarchy

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

@@ -31,8 +31,15 @@ For each group intersecting the requested scope, call a sub-agent with:
 
 - **context**:
   - Group scope and template URL from the `# Reference Template` section in `AGENTS.md`
+  - Applicable standards from the `# Standards Application` matrix in `AGENTS.md`
+    for the file types in the group scope
   - Project-specific names substitute for placeholders at matching path depth
-    (e.g. `SystemName` → `{SystemName}`, `system-name` → `{system-name}`)
+    (e.g. `MySystem` → `{SystemName}`, `my-system` → `{system-name}`)
+  - For files within `{system-name}/` subtrees in `docs/design/`, `docs/verification/`,
+    and `docs/reqstream/`: consult `docs/design/introduction.md` to determine whether
+    each item is a subsystem or unit, then select the appropriate template
+    (`subsystem-name.*` or `unit-name.*`) regardless of the item's folder depth —
+    do not infer item type from path depth alone
   - If a template counterpart cannot be fetched, skip the file and report it
 - **goal**:
   - Based on the given mode:
@@ -42,15 +49,38 @@ For each group intersecting the requested scope, call a sub-agent with:
     - **Scaffold** - fetch `repository-map.md` from the template URL in `AGENTS.md`
       to identify files that should exist but don't; for each, fetch the template,
       populate all sections, write the file; run `pwsh ./fix.ps1`
-    - **Recreate** - read the existing file in full, then fetch the template; use
-      full semantic understanding to map old content onto template sections,
-      splitting or consolidating as needed; create extra sections for any content
-      that has no template home; write the rebuilt file; run `pwsh ./fix.ps1`
-  - When writing any section: HTML comments and TODO placeholders in the template
-    are instructions - always resolve them to real content; infer from README,
-    related files, sibling docs, and path; if confident write directly; if
-    ambiguous offer 2–3 concrete options and ask the user; keep asking until they
-    answer - never leave a TODO unless the user explicitly requests it
+    - **Recreate** - fetch the template and use it as the blueprint for a
+      freshly authored document:
+      - Work through the template section by section; for each section, find
+        any `TEMPLATE-DIRECTIVE` blocks (both `<!-- TEMPLATE-DIRECTIVE: ... -->`
+        in markdown and `# <!-- TEMPLATE-DIRECTIVE: ... -->` in YAML) — execute
+        each directive (read specified standards, apply structural guidance,
+        substitute content), then **remove the directive block entirely** from
+        the output; gather the relevant technical details from all available
+        sources — the old file, README, related docs, sibling files, and any
+        other repo context — to populate that section correctly; the old file's
+        structure and headings are irrelevant; only its factual content is mined
+        as a source
+      - **Gap-check**: after all template sections are filled, scan the old
+        file once more for any technical information not yet captured; if
+        found, preserve it by appending new relevant sections at the end
+      - **Before writing**: do a mandatory self-check — for every section that
+        has a `TEMPLATE-DIRECTIVE` block in the template, explicitly state what
+        format the directive requires, then verify the drafted content matches
+        that format exactly (e.g. if the directive says "no sub-headings",
+        confirm there are no `###` headings inside that section; if it says
+        "bold-name paragraph blocks", confirm each entry is `**Name**: prose`
+        with no sub-heading); fix any mismatches before writing the file
+      - Write the rebuilt file; run `pwsh ./fix.ps1`
+  - When writing any section: `TEMPLATE-DIRECTIVE` blocks are directives —
+    execute them (read specified standards, apply structural guidance, substitute
+    content) and **remove the block entirely** from the written file; inline
+    `TODO:` placeholders in YAML string values (e.g. `title:`, `justification:`)
+    are content placeholders — always resolve them to real content; infer from
+    README, related files, sibling docs, and path; if confident write directly;
+    if ambiguous offer 2–3 concrete options and ask the user; keep asking until
+    they answer - never leave a TODO or TEMPLATE-DIRECTIVE in the output unless
+    the user explicitly requests it
 
 Collect sub-agent results and assemble the final report.
 
@@ -69,6 +99,8 @@ Collect sub-agent results and assemble the final report.
 - **Template**: {template path}
 - **Missing sections**: {list or "none"}
 - **Heading depth issues**: {list or "none"}
+- **Content format issues**: {list of sections where intra-section content did not
+  match the template comment's prescribed format, or "none"} *(Recreate only)*
 - **Action**: (Reported | Sections added | Created | Rebuilt | No template found)
 
 ## Summary

src/.github/standards/cpp-language.md

@@ -10,10 +10,11 @@ Read these standards first before applying this standard:
 
 - **`coding-principles.md`** - Universal coding principles and quality gates
 
-# Header Organization
+# File Organization
 
-Public headers live under `include/` mirroring the `src/` folder structure.
-Internal headers stay alongside their source files in `src/`:
+C++ projects use two parallel top-level folders — `include/` (public API) and
+`src/` (implementation) — both mirroring the same system/subsystem/unit hierarchy
+(test layout is covered in `cpp-testing.md`):
 
 ```text
 include/
@@ -28,6 +29,8 @@ src/
         └── {unit_name}_impl.hpp  # internal header - not part of the public API
 ```
 
+Subsystems may nest to any depth: `{system_name}[/{subsystem_name}...]/{unit_name}.hpp/cpp`.
+
 Protect every header with `#pragma once`.
 
 # Naming and Style Conventions

src/.github/standards/cpp-testing.md

@@ -13,13 +13,14 @@ Read these standards first before applying this standard:
 
 # File Organization
 
-Test files mirror the source tree under a `test/` root:
+Test files mirror the `src/` tree under `test/`, with `_tests` appended to the
+system folder name and each test file name:
 
 ```text
 test/
-└── {system_name}/
+└── {system_name}_tests/
     └── {subsystem_name}/
-        └── {unit_name}_tests.cpp   # unit tests for src/{system_name}/{subsystem_name}/{unit_name}.cpp
+        └── {unit_name}_tests.cpp   # unit tests for src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp
 ```
 
 # Package Reference

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

@@ -28,7 +28,10 @@ docs/design/
     └── {package-name}.md        # heading depth ##
 ```
 
-Subsystems may nest recursively. Each file's heading depth equals its folder depth under `docs/design/`.
+Subsystems may nest recursively, so nested paths may end in either a subsystem document
+(`docs/design/{system-name}[/{subsystem-name}...]/{subsystem-name}.md`) or a unit document
+(`docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md`).
+Each file's heading depth equals its folder depth under `docs/design/`.
 
 # introduction.md (MANDATORY)
 
@@ -56,6 +59,9 @@ write "N/A - {justification}" rather than removing any section:
 # Subsystem Design (MANDATORY)
 
 Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children.
+**Important**: A file at `{system-name}/**/*.md` may be either a subsystem or a unit. Always
+determine the correct classification from `docs/design/introduction.md` — folder depth does not
+determine classification.
 All sections mandatory; write "N/A - {justification}" rather than removing any section:
 
 - **Overview**: responsibility, boundaries, contained units
@@ -64,8 +70,11 @@ All sections mandatory; write "N/A - {justification}" rather than removing any s
 
 # Unit Design (MANDATORY)
 
-Place `{unit-name}.md` in the **parent** folder. All sections mandatory;
-write "N/A - {justification}" rather than removing any section:
+Place `{unit-name}.md` in the **parent** folder.
+**Important**: A file at `{system-name}/**/*.md` may be either a subsystem or a unit. Always
+determine the correct classification from `docs/design/introduction.md` — folder depth does not
+determine classification.
+All sections mandatory; write "N/A - {justification}" rather than removing any section:
 
 - **Purpose**: single responsibility
 - **Data Model**: fields, properties, types, invariants (IEC 62304 §5.4.2)

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

@@ -25,8 +25,8 @@ docs/reqstream/
 │   ├── platform-requirements.yaml  # Platform support requirements
 │   ├── {subsystem-name}.yaml        # Subsystem requirements
 │   ├── {subsystem-name}/            # Subsystem folder (kebab-case); may nest recursively
-│   │   ├── {child-subsystem}.yaml   # Child subsystem requirements
-│   │   ├── {child-subsystem}/       # Child subsystem folder
+│   │   ├── {subsystem-name}.yaml    # Child subsystem requirements
+│   │   ├── {subsystem-name}/        # Child subsystem folder
 │   │   └── {unit-name}.yaml         # Unit requirements
 │   └── {unit-name}.yaml             # System-level unit requirements
 ├── ots/                             # OTS items appear as a distinct section in reports
@@ -35,62 +35,66 @@ docs/reqstream/
     └── {package-name}.yaml          # Requirements for Shared Package dependencies
 ```
 
-Local items have matching relative paths across `docs/reqstream/`, `docs/design/`, and
-`docs/verification/`. OTS items appear in `docs/reqstream/ots/`, `docs/design/ots/`, and
-`docs/verification/ots/`. Shared Packages appear in `docs/reqstream/shared/`,
-`docs/design/shared/`, and `docs/verification/shared/`.
+Local items have matching relative paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`:
+
+- Requirements: `{system-name}[/{subsystem-name}...]/{item-name}.yaml`
+- Design: `{system-name}[/{subsystem-name}...]/{item-name}.md`
+- Verification: `{system-name}[/{subsystem-name}...]/{item-name}.md`
 
 # Requirements File Format
 
-```yaml
-sections:
-  - title: Functional Requirements
-    requirements:
-      - id: System-Component-Feature      # Used as-is in all reports - make it readable
-        title: The system shall perform the required function.
-        justification: |
-          Business rationale and any regulatory references.
-          # ReqStream extracts this field into the justifications report (--justifications)
-        children:                         # ReqStream validates this decomposition chain
-          - ChildSystem-Feature-Behavior  # Downward links only (see requirements-principles.md)
-        tests:                            # ReqStream matches these by method name in test results
-          - TestMethodName
-          - windows@PlatformSpecificTest  # Only test runs on Windows count as evidence
-```
+Each file adds requirements at exactly one level of the hierarchy. The file spells out
+its full ancestry as nested `{ItemName} Requirements` sections down to that level, then
+places requirements there. ReqStream merges identical section title paths across included
+files automatically. Always determine item classification from `docs/design/introduction.md` -
+folder depth does not determine whether an item is a subsystem or unit.
 
-# OTS Software Requirements
+Valid section nestings (names in `{braces}` are placeholders):
+
+```text
+{SystemName} Requirements              # system-level requirements
+├── {SubsystemName} Requirements       # root subsystem requirements
+│   ├── {SubsystemName} Requirements   # nested subsystem (may recurse)
+│   │   └── {UnitName} Requirements    # unit under a nested subsystem
+│   └── {UnitName} Requirements        # unit under a root subsystem
+└── {UnitName} Requirements            # unit directly under the system
+OTS Software Requirements          # OTS root section (fixed title)
+└── {OtsName} Requirements         # requirements for one OTS item
+Shared Package Requirements        # shared package root section (fixed title)
+└── {PackageName} Requirements     # requirements for one shared package
+```
 
-Use nested sections in `docs/reqstream/ots/` because ReqStream renders the `ots/`
-subtree as a distinct section in generated reports, separate from local
-system requirements:
+Each file implements one path through this tree:
 
 ```yaml
 sections:
-  - title: OTS Software Requirements
+  - title: '{SystemName} Requirements'
     sections:
-      - title: System.Text.Json
+      - title: '{SubsystemName} Requirements'
         requirements:
-          - id: SystemTextJson-Core-ReadJson
-            title: System.Text.Json shall be able to read JSON files.
-            tests:
-              - JsonReaderTests.TestReadValidJson
+          - id: System-Subsystem-Feature    # Used as-is in all reports - make it readable
+            title: The subsystem shall perform the required function.
+            justification: |              # ReqStream extracts this into the justifications report (--justifications)
+              Business rationale and any regulatory references.
+            tags:                         # Optional: categorize for filtering with --filter
+              - security
+            children:                     # Optional: ReqStream validates this decomposition chain
+              - System-Subsystem-Unit-Feat  # Downward links only (see requirements-principles.md)
+            tests:                        # ReqStream matches these by method name in test results
+              - TestMethodName
+              - windows@PlatformSpecificTest  # Only test runs on Windows count as evidence
 ```
 
-# Shared Package Requirements
+# Tags (OPTIONAL)
 
-Use nested sections in `docs/reqstream/shared/` - ReqStream renders the `shared/`
-subtree as a distinct section in reports, separate from local and OTS requirements:
+Tags are free-form - no mandatory vocabulary. Common tags: `security`, `safety`, `performance`,
+`compliance`, `reliability`, `critical`. Use `--filter` to selectively export or enforce subsets
+(OR logic across comma-separated tags):
 
-```yaml
-sections:
-  - title: Shared Package Requirements
-    sections:
-      - title: MyOrg.SharedLibrary
-        requirements:
-          - id: SharedLibrary-Core-ParseConfig
-            title: MyOrg.SharedLibrary shall parse configuration files.
-            tests:
-              - SharedLibraryIntegrationTests.TestParseValidConfig
+```bash
+dotnet reqstream --requirements requirements.yaml \
+  --filter security,critical \
+  --report docs/requirements_doc/generated/security_requirements.md
 ```
 
 # Semantic IDs (MANDATORY)
@@ -145,13 +149,9 @@ dotnet reqstream --requirements requirements.yaml \
 
 Before submitting requirements, verify:
 
-- [ ] All requirements have semantic IDs (`System-Section-Feature` pattern)
-- [ ] Every requirement links to at least one passing test
+- [ ] All requirements have semantic IDs (`System-Component-Feature` pattern)
+- [ ] Every requirement has a justification explaining business/regulatory need
+- [ ] Every requirement links to at least one test
 - [ ] Platform-specific requirements use source filters (`platform@TestName`)
-- [ ] Comprehensive justification explains business/regulatory need
-- [ ] Files organized under `docs/reqstream/` following the folder structure pattern above
-- [ ] All documentation folders use kebab-case names matching source code structure
-- [ ] OTS requirements placed in `ots/` subfolder
-- [ ] Shared Package requirements placed in `shared/` subfolder
-- [ ] Valid YAML syntax passes yamllint validation
-- [ ] Test result formats compatible (TRX, JUnit XML)
+- [ ] All files and folders use kebab-case names matching source code structure
+- [ ] All files are organized under `docs/reqstream/` following the folder structure above