Add optional justification field for requirements with PDF generation

.github/workflows/build.yaml

@@ -303,13 +303,14 @@ jobs:
           echo "Installing ReqStream version ${{ inputs.version }} from build..."
           dotnet tool install --global --add-source packages --version ${{ inputs.version }} DemaConsulting.ReqStream
 
-      - name: Generate Requirements Report and Trace Matrix
+      - name: Generate Requirements Documentation
         run: >
           reqstream
           --requirements requirements.yaml
           --tests "test-results/**/*.trx"
           --report docs/requirements/requirements.md
           --matrix docs/tracematrix/tracematrix.md
+          --justifications docs/justifications/justifications.md
           --enforce
 
       - name: Generate HTML with Pandoc
@@ -352,6 +353,19 @@ jobs:
           docs/tracematrix/tracematrix.html
           "docs/ReqStream Trace Matrix.pdf"
 
+      - name: Generate Justifications HTML with Pandoc
+        run: >
+          dotnet pandoc
+          --defaults docs/justifications/definition.yaml
+          --output docs/justifications/justifications.html
+
+      - name: Generate Justifications PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          --pdf-variant pdf/a-3u
+          docs/justifications/justifications.html
+          "docs/ReqStream Requirements Justifications.pdf"
+
       - name: Generate CodeQL Quality Report with SarifMark
         shell: pwsh
         run: >

ARCHITECTURE.md

@@ -43,6 +43,7 @@ public class Requirement
 {
     public string Id { get; set; }          // Unique identifier (e.g., "SYS-SEC-001")
     public string Title { get; set; }       // Human-readable description
+    public string? Justification { get; set; } // Optional rationale for the requirement
     public List<string> Tests { get; }      // Test identifiers linked to this requirement
     public List<string> Children { get; }   // Child requirement IDs for hierarchical requirements
 }
@@ -52,6 +53,7 @@ public class Requirement
 
 - `Id` must be unique across all requirements files
 - `Title` must not be blank
+- `Justification` is optional and explains why the requirement exists
 - `Tests` can be added inline in YAML or through separate mappings
 - `Children` enables hierarchical requirements where high-level requirements are satisfied by child requirements
 
@@ -90,6 +92,7 @@ public class Requirements : Section
 
     public static Requirements Read(params string[] paths);
     public void Export(string filePath, int depth = 1);
+    public void ExportJustifications(string filePath, int depth = 1);
 }
 ```
 
@@ -101,6 +104,7 @@ public class Requirements : Section
 - Process file includes recursively with loop prevention
 - Apply test mappings to requirements
 - Export requirements to Markdown reports
+- Export justifications to Markdown documents
 
 ### TraceMatrix
 
@@ -165,6 +169,12 @@ public sealed class Context : IDisposable
     public bool Enforce { get; }
     public List<string> RequirementsFiles { get; }
     public List<string> TestFiles { get; }
+    public string? RequirementsReport { get; }
+    public int ReportDepth { get; }
+    public string? Matrix { get; }
+    public int MatrixDepth { get; }
+    public string? JustificationsFile { get; }
+    public int JustificationsDepth { get; }
     public int ExitCode { get; }
 
     public static Context Create(string[] args);
@@ -196,6 +206,9 @@ sections:
     requirements:
       - id: "SYS-SEC-001"
         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.
         tests:
           - "AuthTest_ValidCredentials_Allowed"
         children:
@@ -714,11 +727,29 @@ ReqStream uses different exception types for different error scenarios:
 Reports are generated in order:
 
 1. **Requirements Report** (`--report`): Markdown table of requirements by section
-2. **Trace Matrix Report** (`--matrix`): Three sections:
+2. **Justifications Report** (`--justifications`): Markdown document showing requirement IDs, titles, and
+   justifications organized by section
+3. **Trace Matrix Report** (`--matrix`): Three sections:
    - Summary: Satisfied vs total requirements
    - Requirements: Test statistics per requirement
    - Testing: Test-to-requirement mappings
 
+**Example Justifications Report Structure**:
+
+```markdown
+# Security
+
+## SEC-001: The system shall encrypt all data at rest.
+
+Data encryption at rest protects sensitive information from unauthorized access
+in case of physical storage theft or unauthorized access to storage media.
+
+## SEC-002: The system shall use TLS 1.3 for network communications.
+
+TLS 1.3 provides modern cryptographic security and eliminates known vulnerabilities
+present in earlier TLS versions.
+```
+
 **Example Trace Matrix Structure**:
 
 ```markdown

