Add software structure tree diagram, system design doc, integration tests, and review-set restructuring

.reviewmark.yaml

@@ -24,6 +24,16 @@ evidence-source:
 # Each review-set groups requirements, source, and tests for a coherent software unit
 # so that an AI-assisted review can verify consistency across the full evidence chain.
 reviews:
+  # System-level review — requirements, design, integration tests, and platform support
+  - id: ReqStream-System
+    title: Review of ReqStream System-Level Design and Requirements
+    paths:
+      - "docs/reqstream/reqstream-system.yaml"
+      - "docs/reqstream/platform-requirements.yaml"
+      - "docs/design/introduction.md"
+      - "docs/design/system.md"
+      - "test/**/IntegrationTests.cs"
+
   # Software unit reviews - one per class
   - id: ReqStream-Context
     title: Review of ReqStream Context Unit
@@ -78,19 +88,8 @@ reviews:
       - "src/**/Linter.cs"
       - "test/**/LinterTests.cs"
 
-  # Platform and OTS dependency reviews
-  - id: Platform-Support
-    title: Review of Platform and Runtime Support Requirements
-    paths:
-      - "docs/reqstream/platform-requirements.yaml"
-
-  - id: OTS-Dependencies
-    title: Review of Off-The-Shelf Software Dependencies
+  # Full requirements review — all requirements files reviewed together for completeness and consistency
+  - id: ReqStream-AllRequirements
+    title: Review of All ReqStream Requirements for Consistency
     paths:
-      - "docs/reqstream/ots-mstest.yaml"
-      - "docs/reqstream/ots-reqstream.yaml"
-      - "docs/reqstream/ots-buildmark.yaml"
-      - "docs/reqstream/ots-versionmark.yaml"
-      - "docs/reqstream/ots-sarifmark.yaml"
-      - "docs/reqstream/ots-sonarmark.yaml"
-      - "docs/reqstream/ots-reviewmark.yaml"
+      - "docs/reqstream/**/*.yaml"

README.md

@@ -166,19 +166,19 @@ with sections, requirements, test mappings, and file includes.
 sections:
   - title: System Security
     requirements:
-      - id: SYS-SEC-001
+      - id: Security-CredentialAuthentication
         title: The system shall support credentials authentication.
         justification: |
           Authentication is critical to ensure only authorized users can access the system.
           This requirement establishes the foundation for our security posture.
         children: # Support linking to child requirements
-          - AUTH-001
+          - Auth-CredentialValidation
 
   - title: Data Management
     sections:
       - title: User Authentication
         requirements:
-          - id: AUTH-001
+          - id: Auth-CredentialValidation
             title: All requests shall have their credentials authenticated before being processed.
             justification: |
               Prevents unauthorized access to system resources and ensures compliance with
@@ -190,7 +190,7 @@ sections:
 
       - title: Logging
         requirements:
-          - id: DATA-001
+          - id: Logging-RequestLogging
             title: All requests shall be logged.
 
 # Include other requirement files - may contain requirements and/or test mappings
@@ -200,7 +200,7 @@ includes:
 
 # Test mappings support defining tests separate from requirements
 mappings:
-  - id: DATA-001
+  - id: Logging-RequestLogging
     tests:
       - Logging_ValidRequest_Logged
       - Logging_InvalidRequest_Logged
@@ -239,17 +239,17 @@ Test source linking allows requirements to specify which test results should com
 
 ```yaml
 requirements:
-  - id: PLAT-001
+  - id: Platform-Windows
     title: Shall support Windows
     tests:
       - windows@Test_PlatformFeature  # Matches only from files containing "windows"
 
-  - id: PLAT-002
+  - id: Platform-Linux
     title: Shall support Linux
     tests:
       - ubuntu@Test_PlatformFeature   # Matches only from files containing "ubuntu"
 
-  - id: PLAT-003
+  - id: Platform-CrossPlatform
     title: Shall support cross-platform features
     tests:
       - Test_CrossPlatformFeature     # Aggregates from all test result files
@@ -275,21 +275,21 @@ Tags are defined as an optional list in the requirement definition:
 sections:
   - title: System Security
     requirements:
-      - id: SYS-SEC-001
+      - id: Security-CredentialAuthentication
         title: The system shall support credentials authentication.
         tags:
           - security
           - critical
 
-      - id: SYS-SEC-002
+      - id: Security-AuditLogging
         title: The system shall log all authentication attempts.
         tags:
           - security
           - audit
 
   - title: Performance
     requirements:
-      - id: PERF-001
+      - id: Performance-ResponseTime
         title: The system shall respond within 100ms.
         tags:
           - performance
@@ -442,7 +442,7 @@ Given requirements with justifications:
 sections:
   - title: Security
     requirements:
-      - id: SEC-001
+      - id: Security-DataEncryption
         title: The system shall encrypt all data at rest.
         justification: |
           Data encryption at rest protects sensitive information from unauthorized access
@@ -454,7 +454,7 @@ The exported justifications document would look like:
 ```markdown
 # Security
 
-## SEC-001
+## Security-DataEncryption
 
 **The system shall encrypt all data at rest.**
 

docs/design/definition.yaml

@@ -6,6 +6,7 @@ resource-path:
 input-files:
   - docs/design/title.txt
   - docs/design/introduction.md
+  - docs/design/system.md
   - docs/design/program.md
   - docs/design/context.md
   - docs/design/validation.md

docs/design/introduction.md

@@ -28,6 +28,32 @@ The following topics are out of scope:
 - Build pipeline configuration
 - Deployment and packaging
 
