demaconsulting · Malcolmnixon · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git a/.reviewmark.yaml b/.reviewmark.yaml
@@ -3,15 +3,15 @@
 # This file defines which files require review, where the evidence store is located,
 # and how files are grouped into named review-sets following software unit boundaries.
 
-# Patterns identifying all files that require review.
-# Processed in order; prefix a pattern with '!' to exclude.
 needs-review:
-  - "**/*.cs"                    # All C# source and test files
-  - "docs/reqstream/**/*.yaml"   # Requirements files
-  - "!**/obj/**"                 # Exclude build output
-  - "!**/bin/**"                 # Exclude build output
-  - "!node_modules/**"           # Exclude npm dependencies
-  - "!**/.venv/**"               # Exclude Python virtual environment
+  - "requirements.yaml"
+  - "**/*.cs"
+  - "docs/design/**/*.md"
+  - "docs/reqstream/**/*.yaml"
+  - "!**/obj/**"
+  - "!**/bin/**"
+  - "!node_modules/**"
+  - "!**/.venv/**"
 
 # Evidence source: review data and index.json are located in the root of the 'reviews'
 # branch of this repository, accessed through the GitHub public HTTPS raw content endpoint.
@@ -23,72 +23,115 @@ evidence-source:
 
 # Review sets grouping files by logical unit of review.
 reviews:
-  # Software unit reviews - one per class
+  - id: TestResults-System
+    title: Review of TestResults System
+    paths:
+      - "requirements.yaml"
+      - "docs/reqstream/system.yaml"
+      - "docs/reqstream/platform-requirements.yaml"
+      - "docs/design/introduction.md"
+      - "docs/design/system.md"
+
+  - id: TestResults-Design
+    title: Review of TestResults Design Documentation
+    paths:
+      - "docs/design/**/*.md"
+      - "docs/reqstream/system.yaml"
+      - "docs/reqstream/platform-requirements.yaml"
+
+  - id: TestResults-AllRequirements
+    title: Review of All TestResults Requirements
+    paths:
+      - "requirements.yaml"
+      - "docs/reqstream/**/*.yaml"
+
+  - id: TestResults-IO
+    title: Review of TestResults IO Subsystem
+    paths:
+      - "docs/reqstream/io/io.yaml"
+      - "docs/reqstream/io/serializer.yaml"
+      - "docs/reqstream/io/trx-serializer.yaml"
+      - "docs/reqstream/io/junit-serializer.yaml"
+      - "docs/design/io/io.md"
+      - "docs/design/io/serializer.md"
+      - "docs/design/io/trx-serializer.md"
+      - "docs/design/io/junit-serializer.md"
+      - "src/DemaConsulting.TestResults/IO/Serializer.cs"
+      - "src/DemaConsulting.TestResults/IO/SerializerHelpers.cs"
+      - "src/DemaConsulting.TestResults/IO/TrxSerializer.cs"
+      - "src/DemaConsulting.TestResults/IO/JUnitSerializer.cs"
+      - "test/DemaConsulting.TestResults.Tests/IO/SerializerTests.cs"
+      - "test/DemaConsulting.TestResults.Tests/IO/TrxSerializerTests.cs"
+      - "test/DemaConsulting.TestResults.Tests/IO/TrxExampleTests.cs"
+      - "test/DemaConsulting.TestResults.Tests/IO/JUnitSerializerTests.cs"
+      - "test/DemaConsulting.TestResults.Tests/TestHelpers.cs"
+
   - id: TestResults-TestOutcome
     title: Review of TestResults TestOutcome Unit
     paths:
-      - "docs/reqstream/unit-test-outcome.yaml"
+      - "docs/reqstream/test-outcome.yaml"
       - "docs/design/test-outcome.md"
       - "src/DemaConsulting.TestResults/TestOutcome.cs"
       - "test/DemaConsulting.TestResults.Tests/TestOutcomeTests.cs"
 
   - id: TestResults-TestResult
     title: Review of TestResults TestResult Unit
     paths:
-      - "docs/reqstream/unit-test-result.yaml"
+      - "docs/reqstream/test-result.yaml"
       - "docs/design/test-result.md"
       - "src/DemaConsulting.TestResults/TestResult.cs"
       - "test/DemaConsulting.TestResults.Tests/TestResultTests.cs"
 
   - id: TestResults-TestResults
     title: Review of TestResults TestResults Unit
     paths:
-      - "docs/reqstream/unit-test-results.yaml"
+      - "docs/reqstream/test-results.yaml"
       - "docs/design/test-results.md"
       - "src/DemaConsulting.TestResults/TestResults.cs"
       - "test/DemaConsulting.TestResults.Tests/TestResultsTests.cs"
 
   - id: TestResults-Serializer
     title: Review of TestResults Serializer Unit
     paths:
