Add optional justification field for requirements with PDF generation

[Copilot]

Pull Request

Description

Adds optional justification field to requirements YAML schema and a new export format that renders justifications in narrative markdown (vs. the table format used for requirements reports). Includes automated PDF generation of the requirements justifications document.

YAML Schema Extension:

• justification field on requirements (optional, string)
• Uses YAML multiline format (|) for readability
• All YAML examples use unquoted strings per best practices

New Export Command:

• --justifications <file> exports narrative document with requirement ID, title, and justification text
• --justifications-depth <depth> controls markdown header levels (default: 1)
• Preserves section hierarchy, but renders as headers + paragraphs instead of tables
• Can be combined with --report and --matrix in a single invocation for efficiency

Justifications Format:

• Header contains only the requirement ID (e.g., ## REQ-001)
• Title is displayed in bold below the header (e.g., **The requirement title**)
• Justification text follows the title
• This format keeps table of contents entries short and readable

PDF Generation:

• Created docs/justifications/ directory with Pandoc configuration
• Introduction document explaining the purpose and scope of justifications
• Build workflow automatically generates "ReqStream Requirements Justifications.pdf"
• PDF is generated from requirements.yaml and uploaded as a build artifact

Workflow Optimization:

• Combined multiple reqstream invocations into single command for efficiency
• Generates report, matrix, and justifications in one pass, reducing redundant file parsing

Example:

requirements:
  - id: AUTH-001
    title: The system shall require user login.
    justification: |
      User authentication is essential for protecting sensitive data and ensuring
      that only authorized individuals can access the system.

# Generate all documentation in one command
reqstream --requirements requirements.yaml \
          --tests "test-results/**/*.trx" \
          --report requirements.md \
          --matrix matrix.md \
          --justifications justifications.md \
          --enforce

Generates:

## AUTH-001

**The system shall require user login.**

User authentication is essential for protecting sensitive data and ensuring
that only authorized individuals can access the system.

Changes:

• Extended Requirement class with Justification property
• Added ExportJustifications() method to Requirements class
• Extended Context with JustificationsFile and JustificationsDepth properties
• Added CLI argument parsing for --justifications and --justifications-depth
• Added justifications to all 36 project requirements
• Removed unnecessary quotes from YAML examples throughout all documentation per best practices
• Simplified test-source-linking examples to use concise names ("windows", "ubuntu")
• Updated user guide (docs/guide/guide.md) with comprehensive justifications documentation
• Added build workflow steps to generate justifications markdown, HTML, and PDF
• Optimized workflow to combine reqstream invocations into single command
• Updated justifications format to use ID-only headers with bold titles for better table of contents

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Feature request for documenting requirement rationale with justification fields and generating justification reports, including automated PDF generation.

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All tests pass: dotnet test --configuration Release
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint '**/*.{yml,yaml}'

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

Test Coverage: Added 5 new tests covering justification parsing and export scenarios (simple, nested, with/without justifications, custom depth). Total: 117 tests passing.

Security: CodeQL analysis found 0 alerts. No security implications from this feature.

YAML Style: All YAML examples in documentation (README.md, ARCHITECTURE.md, docs/guide/guide.md) follow best practices with unquoted strings for simple values and simplified naming conventions, improving readability and consistency across the project.

User Guide Updates: The user guide (docs/guide/guide.md) has been comprehensively updated to document the justification feature, including new sections, command-line options, examples, and best practices.

PDF Generation: The CI/CD pipeline now automatically generates "ReqStream Requirements Justifications.pdf" from the project's requirements.yaml file. The PDF is generated using Pandoc and Weasyprint, following the same pattern as other documentation PDFs (User Guide, Requirements, Trace Matrix, Code Quality). The PDF includes:

• Title page with metadata
• Introduction explaining the purpose and scope of justifications
• All requirements with their IDs, titles, and justification text
• Professional formatting with table of contents and numbered sections

Performance: Optimized the build workflow to combine multiple reqstream invocations into a single command, reducing redundant file parsing and improving build efficiency.

Format Optimization: Updated justifications export format to use ID-only headers (e.g., ## REQ-001) with bold titles on separate lines. This keeps table of contents entries concise while preserving full context in the document body.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Add Optional Requirements Justification</issue_title>
<issue_description>### Problem Statement

Requirements are often more valuable when coupled with a justification explaining why the requirement exists; however the ReqStream yaml format doesn't have a recognized pattern for capturing justifications

Proposed Solution

Add an optional justification field to each requirement. Additionally the tool should grown an option to generate a new type of requirements justification markdown which follows the same section structure as the requirements export, but contains the requirement ID, Title, and Justification text.

Note that examples of justifications should use the yaml multi-line format. In fact examples probably shouldn't use the double-quotes unless its for symbol names such as tests or other requirements.

Alternatives Considered

No response

Usage Examples

Benefits

The presence of justifications in requirements may help developers (both human and agent) understand the context.

Priority

Medium - Would improve my workflow

Willingness to Contribute

Yes, I can submit a pull request

Additional Context

Remember that supporting documentation needs to be updated as well. Additionally the ReqStream requirements themselves should be enhanced with justification comments and the requirements justification document published to PDF.

Checklist

• I have searched existing issues to ensure this is not a duplicate
• I have provided a clear description of the feature
• I have explained why this feature would be useful</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature]: Add Optional Requirements Justification #93

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Malcolmnixon]