README.md

@@ -25,6 +25,7 @@ create, validate, and manage requirement documents in a structured and maintaina
 - 🧪 **Test Mapping** - Link requirements to test cases for traceability
 - 📦 **File Includes** - Modularize requirements across multiple YAML files
 - ✅ **Validation** - Built-in validation for requirement structure and references
+- 📋 **Justifications** - Document the rationale behind each requirement
 
 ## Installation
 
@@ -87,19 +88,21 @@ This will display:
 Usage: reqstream [options]
 
 Options:
-  -v, --version              Display version information
-  -?, -h, --help             Display this help message
-  --silent                   Suppress console output
-  --validate                 Run self-validation
-  --results <file>           Write validation results to file (TRX or JUnit format)
-  --log <file>               Write output to log file
-  --requirements <pattern>   Requirements files glob pattern
-  --report <file>            Export requirements to markdown file
-  --report-depth <depth>     Markdown header depth for requirements report (default: 1)
-  --tests <pattern>          Test result files glob pattern (TRX or JUnit)
-  --matrix <file>            Export trace matrix to markdown file
-  --matrix-depth <depth>     Markdown header depth for trace matrix (default: 1)
-  --enforce                  Fail if requirements are not fully tested
+  -v, --version                    Display version information
+  -?, -h, --help                   Display this help message
+  --silent                         Suppress console output
+  --validate                       Run self-validation
+  --results <file>                 Write validation results to file (TRX or JUnit format)
+  --log <file>                     Write output to log file
+  --requirements <pattern>         Requirements files glob pattern
+  --report <file>                  Export requirements to markdown file
+  --report-depth <depth>           Markdown header depth for requirements report (default: 1)
+  --tests <pattern>                Test result files glob pattern (TRX or JUnit)
+  --matrix <file>                  Export trace matrix to markdown file
+  --matrix-depth <depth>           Markdown header depth for trace matrix (default: 1)
+  --justifications <file>          Export requirement justifications to markdown file
+  --justifications-depth <depth>   Markdown header depth for justifications (default: 1)
+  --enforce                        Fail if requirements are not fully tested
 ```
 
 ## YAML Format
@@ -115,28 +118,34 @@ with sections, requirements, test mappings, and file includes.
 
 # Requirement sections 
 sections:
-  - title: "System Security"
+  - title: System Security
     requirements:
-      - id: "SYS-SEC-001"
-        title: "The system shall support credentials authentication."
+      - id: SYS-SEC-001
+        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-001
 
-  - title: "Data Management"
+  - title: Data Management
     sections:
-      - title: "User Authentication"
+      - title: User Authentication
         requirements:
-          - id: "AUTH-001"
-            title: "All requests shall have their credentials authenticated before being processed."
+          - id: AUTH-001
+            title: All requests shall have their credentials authenticated before being processed.
+            justification: |
+              Prevents unauthorized access to system resources and ensures compliance with
+              security standards. Each request must be verified to maintain system integrity.
             tests: # Support test-mapping inline with requirements
-              - "Credentials_Valid_Allowed"
-              - "Credentials_Invalid_Refused"
-              - "Credentials_Missing_Refused"
+              - Credentials_Valid_Allowed
+              - Credentials_Invalid_Refused
+              - Credentials_Missing_Refused
 
-      - title: "Logging"
+      - title: Logging
         requirements:
-          - id: "DATA-001"
-            title: "All requests shall be logged."
+          - id: DATA-001
+            title: All requests shall be logged.
 
 # Include other requirement files - may contain requirements and/or test mappings
 includes:
@@ -145,10 +154,10 @@ includes:
 
 # Test mappings support defining tests separate from requirements
 mappings:
-  - id: "DATA-001"
+  - id: DATA-001
     tests:
-      - "Logging_ValidRequest_Logged"
-      - "Logging_InvalidRequest_Logged"
+      - Logging_ValidRequest_Logged
+      - Logging_InvalidRequest_Logged
 ```
 
 ### Key Features