-      - "docs/reqstream/unit-serializer.yaml"
-      - "docs/design/serializer.md"
+      - "docs/reqstream/io/serializer.yaml"
+      - "docs/design/io/serializer.md"
       - "src/DemaConsulting.TestResults/IO/Serializer.cs"
       - "src/DemaConsulting.TestResults/IO/SerializerHelpers.cs"
       - "test/DemaConsulting.TestResults.Tests/IO/SerializerTests.cs"
 
   - id: TestResults-TrxSerializer
     title: Review of TestResults TrxSerializer Unit
     paths:
-      - "docs/reqstream/unit-trx-serializer.yaml"
-      - "docs/design/trx-serializer.md"
+      - "docs/reqstream/io/trx-serializer.yaml"
+      - "docs/design/io/trx-serializer.md"
       - "src/DemaConsulting.TestResults/IO/TrxSerializer.cs"
       - "test/DemaConsulting.TestResults.Tests/IO/TrxSerializerTests.cs"
       - "test/DemaConsulting.TestResults.Tests/IO/TrxExampleTests.cs"
-      - "test/DemaConsulting.TestResults.Tests/TestHelpers.cs"
 
   - id: TestResults-JUnitSerializer
     title: Review of TestResults JUnitSerializer Unit
     paths:
-      - "docs/reqstream/unit-junit-serializer.yaml"
-      - "docs/design/junit-serializer.md"
+      - "docs/reqstream/io/junit-serializer.yaml"
+      - "docs/design/io/junit-serializer.md"
       - "src/DemaConsulting.TestResults/IO/JUnitSerializer.cs"
       - "test/DemaConsulting.TestResults.Tests/IO/JUnitSerializerTests.cs"
 
-  # Platform and OTS dependency reviews
   - id: Platform-Runtime
-    title: Review of Platform and Runtime Support Requirements
+    title: Review of Platform and Runtime Requirements
     paths:
-      - "docs/reqstream/runtime.yaml"
+      - "docs/reqstream/system.yaml"
       - "docs/reqstream/platform-requirements.yaml"
 
   - id: OTS-Dependencies
-    title: Review of Off-The-Shelf Software Dependencies
+    title: Review of OTS Software Dependencies
     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/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/ots/sonarscanner.yaml"
+      - "docs/reqstream/ots/pandoctool.yaml"
+      - "docs/reqstream/ots/weasyprinttool.yaml"
diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml
@@ -5,12 +5,14 @@ resource-path:
 input-files:
   - docs/design/title.txt
   - docs/design/introduction.md
+  - docs/design/system.md
   - docs/design/test-outcome.md
   - docs/design/test-result.md
   - docs/design/test-results.md
-  - docs/design/serializer.md
-  - docs/design/trx-serializer.md
-  - docs/design/junit-serializer.md
+  - docs/design/io/io.md
+  - docs/design/io/serializer.md
+  - docs/design/io/trx-serializer.md
+  - docs/design/io/junit-serializer.md
 template: template.html
 table-of-contents: true
 number-sections: true
diff --git a/docs/design/introduction.md b/docs/design/introduction.md
@@ -50,5 +50,36 @@ This document describes the intent and structure of that code; any discrepancy b
 this document and the code should be resolved by updating this document to reflect the
 actual implementation, or by raising a defect against the code.
 
+## Software Structure
+
+The TestResults library is organized as follows:
+
+```text
+TestResults Library (System)
+├── IO (Subsystem)
+│   ├── Serializer (Unit)
+│   ├── TrxSerializer (Unit)
+│   └── JUnitSerializer (Unit)
+├── TestOutcome (Unit)
+├── TestResult (Unit)
+└── TestResults (Unit)
+```
+
+## Folder Layout
+
+The source code is organized to mirror the design documentation structure:
+
+```text
+src/DemaConsulting.TestResults/
+├── IO/                          — IO Subsystem
+│   ├── Serializer.cs            — Format-detection facade
+│   ├── SerializerHelpers.cs     — Internal UTF-8 writer helper
+│   ├── TrxSerializer.cs         — TRX format read/write
+│   └── JUnitSerializer.cs       — JUnit XML format read/write
+├── TestOutcome.cs               — Test outcome enumeration
+├── TestResult.cs                — Single test result data
+└── TestResults.cs               — Collection of test results
+```
+
 [user-guide]: https://github.com/demaconsulting/TestResults
 [requirements-doc]: https://github.com/demaconsulting/TestResults