+## Software Structure
+
+The following tree shows how the ReqStream software items are organized across the system,
+subsystem, and unit levels:
+
+```text
+ReqStream (System)
+├── Program Orchestration (Subsystem)
+│   ├── Command-Line Interface (Subsystem)
+│   │   └── Context (Unit)
+│   └── Program (Unit)
+├── Requirements (Subsystem)
+│   ├── Requirements File Processing (Subsystem)
+│   │   ├── Requirements (Unit)
+│   │   ├── Section (Unit)
+│   │   └── Requirement (Unit)
+│   ├── Test Integration (Subsystem)
+│   │   └── TraceMatrix (Unit)
+│   └── Linting (Subsystem)
+│       └── Linter (Unit)
+└── Validation (Subsystem)
+    └── Validation (Unit)
+```
+
+Each unit is described in detail in its own chapter within this document.
+
 ## Document Conventions
 
 Throughout this document:

docs/design/system.md

@@ -0,0 +1,92 @@
+# System Integration Design
+
+## Overview
+
+This chapter describes how the ReqStream software units work together as an integrated system.
+Where the unit chapters (Program, Context, Validation, Requirements, TraceMatrix, Linter) each
+describe one component in isolation, this chapter focuses on the end-to-end data flow, the
+coordination points between units, and the integrated scenarios that the units collectively
+enable.
+
+## System Data Flow
+
+The following table shows the direction of data between units during a standard requirements
+processing invocation:
+
+| Source | Data | Destination |
+| ------ | ---- | ----------- |
+| CLI arguments | Parsed options | `Context` |
+| `Context.RequirementsFiles` | Glob-expanded file paths | `Requirements.Read` |
+| `Requirements.Read` | Requirement tree | `Program.ProcessRequirements` |
+| `Context.TestFiles` | Glob-expanded file paths | `TraceMatrix` constructor |
+| Requirement tree | Requirements | `TraceMatrix` constructor |
+| `TraceMatrix` | Coverage data | `Program.EnforceRequirementsCoverage` |
+| `TraceMatrix` / requirement tree | Export input | Report files |
+
+## Integrated Processing Pipeline
+
+The following sequence describes the full pipeline executed during a normal (non-version, non-help,
+non-validate, non-lint) invocation:
+
+1. **Argument parsing** — `Context.Create(args)` parses all CLI flags and expands any glob
+   patterns in `--requirements` and `--tests` arguments.
+2. **Requirements loading** — `Requirements.Read(context.RequirementsFiles)` reads and merges all
+   YAML requirements files into a single requirement tree. Files listed via `includes` are resolved
+   recursively.
+3. **Report generation** — if `--report` is set, the requirements report is exported. If
+   `--justifications` is set, the justifications report is exported.
+4. **Test result loading** — if `--tests` is set, a `TraceMatrix` is constructed. It reads each
+   test result file (TRX or JUnit), applies source-specific matching rules, and maps each test
+   result to the requirements that reference it.
+5. **Trace matrix export** — if `--matrix` is set and a `TraceMatrix` was constructed, the trace
+   matrix report is exported.
+6. **Enforcement** — if `--enforce` is set and a `TraceMatrix` was constructed,
+   `EnforceRequirementsCoverage` compares the satisfied-requirement count against the total count.
+   Any unsatisfied requirement causes an error to be written to `context`, which results in a
+   non-zero exit code.
+
+## Source-Specific Test Matching
+
+When test results are collected from multiple platforms or configurations, each result file
+typically carries a platform identifier in its file name (for example `windows-latest.trx` or
+`ubuntu-latest.trx`). The `TraceMatrix` unit supports source-specific matching through the
+`filepart@testname` syntax in requirement test lists:
+
+```text
+tests:
+  - windows-latest@Test_WindowsOnlyFeature
+  - ubuntu@Test_LinuxFeature
+  - Test_CrossPlatformFeature
+```
+
+A `filepart@testname` entry matches only test result files whose names contain `filepart`. A plain
+`testname` entry aggregates results from all files. This mechanism is used in ReqStream's own
+requirements to enforce that platform-specific requirements are satisfied by evidence from the
+correct platform.
+
+## Self-Validation Flow
+
+When `--validate` is specified, `Program.Run` delegates entirely to `Validation.Run(context)`.
+`Validation` is self-contained: it creates temporary directories, writes fixture files, and invokes
+the same `Program` methods used in normal processing. The self-validation path exercises the
+integrated pipeline internally and produces structured test-result output in TRX or JUnit format
+so that the evidence can be fed back into ReqStream's own requirements enforcement.
+
+## Interactions Between Units
+
+| Calling unit | Called unit | Call site | Purpose |
+| ------------ | ----------- | --------- | ------- |
+| `Program` | `Context` | `Main` | Parses CLI arguments; owns output and exit code |
+| `Program` | `Validation` | `Run` | Runs self-validation suite when `--validate` is set |
+| `Program` | `Linter` | `Run` | Lints requirements files when `--lint` is set |
+| `Program` | `Requirements` | `ProcessRequirements` | Reads and merges YAML requirement files |
+| `Program` | `TraceMatrix` | `ProcessRequirements` | Loads test results and maps them to requirements |
+| `Validation` | `Program` | test methods | Invokes `Program.Run` to exercise the full pipeline |
+
+## References
+
+- [ReqStream Architecture][arch]
+- [ReqStream Repository][repo]
+
+[arch]: ../../ARCHITECTURE.md
+[repo]: https://github.com/demaconsulting/ReqStream