feat: add --depth as default markdown header depth for all reports

[Copilot]

Pull Request

Description

Adds --depth <depth> as a global default markdown header depth that applies to the self-validation
report, requirements report, trace matrix, and justifications output. Per-report flags
(--report-depth, --matrix-depth, --justifications-depth) override it when specified.

Behavior:

# All reports start at level 2
reqstream --requirements "**/*.yaml" --report out.md --matrix matrix.md --depth 2

# Default depth 2, but trace matrix at level 3
reqstream --requirements "**/*.yaml" --report out.md --matrix matrix.md --depth 2 --matrix-depth 3

Implementation

• Context.cs: Added Depth property; per-report depth locals changed to int? — each falls
  back to Depth when not explicitly set; --depth parsed and validated like other depth args
• Validation.cs: PrintValidationHeader uses new string('#', context.Depth) for the
  self-validation section heading
• Program.cs: Help text updated to document --depth and note that specific depth flags
  override it

Tests

• ContextTests.cs: 4 new tests — --depth propagates to all depths, per-report flag overrides
  default, missing-value error, invalid-value error

Documentation

• README.md: Updated CLI options table and "Configuring Header Depth" section
• docs/user_guide/introduction.md: Updated options table, examples, and FAQ entry
• docs/design/reqstream/cli/context.md: Added Depth property row; updated Create() description
• docs/reqstream/reqstream/cli/context.yaml: Added ReqStream-Command-Depth requirement
• docs/reqstream/reqstream/cli/cli.yaml: Added ReqStream-Command-Depth to subsystem children

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

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 unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.ReqStream --configuration Release --framework net10.0
--no-build -- --validate
• 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 .

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

Default depth is 1 when --depth is not specified — no behavioral change for existing invocations.

[Copilot]

Pull request overview

Adds a new global CLI option --depth <depth> to set the default starting Markdown header depth across all generated outputs (requirements report, trace matrix, justifications, and self-validation), while preserving existing per-report depth flags as overrides.

Changes:

• Introduced Context.Depth and --depth parsing/validation, with per-report depths defaulting to Depth unless explicitly set.
• Updated self-validation header rendering to respect context.Depth.
• Updated unit tests and documentation/help text to cover the new option and override behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/DemaConsulting.ReqStream.Tests/Cli/ContextTests.cs	Adds coverage for --depth defaulting/overrides and validation errors.
src/DemaConsulting.ReqStream/Cli/Context.cs	Implements Depth property and CLI parsing; wires per-report depth fallbacks.
src/DemaConsulting.ReqStream/SelfTest/Validation.cs	Uses context.Depth for the self-validation Markdown header.
src/DemaConsulting.ReqStream/Program.cs	Updates CLI help text to document --depth and override semantics.
README.md	Documents --depth and provides updated examples for header depth configuration.
docs/user_guide/introduction.md	Updates user guide options table, examples, and FAQ to include --depth.
docs/design/reqstream/cli/context.md	Updates design documentation for Context.Depth and override behavior.
docs/reqstream/reqstream/cli/context.yaml	Adds a requirement covering global default depth behavior + associated tests.
docs/reqstream/reqstream/cli/cli.yaml	Registers the new depth requirement in the CLI subsystem requirements list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.