@@ -157,6 +166,8 @@ mappings:
 - **Section Merging**: Identical sections (where the full hierarchy is identical) are automatically merged,
   allowing included files to add more sections or requirements to existing sections
 - **Child Requirements**: Requirements can reference other requirements as children using the `children` field
+- **Justifications**: Requirements can include an optional `justification` field to document the rationale behind
+  the requirement, explaining why it exists and its purpose
 - **Test Mappings**: Tests can be mapped to requirements either inline (within the requirement definition) or
   separately (using the `mappings` section)
 - **Test Source Linking**: Support for source-specific test matching using the `[filepart@]testname` pattern,
@@ -180,20 +191,20 @@ Test source linking allows requirements to specify which test results should com
 
 ```yaml
 requirements:
-  - id: "PLAT-001"
-    title: "Shall support Windows"
+  - id: PLAT-001
+    title: Shall support Windows
     tests:
-      - "windows-latest@Test_PlatformFeature"  # Matches only from files containing "windows-latest"
+      - windows@Test_PlatformFeature  # Matches only from files containing "windows"
 
-  - id: "PLAT-002"
-    title: "Shall support Linux"
+  - id: PLAT-002
+    title: Shall support Linux
     tests:
-      - "ubuntu-latest@Test_PlatformFeature"   # Matches only from files containing "ubuntu-latest"
+      - ubuntu@Test_PlatformFeature   # Matches only from files containing "ubuntu"
 
-  - id: "PLAT-003"
-    title: "Shall support cross-platform features"
+  - id: PLAT-003
+    title: Shall support cross-platform features
     tests:
-      - "Test_CrossPlatformFeature"             # Aggregates from all test result files
+      - Test_CrossPlatformFeature     # Aggregates from all test result files
 ```
 
 **Key behaviors**:
@@ -254,6 +265,63 @@ And exit with code 1, failing the build.
 - Start without enforcement initially, then enable it once baseline coverage is established
 - Use transitive coverage through child requirements for high-level requirements that don't have direct tests
 
+## Justifications Export
+
+ReqStream can export a markdown document that shows each requirement's ID, title, and justification. This is useful
+for documentation, compliance audits, and communicating the rationale behind requirements to stakeholders.
+
+### Exporting Justifications
+
+Use the `--justifications` flag to export a justifications document:
+
+```bash
+reqstream --requirements "**/*.yaml" --justifications justifications.md
+```
+
+This generates a markdown file organized by sections, with each requirement showing:
+
+- Requirement ID and title as a header
+- The justification text (if provided)
+
+### Example Output
+
+Given requirements with justifications:
+
+```yaml
+sections:
+  - title: Security
+    requirements:
+      - id: SEC-001
+        title: The system shall encrypt all data at rest.
+        justification: |
+          Data encryption at rest protects sensitive information from unauthorized access
+          in case of physical storage theft or unauthorized access to storage media.
+```
+
+The exported justifications document would look like:
+
+```markdown
+# Security
+
+## SEC-001
+
+**The system shall encrypt all data at rest.**
+
+Data encryption at rest protects sensitive information from unauthorized access
+in case of physical storage theft or unauthorized access to storage media.
+```
+
+### Configuring Header Depth
+
+Use the `--justifications-depth` option to control the markdown header depth (default: 1):
+
+```bash
+reqstream --requirements "**/*.yaml" --justifications justifications.md --justifications-depth 2
+```
+
+This adjusts the header levels in the output, useful when embedding the justifications document in larger
+documentation structures.
+
 ## Development
 
 ### Requirements