@copilot The README.md examples have double-quotes around the requirement titles. Again please only use double-quotes where needed.

[Malcolmnixon]

@copilot Also lets modify the examples so when demonstrating test-source-linking they don't use the full github agent names, but use "windows" and "ubuntu".

[Copilot]

@copilot The README.md examples have double-quotes around the requirement titles. Again please only use double-quotes where needed.

Fixed in ddc0e36. Removed unnecessary double-quotes from all YAML examples in README.md - titles, IDs, and test names now use unquoted strings as per YAML best practices.

[Malcolmnixon]

@copilot And remember to review the users guide for the new functionality and for unnecessary quotes.

[Copilot]

@copilot Also lets modify the examples so when demonstrating test-source-linking they don't use the full github agent names, but use "windows" and "ubuntu".

Fixed in 44061e6. Changed test-source-linking examples from "windows-latest"/"ubuntu-latest" to simpler "windows"/"ubuntu" names.

[Copilot]

@copilot And remember to review the users guide for the new functionality and for unnecessary quotes.

Fixed in deadee9. Updated the user guide (docs/guide/guide.md) with comprehensive justifications documentation including:

• Added justification field to Requirements section with example
• Added new "Justifications Export" section with usage examples
• Updated Command-Line Options table with --justifications and --justifications-depth options
• Updated Key Features to mention justifications
• Updated Table of Contents
• Removed all unnecessary quotes from YAML examples throughout the guide

[Malcolmnixon]

@copilot Hey, you didn't add building a ReqStream Requirements Justification PDF document as I put in my original ticket.

[Copilot]

@copilot Hey, you didn't add building a ReqStream Requirements Justification PDF document as I put in my original ticket.

Fixed in 8513809. Added complete PDF generation infrastructure for requirements justifications:

Created:

• docs/justifications/ directory with Pandoc definition, title, and introduction
• Introduction document explaining the purpose and scope of justifications

Updated build workflow to:

1. Generate justifications markdown from requirements.yaml (--justifications docs/justifications/justifications.md)
2. Convert markdown to HTML using Pandoc
3. Generate "ReqStream Requirements Justifications.pdf" using Weasyprint

The PDF will be automatically generated in the CI/CD pipeline and uploaded as a build artifact along with the other documentation PDFs (User Guide, Requirements, Trace Matrix, Code Quality).

[Malcolmnixon]

@copilot Unfortunately building section headings consisting of both the requirement ID and Title result in names too long for the table of contents. I think the section heading needs to just be the ID and then the section contents needs to list the requirement title followed by the justification.

[Copilot]

@copilot Unfortunately building section headings consisting of both the requirement ID and Title result in names too long for the table of contents. I think the section heading needs to just be the ID...

Fixed in fa199a1. Changed justifications format to use ID-only headers with title in bold:

New format:

## REQ-001

**The requirement title**

Justification text...

This creates much shorter table of contents entries while maintaining full context in the document body. Updated all tests and documentation to match the new format.