Add Requirements Management with ReqStream

[Copilot]

Pull Request

Description

Implements requirements management and traceability using ReqStream tool. Adds 30 product-level requirements focused on publicly observable behavior across CLI, GitHub integration, report generation, validation, and platform support. All requirements linked to tests with 100% coverage enforcement in CI/CD.

Key Changes

• requirements.yaml: 30 requirements organized in 5 sections, focusing on user-facing functionality rather than internal implementation details. Follows Test Source pattern for platform requirements with proper test hierarchy (self-validation > integration > unit)
• Test Infrastructure:
  • Runner.cs: Process execution helper for integration tests
  • IntegrationTests.cs: 10 tests executing BuildMark via dotnet <dll>
  • Validation.cs: 4 self-validation tests using Program.Run with mock connector factory
• Context Enhancement:
  • Added ConnectorFactory property to support mock data injection
  • Added Context.Create(args, connectorFactory) overload for testing
• Documentation Structure:
  • docs/requirements/: Pandoc configuration for requirements document generation
  • docs/tracematrix/: Pandoc configuration for trace matrix generation
• CI/CD Integration:
  • Integration-test job: Runs validation tests across 6 matrix combinations (2 OS × 3 .NET versions)
  • Build-docs job: Enforces requirements coverage with reqstream --enforce, generates Requirements and Trace Matrix PDFs

Requirements Focus

Requirements concentrate on publicly observable behavior ("what" the tool does) rather than internal implementation details ("how" it does it):

1. Command-Line Interface (9 requirements): User-facing CLI capabilities
2. GitHub Integration (3 requirements): Building notes from GitHub repositories, tracking issues/PRs, identifying changes
3. Report Generation (9 requirements): Markdown output, formatting, content
4. Validation and Testing (4 requirements): Self-validation mode, test result formats
5. Platform Support (5 requirements): Windows, Linux, .NET 8/9/10 runtime support

Removed internal implementation sections (Git Integration, Data Models, Repository Connectors) that don't represent product-level requirements.

Test Hierarchy

Requirements linked following priority: self-validation (BuildMark_*) > integration (IntegrationTest_*) > program (Program_*) > unit tests. Unit tests removed where higher-level tests exist.

Platform Requirements

Platform requirements (PLT-001 to PLT-005) use Test Source pattern matching SonarMark:

• Windows: windows@IntegrationTest_* and windows@BuildMark_*
• Linux: ubuntu@IntegrationTest_* and ubuntu@BuildMark_*
• .NET versions: dotnet8.x@BuildMark_*, dotnet9.x@BuildMark_*, dotnet10.x@BuildMark_*

Example validation test using Program.Run:

private static void RunMarkdownReportGeneration(
    Context context,
    TestResults testResults,
    Func<IRepoConnector> mockFactory)
{
    RunValidationTest(
        context, testResults,
        "BuildMark_MarkdownReportGeneration",
        "Markdown Report Generation Test",
        mockFactory,
        "build-report.md",
        (logContent, reportContent) =>
        {
            if (reportContent?.Contains("# Build Report") == true)
                return null;
            return "Report missing expected content";
        });
}

Type of Change

• New feature (non-breaking change which adds functionality)

Pre-Submission Checklist

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

• 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

Pattern follows SonarMark implementation exactly:

• Self-validation tests use Program.Run with mock connector factory (not direct unit testing)
• Short test names for requirements traceability
• Test Source pattern for platform-specific requirements validation
• Proper test hierarchy enforced (self-validation > integration > unit)
• Requirements focus on publicly observable product behavior, not internal implementation
• Build fails if any requirement lacks test coverage (dotnet reqstream --enforce)
• Generated documents (requirements.md, tracematrix.md) are gitignored and rebuilt in CI/CD
• Platform requirements validated in CI with test source prefixes (windows@, ubuntu@, dotnet8.x@, etc.)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Requirements and Trace Matrix</issue_title>
<issue_description>### Problem Statement

The project needs requirements and requirements-testing.

Proposed Solution

The project should manage requirements using the https://github.com/demaconsulting/ReqStream tool. The https://github.com/demaconsulting/SonarMark repo contains an excellent example of how to use ReqStream for a project; which involves:

• requirements.yaml identifying the core requirements of the tool
• Link requirements to tests - preferring self-validation tests, IntegrationTests, ProgramTests, and only falling back to component unit tests as a final resort
• docs/requirements pandoc folder to build the requirements document
• docs/tracematrix pandoc folder to build the trace matrix document
• Building the requirements and trace matric document in the build-docs job

This will also require the creation of two types of tests:

• IntegrationTests.cs - tests which run the tool through dotnet <dllname> to test the DLL is actually executable (probably just for basic --help and --version as this doesn't support mocking)
• ProgramTests.cs - tests which run the tool through the Program.Run to prove high-level functionality. This may require a new Context property to trigger Mock data
• Validation.ccs - self-validation tests which again use the Program.Run method to validate high-level functionality. This again would need to use the new Context property to trigger Mock data.

Please follow the "Test Source" pattern demonstrated in SonarMark for making sure test results come from the correct platform. The comments in the requirements.yaml file explain the reasoning and should be replicated in the new requirements.yaml file.

Alternatives Considered

No response

Usage Examples

Benefits

Requirements enforcement of core tool functionality.

Priority

High - Blocking my use case

Willingness to Contribute

Yes, I can submit a pull request

Additional Context

No response

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]: Requirements and Trace Matrix #46

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.