diff --git a/docs/design/io/io.md b/docs/design/io/io.md
@@ -0,0 +1,39 @@
+# IO Subsystem Design
+
+## Overview
+
+The IO subsystem provides serialization and deserialization of test result data
+in multiple formats. It acts as the interface between the in-memory
+[TestResults](../test-results.md) model and external test result files.
+
+## Subsystem Structure
+
+The IO subsystem consists of the following units:
+
+| Unit | File | Description |
+| ---- | ---- | ----------- |
+| [Serializer](serializer.md) | `IO/Serializer.cs` | Format-detection facade |
+| [TrxSerializer](trx-serializer.md) | `IO/TrxSerializer.cs` | TRX format implementation |
+| [JUnitSerializer](junit-serializer.md) | `IO/JUnitSerializer.cs` | JUnit XML format implementation |
+
+## Responsibilities
+
+The IO subsystem is responsible for:
+
+- Detecting the format of test result files automatically
+- Deserializing test result files into the in-memory model
+- Serializing the in-memory model to test result files
+- Converting between different test result formats
+
+## Dependencies
+
+The IO subsystem depends on:
+
+- **Model layer**: [TestResults](../test-results.md), [TestResult](../test-result.md),
+  [TestOutcome](../test-outcome.md)
+- **External**: `System.Xml.Linq` for XML processing
+
+## Related Requirements
+
+Requirements for the IO subsystem are in
+[docs/reqstream/io/](../../reqstream/io/).
diff --git a/docs/design/junit-serializer.md → docs/design/io/junit-serializer.md b/docs/design/junit-serializer.md → docs/design/io/junit-serializer.md
diff --git a/docs/design/serializer.md → docs/design/io/serializer.md b/docs/design/serializer.md → docs/design/io/serializer.md
diff --git a/docs/design/trx-serializer.md → docs/design/io/trx-serializer.md b/docs/design/trx-serializer.md → docs/design/io/trx-serializer.md
diff --git a/docs/design/system.md b/docs/design/system.md
@@ -0,0 +1,65 @@
+# System Design
+
+## Overview
+
+The TestResults library is a .NET library for reading and writing test result
+files in multiple formats. It provides a format-agnostic in-memory model and
+format-specific serialization implementations.
+
+## System Architecture
+
+The TestResults library uses a layered architecture:
+
+```mermaid
+graph TD
+    CallingCode[Calling Code]
+
+    subgraph IO["IO Subsystem (Serialization)"]
+        Serializer[Serializer facade]
+        TrxSerializer[TrxSerializer]
+        JUnitSerializer[JUnitSerializer]
+    end
+
+    subgraph Model["Model Layer"]
+        TestResults[TestResults]
+        TestResult[TestResult]
+        TestOutcome[TestOutcome]
+    end
+
+    CallingCode --> Serializer
+    Serializer --> TrxSerializer
+    Serializer --> JUnitSerializer
+    TrxSerializer --> TestResults
+    JUnitSerializer --> TestResults
+    TestResults --> TestResult
+    TestResult --> TestOutcome
+```
+
+## Software Items
+
+The software items in the TestResults system are described in the
+[introduction](introduction.md#software-structure).
+
+## External Interfaces
+
+The TestResults library exposes the following public API entry points:
+
+- `Serializer.Identify(string)`: Detects format of a test result file
+- `Serializer.Deserialize(string)`: Reads a test result file into the model
+- `TrxSerializer.Serialize(TestResults)`: Writes TRX format
+- `TrxSerializer.Deserialize(string)`: Reads TRX format
+- `JUnitSerializer.Serialize(TestResults)`: Writes JUnit XML format
+- `JUnitSerializer.Deserialize(string)`: Reads JUnit XML format
+
+## Supported Formats
+
+| Format | Description | Standard |
+| ------ | ----------- | -------- |
+| TRX | Visual Studio Test Results | Microsoft proprietary |
+| JUnit XML | JUnit test results | Apache JUnit |
+
+## Related Requirements
+
+System-level requirements are in [docs/reqstream/system.yaml](../reqstream/system.yaml).
+Platform requirements are in
+[docs/reqstream/platform-requirements.yaml](../reqstream/platform-requirements.yaml).
diff --git a/docs/reqstream/io/io.yaml b/docs/reqstream/io/io.yaml
@@ -0,0 +1,10 @@
+---
+# IO Subsystem Requirements
+# This file covers the IO subsystem of the TestResults library.
+# Unit-level requirements are in the individual unit files:
+#   - serializer.yaml
+#   - trx-serializer.yaml
+#   - junit-serializer.yaml
+
+sections:
+  - title: IO Subsystem Requirements
diff --git a/docs/reqstream/unit-junit-serializer.yaml → docs/reqstream/io/junit-serializer.yaml b/docs/reqstream/unit-junit-serializer.yaml → docs/reqstream/io/junit-serializer.yaml
diff --git a/docs/reqstream/unit-serializer.yaml → docs/reqstream/io/serializer.yaml b/docs/reqstream/unit-serializer.yaml → docs/reqstream/io/serializer.yaml
diff --git a/docs/reqstream/unit-trx-serializer.yaml → docs/reqstream/io/trx-serializer.yaml b/docs/reqstream/unit-trx-serializer.yaml → docs/reqstream/io/trx-serializer.yaml
diff --git a/docs/reqstream/ots-buildmark.yaml → docs/reqstream/ots/buildmark.yaml b/docs/reqstream/ots-buildmark.yaml → docs/reqstream/ots/buildmark.yaml
diff --git a/docs/reqstream/ots-mstest.yaml → docs/reqstream/ots/mstest.yaml b/docs/reqstream/ots-mstest.yaml → docs/reqstream/ots/mstest.yaml
diff --git a/docs/reqstream/ots-pandoctool.yaml → docs/reqstream/ots/pandoctool.yaml b/docs/reqstream/ots-pandoctool.yaml → docs/reqstream/ots/pandoctool.yaml
diff --git a/docs/reqstream/ots-reqstream.yaml → docs/reqstream/ots/reqstream.yaml b/docs/reqstream/ots-reqstream.yaml → docs/reqstream/ots/reqstream.yaml
diff --git a/docs/reqstream/ots-reviewmark.yaml → docs/reqstream/ots/reviewmark.yaml b/docs/reqstream/ots-reviewmark.yaml → docs/reqstream/ots/reviewmark.yaml
diff --git a/docs/reqstream/ots-sarifmark.yaml → docs/reqstream/ots/sarifmark.yaml b/docs/reqstream/ots-sarifmark.yaml → docs/reqstream/ots/sarifmark.yaml
diff --git a/docs/reqstream/ots-sonarmark.yaml → docs/reqstream/ots/sonarmark.yaml b/docs/reqstream/ots-sonarmark.yaml → docs/reqstream/ots/sonarmark.yaml
diff --git a/docs/reqstream/ots-sonarscanner.yaml → docs/reqstream/ots/sonarscanner.yaml b/docs/reqstream/ots-sonarscanner.yaml → docs/reqstream/ots/sonarscanner.yaml
diff --git a/docs/reqstream/ots-versionmark.yaml → docs/reqstream/ots/versionmark.yaml b/docs/reqstream/ots-versionmark.yaml → docs/reqstream/ots/versionmark.yaml
diff --git a/docs/reqstream/ots-weasyprinttool.yaml → docs/reqstream/ots/weasyprinttool.yaml b/docs/reqstream/ots-weasyprinttool.yaml → docs/reqstream/ots/weasyprinttool.yaml
diff --git a/docs/reqstream/runtime.yaml → docs/reqstream/system.yaml b/docs/reqstream/runtime.yaml → docs/reqstream/system.yaml
diff --git a/docs/reqstream/unit-test-outcome.yaml → docs/reqstream/test-outcome.yaml b/docs/reqstream/unit-test-outcome.yaml → docs/reqstream/test-outcome.yaml
diff --git a/docs/reqstream/unit-test-result.yaml → docs/reqstream/test-result.yaml b/docs/reqstream/unit-test-result.yaml → docs/reqstream/test-result.yaml
diff --git a/docs/reqstream/unit-test-results.yaml → docs/reqstream/test-results.yaml b/docs/reqstream/unit-test-results.yaml → docs/reqstream/test-results.yaml
diff --git a/requirements.yaml b/requirements.yaml
@@ -1,24 +1,26 @@
 ---
 # TestResults Library Requirements
 #
-# Root requirements file - includes all unit, platform, and OTS requirements
+# Root requirements file - includes all unit, platform, and OTS requirements.
+# Organized by subsystem: model units, IO subsystem, system/platform, and OTS.
 
 includes:
-  - docs/reqstream/unit-test-outcome.yaml
-  - docs/reqstream/unit-test-result.yaml
-  - docs/reqstream/unit-test-results.yaml
-  - docs/reqstream/unit-serializer.yaml
-  - docs/reqstream/unit-trx-serializer.yaml
-  - docs/reqstream/unit-junit-serializer.yaml
-  - docs/reqstream/runtime.yaml
+  - docs/reqstream/test-outcome.yaml
+  - docs/reqstream/test-result.yaml
+  - docs/reqstream/test-results.yaml
+  - docs/reqstream/io/io.yaml
+  - docs/reqstream/io/serializer.yaml
+  - docs/reqstream/io/trx-serializer.yaml
+  - docs/reqstream/io/junit-serializer.yaml
+  - docs/reqstream/system.yaml
   - docs/reqstream/platform-requirements.yaml
-  - 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/ots-sonarscanner.yaml
-  - docs/reqstream/ots-pandoctool.yaml
-  - docs/reqstream/ots-weasyprinttool.yaml
+  - 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/ots/sonarscanner.yaml
+  - docs/reqstream/ots/pandoctool.yaml
+  - docs/reqstream/ots/weasyprinttool.yaml