Pre-release quality sweep: formatting, requirements gaps, architecture docs, guide restructuring, template consistency, workflow reorganization

.config/dotnet-tools.json

@@ -33,7 +33,7 @@
       ]
     },
     "demaconsulting.buildmark": {
-      "version": "0.2.0",
+      "version": "0.3.0",
       "commands": [
         "buildmark"
       ]

.editorconfig

@@ -6,6 +6,7 @@ root = true
 # All files
 [*]
 charset = utf-8
+end_of_line = lf
 indent_style = space
 indent_size = 4
 insert_final_newline = true

.github/pull_request_template.md

@@ -27,7 +27,10 @@ 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`
+- [ ] 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
@@ -42,7 +45,7 @@ Please run the following checks before submitting:
 
 - [ ] **Spell checker passes**: `cspell "**/*.{md,cs}"`
 - [ ] **Markdown linter passes**: `markdownlint "**/*.md"`
-- [ ] **YAML linter passes**: `yamllint '**/*.{yml,yaml}'`
+- [ ] **YAML linter passes**: `yamllint .`
 
 ### Testing
 

.gitignore

@@ -118,14 +118,33 @@ Desktop.ini
 # Node.js
 node_modules/
 package-lock.json
+npm-debug.log
 
 # Generated documentation
-docs/guide/*.html
-docs/requirements/*.html
+docs/**/*.html
+docs/**/*.pdf
+!docs/template/**
 docs/requirements/requirements.md
-docs/tracematrix/*.html
+docs/justifications/justifications.md
 docs/tracematrix/tracematrix.md
-docs/*.pdf
+docs/quality/codeql-quality.md
+docs/quality/sonar-quality.md
+docs/buildnotes.md
+docs/buildnotes/versions.md
 
-# Agent-generated reports (should not be committed)
+# Test results
+TestResults/
+*.trx
+*.xml
+coverage.opencover.xml
+
+# VersionMark captures (generated during CI/CD)
+versionmark-*.json
+
+# Temporary files
+*.tmp
+*.temp
+*.log
+
+# Agent report files
 AGENT_REPORT_*.md

.markdownlint-cli2.jsonc

@@ -4,11 +4,12 @@
     "MD003": { "style": "atx" },
     "MD007": { "indent": 2 },
     "MD013": { "line_length": 120 },
+    "MD025": false,
     "MD033": false,
     "MD041": false
   },
   "ignores": [
-    "node_modules/**",
-    "AGENT_REPORT_*.md"
+    "node_modules",
+    "**/AGENT_REPORT_*.md"
   ]
 }

AGENTS.md

@@ -41,7 +41,7 @@ ReqStream/
 │   └── DemaConsulting.ReqStream.Tests/ # Test project
 ├── .cspell.json                  # Spell checking configuration
 ├── .editorconfig                 # Code style configuration
-├── .markdownlint.json            # Markdown linting rules
+├── .markdownlint-cli2.jsonc      # Markdown linting rules
 ├── .yamllint.yaml                # YAML linting rules
 ├── AGENTS.md                     # This file
 ├── ARCHITECTURE.md               # Architecture documentation
@@ -53,7 +53,7 @@ ReqStream/
 
 - **`.editorconfig`**: Defines code style rules, naming conventions, and formatting standards
 - **`.cspell.json`**: Contains spell-checking configuration and custom dictionary
-- **`.markdownlint.json`**: Markdown linting rules
+- **`.markdownlint-cli2.jsonc`**: Markdown linting rules
 - **`.yamllint.yaml`**: YAML linting rules
 - **`DemaConsulting.ReqStream.slnx`**: Solution file containing all projects (XML format)
 - **`ARCHITECTURE.md`**: Comprehensive guide to the tool's architecture and internal design
@@ -81,6 +81,23 @@ ReqStream/
 - **All tests must pass** before merging changes
 - **No warnings allowed** in test builds
 
+## Test Source Filters
+
+Test links in `requirements.yaml` can include a source filter prefix to restrict which test results count as
+evidence. This is critical for platform and framework requirements - **do not remove these filters**.
+
+- `windows@TestName` - proves the test passed on a Windows platform
+- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform
+- `net8.0@TestName` - proves the test passed under the .NET 8 target framework
+- `net9.0@TestName` - proves the test passed under the .NET 9 target framework
+- `net10.0@TestName` - proves the test passed under the .NET 10 target framework
+- `dotnet8.x@TestName` - proves the self-validation test ran on a machine with .NET 8.x runtime
+- `dotnet9.x@TestName` - proves the self-validation test ran on a machine with .NET 9.x runtime
+- `dotnet10.x@TestName` - proves the self-validation test ran on a machine with .NET 10.x runtime
+
+Without the source filter, a test result from any platform/framework satisfies the requirement. Adding the filter
+ensures the CI evidence comes specifically from the required environment.
+
 ## Code Style and Conventions
 
 ### Naming Conventions
@@ -128,6 +145,7 @@ ReqStream/
 - **Documentation**:
   - README.md uses absolute URLs (included in NuGet package)
   - Other markdown files use link references: `[text][ref]` with `[ref]: url` at end
+  - **CHANGELOG.md**: Not present - changes are captured in the auto-generated build notes
 - **Linting**:
   - **Markdown**: Must pass markdownlint (max line length: 120 chars)
     - Lists must be surrounded by blank lines (MD032)
@@ -137,6 +155,25 @@ ReqStream/
   - **YAML**: Must pass yamllint (2-space indentation, max line length: 120 chars)
   - **All linting must pass locally before committing** - CI will reject changes with linting errors
 
+## Markdown Link Style
+
+- **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent
+  context
+- **README.md**: Use absolute URLs (shipped in NuGet package)
+- **All other markdown files**: Use reference-style links `[text][ref]` with `[ref]: url` at document end
+
+## Agent Report Files
+
+When agents need to write report files to communicate with each other or the user, follow these guidelines:
+
+- **Naming Convention**: Use the pattern `AGENT_REPORT_xxxx.md` (e.g., `AGENT_REPORT_analysis.md`,
+  `AGENT_REPORT_results.md`)
+- **Purpose**: These files are for temporary inter-agent communication and should not be committed
+- **Exclusions**: Files matching `AGENT_REPORT_*.md` are automatically:
+  - Excluded from git (via .gitignore)
+  - Excluded from markdown linting
+  - Excluded from spell checking
+
 ## CI/CD Pipelines
 
 The project uses GitHub Actions workflows in `.github/workflows/`:

ARCHITECTURE.md

@@ -46,6 +46,7 @@ public class Requirement
     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
+    public List<string> Tags { get; }       // Tags for categorization and filtering
 }
 ```
 
@@ -56,6 +57,7 @@ public class Requirement
 - `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
+- `Tags` are optional labels used for categorization and selective filtering of requirements in reports
 
 ### Section
 
@@ -225,6 +227,7 @@ public sealed class Context : IDisposable
     public int MatrixDepth { get; }
     public string? JustificationsFile { get; }
     public int JustificationsDepth { get; }
+    public HashSet<string>? FilterTags { get; }
     public int ExitCode { get; }
 
     public static Context Create(string[] args);
@@ -237,6 +240,7 @@ public sealed class Context : IDisposable
 
 - Parse command-line arguments
 - Expand glob patterns for file matching
+- Parse `--filter` tags for requirements filtering
 - Manage console and log file output
 - Track error state for exit code determination
 
@@ -416,6 +420,42 @@ requirements:
 - Child requirements can themselves have children (recursive traversal)
 - If a child requirement ID doesn't exist, it is ignored during satisfaction calculation
 
+### 7. Tag Filtering
+
+Requirements can be assigned tags for categorization and selective reporting using the `tags` field:
+
+```yaml
+requirements:
+  - id: "SEC-001"
+    title: "Encrypt data at rest"
+    tags:
+      - security
+      - compliance
+    tests:
+      - "TestEncrypt_Passes"
+
+  - id: "PERF-001"
+    title: "Response time under 100ms"
+    tags:
+      - performance
+    tests:
+      - "TestPerformance_Passes"
+```
+
+When the `--filter` option is specified (e.g., `--filter security,compliance`), only requirements with at least one
+matching tag are included in reports, trace matrices, and enforcement calculations. Requirements without any matching
+tags are excluded from all outputs.
+
+**Key Points**:
+
+- Tags are optional; requirements without tags are only included when no filter is active
+- Filter tags are parsed from a comma-separated string and trimmed of whitespace
+- Tag matching checks if the requirement has **any** of the specified filter tags (OR logic)
+- Tag filtering applies to requirements export, justifications export, trace matrix export, satisfaction calculation,
+  and enforcement
+- The `FilterTags` property on `Context` is `null` when no filter is specified, indicating all requirements should be
+  included
+
 ## Trace Matrix Construction and Analysis
 
 The trace matrix maps test results to requirements and determines coverage satisfaction:
@@ -752,9 +792,12 @@ The program follows a priority-based execution flow:
 5. Requirements Processing
    ├─> Read and merge requirements files
    ├─> Export requirements report (if --report specified)
+   ├─> Export justifications report (if --justifications specified)
    ├─> Parse test result files (if --tests specified)
    ├─> Export trace matrix (if --matrix specified)
    └─> Enforce coverage (if --enforce specified)
+
+Note: When --filter is specified, tag filtering is applied to all exports and enforcement.
 ```
 
 ### Error Handling Patterns

CONTRIBUTING.md

@@ -99,7 +99,7 @@ This project follows the coding standards defined in `.editorconfig`. Key conven
 - All new features must include tests
 - Tests should follow the AAA (Arrange, Act, Assert) pattern
 - Test method naming: `TestMethod_Scenario_ExpectedBehavior`
-- All tests must pass before submitting a PR
+- All unit tests must pass before submitting a PR
 - Aim for high code coverage (>80%)
 
 ### Commit Messages
@@ -132,6 +132,29 @@ dotnet build --configuration Release
 dotnet test --configuration Release
 ```
 
+### Running Tests
+
+#### Unit Tests
+
+```bash
+# Run all unit tests
+dotnet test --configuration Release
+
+# Run specific unit test
+dotnet test --filter "FullyQualifiedName~YourTestName"
+
+# Run with coverage
+dotnet test --collect "XPlat Code Coverage"
+```
+
+#### Self-Validation Tests
+
+```bash
+# Run self-validation tests
+dotnet run --project src/DemaConsulting.ReqStream \
+  --configuration Release --framework net10.0 --no-build -- --validate
+```
+
 ### Linting
 
 The CI pipeline runs the following checks: