Apply subsystem folder structure to SarifMark (mirrors TemplateDotNetTool PR #81)

.reviewmark.yaml

@@ -7,6 +7,7 @@
 # Processed in order; prefix a pattern with '!' to exclude.
 needs-review:
   - "**/*.cs"                    # All C# source and test files
+  - "requirements.yaml"          # Root requirements file
   - "docs/reqstream/**/*.yaml"   # Requirements files
   - "docs/design/**/*.md"        # Design documents
   - "!**/obj/**"                 # Exclude build output
@@ -24,117 +25,128 @@ evidence-source:
 reviews:
 
   # ---------------------------------------------------------------------------
-  # Subsystem Reviews
+  # System Review
   # ---------------------------------------------------------------------------
 
-  - id: SarifMark-CommandLine-Subsystem-Review
-    title: Review of SarifMark Command-Line Interface Subsystem
+  - id: SarifMark-System
+    title: Review of SarifMark System
     paths:
-      - "docs/reqstream/command-line.yaml"
-      - "docs/reqstream/program.yaml"
-      - "docs/reqstream/context.yaml"
+      - "docs/reqstream/sarifmark-system.yaml"
+      - "docs/reqstream/platform-requirements.yaml"
+      - "docs/reqstream/ots-software.yaml"
       - "docs/design/introduction.md"
-      - "docs/design/command-line.md"
+      - "docs/design/system.md"
+      - "docs/reqstream/unit-program.yaml"
       - "docs/design/program.md"
-      - "docs/design/context.md"
       - "src/**/Program.cs"
-      - "src/**/Context.cs"
       - "test/**/ProgramTests.cs"
-      - "test/**/ContextTests.cs"
       - "test/**/IntegrationTests.cs"
       - "test/**/Runner.cs"
       - "test/**/AssemblyInfo.cs"
 
-  - id: SarifMark-Sarif-Subsystem-Review
-    title: Review of SarifMark SARIF Reading Subsystem
+  # ---------------------------------------------------------------------------
+  # All Requirements Review
+  # ---------------------------------------------------------------------------
+
+  - id: SarifMark-AllRequirements
+    title: Review of All SarifMark Requirements
     paths:
-      - "docs/reqstream/sarif.yaml"
-      - "docs/reqstream/sarif-result.yaml"
-      - "docs/reqstream/sarif-results.yaml"
-      - "docs/design/sarif.md"
-      - "src/**/SarifResult.cs"
-      - "src/**/SarifResults.cs"
-      - "test/**/SarifResultsTests.cs"
-      - "test/**/IntegrationTests.cs"
+      - "requirements.yaml"
+      - "docs/reqstream/**/*.yaml"
+
+  # ---------------------------------------------------------------------------
+  # Subsystem Reviews
+  # ---------------------------------------------------------------------------
+
+  - id: SarifMark-Cli
+    title: Review of SarifMark Command-Line Interface Subsystem
+    paths:
+      - "docs/reqstream/cli/subsystem-cli.yaml"
+      - "docs/design/cli/cli.md"
+      - "docs/design/cli/context.md"
+      - "src/**/Cli/Context.cs"
+      - "test/**/Cli/ContextTests.cs"
 
-  - id: SarifMark-Report-Subsystem-Review
-    title: Review of SarifMark Report Generation Subsystem
+  - id: SarifMark-Sarif
+    title: Review of SarifMark SARIF Reading Subsystem
     paths:
-      - "docs/reqstream/report.yaml"
-      - "docs/reqstream/sarif-results.yaml"
-      - "docs/design/sarif.md"
-      - "docs/design/sarif-results.md"
-      - "src/**/SarifResults.cs"
-      - "test/**/SarifResultsTests.cs"
+      - "docs/reqstream/sarif/subsystem-sarif.yaml"
+      - "docs/reqstream/sarif/subsystem-report.yaml"
+      - "docs/design/sarif/sarif.md"
+      - "docs/design/sarif/sarif-result.md"
+      - "docs/design/sarif/sarif-results.md"
+      - "src/**/Sarif/SarifResult.cs"
+      - "src/**/Sarif/SarifResults.cs"
+      - "test/**/Sarif/SarifResultsTests.cs"
       - "test/**/IntegrationTests.cs"
 
-  - id: SarifMark-Validation-Subsystem-Review
+  - id: SarifMark-SelfTest
     title: Review of SarifMark Self-Validation Subsystem
     paths:
-      - "docs/reqstream/validation.yaml"
-      - "docs/reqstream/validation-class.yaml"
-      - "docs/design/validation.md"
-      - "src/**/Validation.cs"
-      - "test/**/ValidationTests.cs"
+      - "docs/reqstream/self-test/subsystem-self-test.yaml"
+      - "docs/design/self-test/self-test.md"
+      - "docs/design/self-test/validation.md"
+      - "src/**/SelfTest/Validation.cs"
+      - "test/**/SelfTest/ValidationTests.cs"
       - "test/**/IntegrationTests.cs"
 
-  - id: SarifMark-Platform-Subsystem-Review
-    title: Review of SarifMark Platform and OTS Software
+  - id: SarifMark-Utilities
+    title: Review of SarifMark Utilities Subsystem
     paths:
-      - "docs/reqstream/platform.yaml"
-      - "docs/reqstream/ots-software.yaml"
+      - "docs/reqstream/utilities/subsystem-utilities.yaml"
+      - "docs/design/utilities/utilities.md"
+      - "docs/design/utilities/path-helpers.md"
+      - "src/**/Utilities/PathHelpers.cs"
+      - "test/**/Utilities/PathHelpersTests.cs"
 
   # ---------------------------------------------------------------------------
   # Software Unit Reviews
   # ---------------------------------------------------------------------------
 
-  - id: SarifMark-Program-SoftwareUnit-Review
+  - id: SarifMark-Program
     title: Review of SarifMark Program Software Unit
     paths:
-      - "docs/reqstream/program.yaml"
+      - "docs/reqstream/unit-program.yaml"
       - "docs/design/program.md"
       - "src/**/Program.cs"
       - "test/**/ProgramTests.cs"
-      - "test/**/IntegrationTests.cs"
-      - "test/**/Runner.cs"
-      - "test/**/AssemblyInfo.cs"
 
-  - id: SarifMark-Context-SoftwareUnit-Review
+  - id: SarifMark-Context
     title: Review of SarifMark Context Software Unit
     paths:
-      - "docs/reqstream/context.yaml"
-      - "docs/design/context.md"
-      - "src/**/Context.cs"
-      - "test/**/ContextTests.cs"
+      - "docs/reqstream/cli/unit-context.yaml"
+      - "docs/design/cli/context.md"
+      - "src/**/Cli/Context.cs"
+      - "test/**/Cli/ContextTests.cs"
 
-  - id: SarifMark-SarifResult-SoftwareUnit-Review
+  - id: SarifMark-SarifResult
     title: Review of SarifMark SarifResult Software Unit
     paths:
-      - "docs/reqstream/sarif-result.yaml"
-      - "docs/design/sarif-result.md"
-      - "src/**/SarifResult.cs"
-      - "test/**/SarifResultsTests.cs"
+      - "docs/reqstream/sarif/unit-sarif-result.yaml"
+      - "docs/design/sarif/sarif-result.md"
+      - "src/**/Sarif/SarifResult.cs"
+      - "test/**/Sarif/SarifResultsTests.cs"
 
-  - id: SarifMark-SarifResults-SoftwareUnit-Review
+  - id: SarifMark-SarifResults
     title: Review of SarifMark SarifResults Software Unit
     paths:
-      - "docs/reqstream/sarif-results.yaml"
-      - "docs/design/sarif-results.md"
-      - "src/**/SarifResults.cs"
-      - "test/**/SarifResultsTests.cs"
+      - "docs/reqstream/sarif/unit-sarif-results.yaml"
+      - "docs/design/sarif/sarif-results.md"
+      - "src/**/Sarif/SarifResults.cs"
+      - "test/**/Sarif/SarifResultsTests.cs"
 
-  - id: SarifMark-Validation-SoftwareUnit-Review
+  - id: SarifMark-Validation
     title: Review of SarifMark Validation Software Unit
     paths:
-      - "docs/reqstream/validation-class.yaml"
-      - "docs/design/validation.md"
-      - "src/**/Validation.cs"
-      - "test/**/ValidationTests.cs"
+      - "docs/reqstream/self-test/unit-validation.yaml"
+      - "docs/design/self-test/validation.md"
+      - "src/**/SelfTest/Validation.cs"
+      - "test/**/SelfTest/ValidationTests.cs"
 
-  - id: SarifMark-PathHelpers-SoftwareUnit-Review
+  - id: SarifMark-PathHelpers
     title: Review of SarifMark PathHelpers Software Unit
     paths:
-      - "docs/reqstream/path-helpers.yaml"
-      - "docs/design/path-helpers.md"
-      - "src/**/PathHelpers.cs"
-      - "test/**/PathHelpersTests.cs"
+      - "docs/reqstream/utilities/unit-path-helpers.yaml"
+      - "docs/design/utilities/path-helpers.md"
+      - "src/**/Utilities/PathHelpers.cs"
+      - "test/**/Utilities/PathHelpersTests.cs"

AGENTS.md

@@ -92,6 +92,8 @@ compliance gates on every CI/CD run instead of as a last-mile activity.
 ## Project Structure Template
 
 - `docs/` - Documentation and compliance artifacts
+  - `design/` - Detailed design documents
+    - `introduction.md` - System/Subsystem/Unit breakdown for this repository
   - `reqstream/` - Subsystem requirements YAML files (included by root requirements.yaml)
   - Auto-generated reports (requirements, justifications, trace matrix)
 - `src/` - Source code files

docs/design/cli/cli.md

@@ -0,0 +1,41 @@
+# Cli Subsystem
+
+The `Cli` subsystem provides the command-line interface for SarifMark.
+It is responsible for accepting user input from the command line and routing output to
+the console and an optional log file.
+
+## Overview
+
+The `Cli` subsystem acts as the primary boundary between the user's shell invocation and
+the tool's internal logic. It owns argument parsing, output formatting, and error tracking.
+All other subsystems receive a `Context` object from the `Cli` subsystem to read parsed
+flags and write output.
+
+## Units
+
+The `Cli` subsystem contains the following software unit:
+
+| Unit      | File             | Responsibility                                    |
+|-----------|------------------|---------------------------------------------------|
+| `Context` | `Cli/Context.cs` | Argument parsing, output channels, and exit code. |
+
+## Interfaces
+
+The `Cli` subsystem exposes the following interface to the rest of the tool:
+
+| Interface            | Direction | Description                                                   |
+|----------------------|-----------|---------------------------------------------------------------|
+| `Context.Create`     | Outbound  | Factory method constructing a `Context` from `string[] args`. |
+| `Context.WriteLine`  | Outbound  | Writes a message to console and optional log file.            |
+| `Context.WriteError` | Outbound  | Writes an error to stderr and sets the error exit code.       |
+| `Context.ExitCode`   | Outbound  | Returns 0 for success or 1 when errors have been reported.    |
+
+## Interactions
+
+The `Cli` subsystem has no dependencies on other tool subsystems. It uses only .NET base
+class library types. The `Program` unit at system level creates the `Context` and passes it
+to all subsystems that need to produce output.
+
+## Class Details
+
+- **Context class** — argument parsing and output routing

docs/design/definition.yaml

@@ -1,18 +1,25 @@
 ---
 resource-path:
   - docs/design
+  - docs/design/cli
+  - docs/design/sarif
+  - docs/design/self-test
+  - docs/design/utilities
   - docs/template
 input-files:
   - docs/design/title.txt
   - docs/design/introduction.md
-  - docs/design/command-line.md
-  - docs/design/sarif.md
-  - docs/design/validation.md
+  - docs/design/system.md
   - docs/design/program.md
-  - docs/design/context.md
-  - docs/design/sarif-result.md
-  - docs/design/sarif-results.md
-  - docs/design/path-helpers.md
+  - docs/design/cli/cli.md
+  - docs/design/cli/context.md
+  - docs/design/sarif/sarif.md
+  - docs/design/sarif/sarif-result.md
+  - docs/design/sarif/sarif-results.md
+  - docs/design/self-test/self-test.md
+  - docs/design/self-test/validation.md
+  - docs/design/utilities/utilities.md
+  - docs/design/utilities/path-helpers.md
 template: template.html
 table-of-contents: true
 number-sections: true

docs/design/introduction.md

@@ -42,6 +42,48 @@ This document is intended for:
 Readers are assumed to be familiar with C# and .NET development and general concepts of
 command-line tool design.
 
+## Software Structure
+
+The following tree shows how the SarifMark software items are organized across the
+system, subsystem, and unit levels:
+
+```text
+SarifMark (System)
+├── Program (Unit)
+├── Cli (Subsystem)
+│   └── Context (Unit)
+├── Sarif (Subsystem)
+│   ├── SarifResult (Unit)
+│   └── SarifResults (Unit)
+├── SelfTest (Subsystem)
+│   └── Validation (Unit)
+└── Utilities (Subsystem)
+    └── PathHelpers (Unit)
+```
+
+Each unit is described in detail in its own chapter within this document.
+
+## Folder Layout
+
+The source code folder structure mirrors the top-level subsystem breakdown above, giving
+reviewers an explicit navigation aid from design to code:
+
+```text
+src/DemaConsulting.SarifMark/
+├── Program.cs                  — entry point and execution orchestrator
+├── Cli/
+│   └── Context.cs              — command-line argument parser and I/O owner
+├── Sarif/
+│   ├── SarifResult.cs          — immutable record for a single analysis finding
+│   └── SarifResults.cs         — SARIF file reading and markdown report generation
+├── SelfTest/
+│   └── Validation.cs           — self-validation test runner
+└── Utilities/
+    └── PathHelpers.cs          — safe path combination utilities
+```
+
+The test project mirrors the same layout under `test/DemaConsulting.SarifMark.Tests/`.
+
 ## Relationship to Requirements and Code
 
 Each component described here corresponds to one or more requirements defined in the