From 3035191d8a0e81fd3400fdde0469f6bbc5c8767b Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 5 May 2026 18:23:45 -0400 Subject: [PATCH 1/2] Move category files into correct locations and update references. --- .github/standards/design-documentation.md | 66 ++++++++++++------- .github/standards/reqstream-usage.md | 31 +++++---- .github/standards/reviewmark-usage.md | 48 ++++++++++---- .github/standards/software-items.md | 8 +++ .github/standards/technical-documentation.md | 17 +++++ .../standards/verification-documentation.md | 62 ++++++++++------- .reviewmark.yaml | 14 ++-- AGENTS.md | 6 +- docs/design/definition.yaml | 2 +- docs/design/introduction.md | 2 +- .../{nuget-caching => }/nuget-caching.md | 0 docs/design/nuget-caching/nuget-cache.md | 28 ++++---- docs/design/nuget-caching/path-helpers.md | 28 ++++---- .../{nuget-caching => }/nuget-caching.yaml | 0 docs/verification/definition.yaml | 3 +- docs/verification/introduction.md | 14 ++-- .../{nuget-caching => }/nuget-caching.md | 0 .../verification/nuget-caching/nuget-cache.md | 20 +++--- .../nuget-caching/path-helpers.md | 34 +++++----- docs/verification/ots.md | 9 +++ docs/verification/ots/buildmark.md | 20 +++--- docs/verification/ots/fileassert.md | 16 ++--- docs/verification/ots/pandoc.md | 24 +++---- docs/verification/ots/reqstream.md | 22 +++---- docs/verification/ots/reviewmark.md | 24 +++---- docs/verification/ots/sarifmark.md | 16 ++--- docs/verification/ots/sonarmark.md | 18 ++--- docs/verification/ots/versionmark.md | 18 ++--- docs/verification/ots/weasyprint.md | 24 +++---- docs/verification/ots/xunit.md | 16 ++--- requirements.yaml | 2 +- 31 files changed, 347 insertions(+), 245 deletions(-) rename docs/design/{nuget-caching => }/nuget-caching.md (100%) rename docs/reqstream/{nuget-caching => }/nuget-caching.yaml (100%) rename docs/verification/{nuget-caching => }/nuget-caching.md (100%) create mode 100644 docs/verification/ots.md diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index 3b448f3..768bf3f 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -35,16 +35,21 @@ design to implementation: ```text docs/design/ -├── introduction.md # Design overview with software structure -└── {system-name}/ # System-level design folder (one per system) - ├── {system-name}.md # System-level design documentation - ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively - │ ├── {subsystem-name}.md # Subsystem overview and design - │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) - │ └── {unit-name}.md # Unit-level design documents - └── {unit-name}.md # Top-level unit design documents (if not in subsystem) +├── introduction.md # Document overview - heading depth # +├── {system-name}.md # System-level design - heading depth # +└── {system-name}/ # System folder (one per system) + ├── {subsystem-name}.md # Subsystem overview - heading depth ## + ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively + │ ├── {child-subsystem}.md # Child subsystem overview - heading depth ### + │ ├── {child-subsystem}/ # Child subsystem folder (same structure as parent) + │ └── {unit-name}.md # Unit design - heading depth ### + └── {unit-name}.md # System-level unit design - heading depth ## ``` +Each scope's overview file lives in its **parent** folder, not inside the scope's own +subfolder - this aligns heading depth with folder depth so the compiled PDF has a +meaningful multi-level outline (see Heading Depth Rule in `technical-documentation.md`). + ## introduction.md (MANDATORY) The `introduction.md` file serves as the design entry point and MUST include @@ -124,23 +129,30 @@ artifact to all related files: Example format: ```text -Each software item in the structure above has corresponding artifacts in -parallel directory trees: - -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source code: `src/{System}/.../{Item}.{ext}` (cased per language - see `software-items.md`) -- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language - see `software-items.md`) -- Review-sets: defined in `.reviewmark.yaml` +Each in-house software item has corresponding artifacts in parallel directory trees: + +- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml` +- Design docs: `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md` +- Verification: `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md` +- Source code: `src/{SystemName}/.../{Item}.{ext}` (cased per language - see `software-items.md`) +- Tests: `test/{SystemName}.Tests/.../{Item}Tests.{ext}` (cased per language) + +OTS items have no design documentation; their artifacts sit parallel to system folders: + +- Requirements: `docs/reqstream/ots/{ots-name}.yaml` +- Verification: `docs/verification/ots/{ots-name}.md` +- Tests (optional): `test/{OtsSoftwareTests}/...` (cased per language - see `software-items.md`) + +Review-sets: defined in `.reviewmark.yaml` ``` ## System Design Documentation (MANDATORY) For each system identified in the repository: -- Create a kebab-case folder matching the system name -- Include `{system-name}.md` with system-level design documentation such as: +- Create `{system-name}.md` directly under `docs/design/` (heading depth `#`) +- Create a kebab-case folder `{system-name}/` to hold its subsystems and units +- `{system-name}.md` must cover: - System architecture and major components - External interfaces and dependencies - Data flow and control flow @@ -151,16 +163,20 @@ For each system identified in the repository: For each subsystem identified in the software structure: -- Create a kebab-case folder matching the subsystem name (enables automated tooling) -- Include `{subsystem-name}.md` with subsystem overview and design -- Include unit design documents for ALL units within the subsystem +- Place `{subsystem-name}.md` inside the **parent** folder (the system folder, or parent + subsystem folder) - not inside its own subfolder +- Create a kebab-case folder `{subsystem-name}/` to hold its child units and subsystems +- `{subsystem-name}.md` must cover subsystem overview and design For every unit identified in the software structure: +- Place `{unit-name}.md` inside its parent scope's folder (system or subsystem folder) - Document data models, algorithms, and key methods - Describe interactions with other units - Include sufficient detail for formal code review -- Place in appropriate subsystem folder or at design root level + +Follow the Heading Depth Rule from `technical-documentation.md` - a file's top-level +heading depth equals its folder depth under `docs/design/`. # Software Items Integration (CRITICAL) @@ -191,9 +207,11 @@ Before submitting design documentation, verify: - [ ] `introduction.md` includes both Software Structure and Folder Layout sections - [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md` - [ ] Folder layout mirrors software structure organization +- [ ] Files organized under `docs/design/` following the folder structure pattern above +- [ ] Each file's top-level heading depth matches its folder depth per the Heading Depth Rule - [ ] Design documents provide sufficient detail for code review - [ ] System documentation provides comprehensive system-level design -- [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure +- [ ] All documentation folders use kebab-case names mirroring source code structure - [ ] All documents follow technical documentation formatting standards - [ ] Content is current with implementation and requirements - [ ] Documents are integrated into ReviewMark review-sets for formal review diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index 58b08b4..303bb43 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -18,20 +18,25 @@ because ReqStream discovers files via the includes chain in `requirements.yaml` and organizes report output by this hierarchy: ```text -requirements.yaml # Root file (includes only) +requirements.yaml # Root file (includes only) docs/reqstream/ -├── {system-name}/ # System-level requirements folder (one per system) -│ ├── {system-name}.yaml # System-level requirements +├── {system-name}.yaml # System-level requirements +├── {system-name}/ # System folder (one per system) │ ├── platform-requirements.yaml # Platform support requirements -│ ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively -│ │ ├── {subsystem-name}.yaml # Requirements for this subsystem -│ │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) -│ │ └── {unit-name}.yaml # Requirements for units within this subsystem -│ └── {unit-name}.yaml # Requirements for top-level units (outside subsystems) -└── ots/ # OTS items appear as a distinct section in reports - └── {ots-name}.yaml # Requirements for OTS components +│ ├── {subsystem-name}.yaml # Subsystem requirements +│ ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively +│ │ ├── {child-subsystem}.yaml # Child subsystem requirements +│ │ ├── {child-subsystem}/ # Child subsystem folder +│ │ └── {unit-name}.yaml # Unit requirements +│ └── {unit-name}.yaml # System-level unit requirements +└── ots/ # OTS items appear as a distinct section in reports + └── {ots-name}.yaml # Requirements for OTS components ``` +In-house items have matching relative paths across `docs/reqstream/`, `docs/design/`, and +`docs/verification/`. OTS items appear only in `docs/reqstream/ots/` and +`docs/verification/ots/` - they have no design documentation. + # Requirements File Format ```yaml @@ -62,7 +67,7 @@ sections: sections: - title: System.Text.Json requirements: - - id: TemplateTool-SystemTextJson-ReadJson + - id: SystemTextJson-Core-ReadJson title: System.Text.Json shall be able to read JSON files. tests: - JsonReaderTests.TestReadValidJson @@ -124,8 +129,8 @@ Before submitting requirements, verify: - [ ] Every requirement links to at least one passing test - [ ] Platform-specific requirements use source filters (`platform@TestName`) - [ ] Comprehensive justification explains business/regulatory need -- [ ] Files organized under `docs/reqstream/` following folder structure patterns -- [ ] Subsystem folders use kebab-case naming matching source code +- [ ] Files organized under `docs/reqstream/` following the folder structure pattern above +- [ ] All documentation folders use kebab-case names matching source code structure - [ ] OTS requirements placed in `ots/` subfolder - [ ] Valid YAML syntax passes yamllint validation - [ ] Test result formats compatible (TRX, JUnit XML) diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index 2f778dc..2d95832 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -61,6 +61,17 @@ needs-review: # Source of review evidence evidence-source: type: none + +# Review-sets (each focuses on a single compliance question) +reviews: + - id: Purpose + title: Review of user-facing capabilities and system promises + paths: + - "README.md" + - "docs/user_guide/**/*.md" + - "docs/reqstream/{system-name}.yaml" + - "docs/design/introduction.md" + - "docs/design/{system-name}.md" ``` # Review-Set Design Principles @@ -95,9 +106,9 @@ Reviews user-facing capabilities and system promises: - **File Path Patterns**: - README: `README.md` - User guide: `docs/user_guide/**/*.md` - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}/{system-name}.md` + - System design: `docs/design/{system-name}.md` ## `{System}-Architecture` Review (one per system) @@ -108,11 +119,11 @@ Reviews system architecture and operational validation: - **Scope**: Excludes subsystem and unit files, relying on system-level design to describe what subsystems and units it uses - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}/{system-name}.md` + - System design: `docs/design/{system-name}.md` - Verification introduction: `docs/verification/introduction.md` - - System verification design: `docs/verification/{system-name}/{system-name}.md` + - System verification design: `docs/verification/{system-name}.md` - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` ## `{System}-Design` Review (one per system) @@ -123,9 +134,10 @@ Reviews architectural and design consistency: - **Title**: "Review that {System} Design is Consistent and Complete" - **Scope**: Only brings in top-level requirements and relies on brevity of design documentation - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Platform requirements: `docs/reqstream/{system-name}/platform-requirements.yaml` - Design introduction: `docs/design/introduction.md` + - System design: `docs/design/{system-name}.md` - System design files: `docs/design/{system-name}/**/*.md` ## `{System}-AllRequirements` Review (one per system) @@ -137,8 +149,8 @@ Reviews requirements quality and traceability: - **Scope**: Only brings in requirements files to keep review manageable - **File Path Patterns**: - Root requirements: `requirements.yaml` - - System requirements: `docs/reqstream/{system-name}/**/*.yaml` - - OTS requirements: `docs/reqstream/ots/**/*.yaml` (if applicable) + - System requirements: `docs/reqstream/{system-name}.yaml` + - Subsystem/unit requirements: `docs/reqstream/{system-name}/**/*.yaml` ## `{System}-{Subsystem[-Child...]}` Review (one per subsystem at any depth) @@ -149,9 +161,9 @@ Reviews subsystem architecture and interfaces: - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe what units it uses - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}/{subsystem-name}.yaml` - - Design: `docs/design/{system-name}/.../{subsystem-name}/{subsystem-name}.md` - - Verification design: `docs/verification/{system-name}/.../{subsystem-name}/{subsystem-name}.md` + - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}.yaml` + - Design: `docs/design/{system-name}/.../{subsystem-name}.md` + - Verification design: `docs/verification/{system-name}/.../{subsystem-name}.md` - Tests: `test/{SystemName}.Tests/.../{SubsystemName}/{SubsystemName}Tests.{ext}` ## `{System}-{Subsystem[-Child...]}-{Unit}` Review (one per unit) @@ -168,6 +180,19 @@ Reviews individual software unit implementation: - Source: `src/{SystemName}/.../{UnitName}.{ext}` - Tests: `test/{SystemName}.Tests/.../{UnitName}Tests.{ext}` +## `OTS-{OtsName}` Review (one per OTS item) + +Reviews OTS item requirements and verification evidence: + +- **Purpose**: Proves that the OTS item provides the required functionality +- **Title**: "Review that {OtsName} Provides Required Functionality" +- **Scope**: OTS items have no in-house design or source; review covers requirements and + verification evidence only +- **File Path Patterns**: + - OTS requirements: `docs/reqstream/ots/{ots-name}.yaml` + - OTS verification: `docs/verification/ots/{ots-name}.md` + - Tests (if applicable): `test/{OtsSoftwareTests}/...` (cased per language) + **Note**: File path patterns use `{ext}` as a placeholder for language-specific extensions (`.cs`, `.cpp`/`.hpp`, `.py`, etc.). Adapt to your repository's languages. @@ -184,6 +209,7 @@ Before submitting ReviewMark configuration, verify: - [ ] Architecture review-sets include system verification design alongside system design - [ ] Subsystem review-sets include subsystem verification design - [ ] Unit review-sets include unit verification design +- [ ] OTS review-sets include OTS requirements and verification evidence - [ ] Each review-set focuses on a single compliance question (single focus principle) - [ ] File patterns use correct glob syntax and match intended files - [ ] Review-set file counts remain manageable (context management principle) diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 4e5c90e..6be029f 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -81,6 +81,14 @@ Choose the appropriate category based on scope and testability: consumes it - Tested through integration tests proving required functionality works - Examples: System.Text.Json, Entity Framework, third-party APIs +- **Artifact locations** (OTS items have no design documentation): + - Requirements: `docs/reqstream/ots/{ots-name}.yaml` + - Verification: `docs/verification/ots/{ots-name}.md` + - These folders sit parallel to system folders (not inside any system folder) +- System design documentation records which OTS items each system depends on +- **OTS test project**: If no other verification evidence is available (e.g., vendor test results, + published compliance reports), a dedicated test project (`OtsSoftwareTests` / `ots_software_tests`, + cased per language) holds OTS integration tests - one test file per OTS item requiring tests. # Software Item Artifact Model diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 7ff5b5a..2ac29f4 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -84,6 +84,23 @@ elsewhere causes duplicate sections in the compiled PDF. List documents in logical reading order in Pandoc configuration because readers need coherent information flow from general to specific topics. +## Heading Depth Rule (MANDATORY) + +A file's top-level heading depth must equal its folder depth under the document +collection root - this ensures Pandoc can concatenate all files in `definition.yaml` +order and produce a coherent outline with no heading-shift configuration: + +| Folder depth | Top heading | +| --- | --- | +| 0 - collection root | `#` | +| 1 - one subfolder deep | `##` | +| 2 - two subfolders deep | `###` | +| N - N subfolders deep | `#` × (N+1) | + +Internal sections use the next heading level down (e.g. a `##` file uses `###` +for *Overview*, *Interfaces*, etc.). Deeply nested files have fewer heading levels +available - keep internal structure flat to avoid excessive nesting. + # Writing Guidelines Write technical documentation for clarity and compliance verification: diff --git a/.github/standards/verification-documentation.md b/.github/standards/verification-documentation.md index f6f407f..8eea3b7 100644 --- a/.github/standards/verification-documentation.md +++ b/.github/standards/verification-documentation.md @@ -23,18 +23,25 @@ Organize under `docs/verification/` mirroring the software item hierarchy: ```text docs/verification/ -├── introduction.md # Verification overview -├── {system-name}/ # System-level verification folder (one per system) -│ ├── {system-name}.md # System-level verification design -│ ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively -│ │ ├── {subsystem-name}.md # Subsystem verification design -│ │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) -│ │ └── {unit-name}.md # Unit-level verification design documents -│ └── {unit-name}.md # Top-level unit verification documents (if not in subsystem) -└── ots/ # OTS items (one verification file per OTS item) - └── {ots-name}.md # Verification evidence for each OTS item +├── introduction.md # Document overview - heading depth # +├── {system-name}.md # System-level verification - heading depth # +├── {system-name}/ # System folder (one per system) +│ ├── {subsystem-name}.md # Subsystem verification - heading depth ## +│ ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively +│ │ ├── {child-subsystem}.md # Child subsystem verification - heading depth ### +│ │ ├── {child-subsystem}/ # Child subsystem folder (same structure as parent) +│ │ └── {unit-name}.md # Unit verification - heading depth ### +│ └── {unit-name}.md # System-level unit verification - heading depth ## +├── ots.md # OTS section overview - heading depth # (MANDATORY if OTS items exist) +└── ots/ # OTS items - parallel to system folders (not inside them) + └── {ots-name}.md # OTS item verification evidence - heading depth ## ``` +Each scope's overview file lives in its **parent** folder, not inside the scope's own +subfolder - this keeps artifact locations consistent with design and requirements trees +so any item's files are deterministically locatable, and aligns heading depth with folder +depth for correct PDF structure (see Heading Depth Rule in `technical-documentation.md`). + ## introduction.md (MANDATORY) Follow the standard `introduction.md` format from `technical-documentation.md`. Scope @@ -45,16 +52,16 @@ artifact to all related files: ```text In-house items have parallel artifacts in: -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source: `src/{System}/.../{Item}.{ext}` (cased per language) -- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language) +- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml` +- Design: `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md` +- Verification: `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md` +- Source: `src/{SystemName}/.../{Item}.{ext}` (cased per language) +- Tests: `test/{SystemName}.Tests/.../{Item}Tests.{ext}` (cased per language) -OTS items have parallel artifacts in: -- Requirements: `docs/reqstream/ots/{ots-name}.yaml` (kebab-case) -- Verification: `docs/verification/ots/{ots-name}.md` (kebab-case) -- Tests: `test/{OtsName}.Tests/...` (cased per language, if required) +OTS items (no design documentation) have artifacts parallel to system folders: +- Requirements: `docs/reqstream/ots/{ots-name}.yaml` +- Verification: `docs/verification/ots/{ots-name}.md` +- Tests (if required): `test/{OtsSoftwareTests}/...` (cased per language - see `software-items.md`) Review-sets: defined in `.reviewmark.yaml` ``` @@ -64,7 +71,8 @@ a `## References` section in `introduction.md` only - do not add one to any othe ## System Verification Design (MANDATORY) -For each system, create a kebab-case folder and `{system-name}.md` covering: +For each system, create `{system-name}.md` at `docs/verification/` root and a +`{system-name}/` folder for subsystems. Cover: - System verification strategy and overall test approach - Test environments and configuration required @@ -75,7 +83,8 @@ For each system, create a kebab-case folder and `{system-name}.md` covering: ## Subsystem Verification Design (MANDATORY) -For each subsystem, create a kebab-case folder and `{subsystem-name}.md` covering: +For each subsystem, place `{subsystem-name}.md` in the parent (system or subsystem) +folder and create a `{subsystem-name}/` folder for its units. Cover: - Subsystem verification strategy and integration test approach - Dependencies that must be mocked or stubbed at the subsystem boundary @@ -84,7 +93,7 @@ For each subsystem, create a kebab-case folder and `{subsystem-name}.md` coverin ## Unit Verification Design (MANDATORY) -For each unit, create `{unit-name}.md` covering: +Place `{unit-name}.md` in the parent (system or subsystem) folder. Cover: - Verification approach for each unit requirement - Named test scenarios including boundary conditions, error paths, and normal-operation cases @@ -93,6 +102,10 @@ For each unit, create `{unit-name}.md` covering: ## OTS Verification Evidence (when OTS items are used) +Create `docs/verification/ots.md` at the collection root with a `#` top-level heading. This +file introduces the OTS verification approach and ensures OTS items compile as a top-level +section in the PDF rather than as subsystems of the last in-house system. + For each OTS item, create `docs/verification/ots/{ots-name}.md` covering: - The OTS item's required functionality (reference `docs/reqstream/ots/{ots-name}.yaml`) @@ -121,8 +134,11 @@ Before submitting verification documentation, verify: - [ ] System verification documents cover end-to-end and integration scenarios - [ ] Subsystem verification documents identify mocked boundaries and integration scenarios - [ ] Unit verification documents identify individual scenarios including boundary and error paths -- [ ] Subsystem documentation folders use kebab-case names mirroring the source subsystem structure +- [ ] Files organized under `docs/verification/` following the folder structure pattern above +- [ ] Each file's top-level heading depth matches its folder depth per the Heading Depth Rule +- [ ] All documentation folders use kebab-case names mirroring source code structure - [ ] All documents follow technical documentation formatting standards - [ ] Content is current with requirements and test implementation - [ ] Every OTS item has `docs/verification/ots/{ots-name}.md` with requirement coverage +- [ ] `docs/verification/ots.md` exists with a `#` heading when OTS items are present - [ ] Documents are integrated into ReviewMark review-sets for formal review diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 9558402..aa577c8 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -35,26 +35,27 @@ reviews: paths: - "README.md" - "docs/user_guide/**/*.md" - - "docs/reqstream/nuget-caching/nuget-caching.yaml" + - "docs/reqstream/nuget-caching.yaml" - "docs/design/introduction.md" - - "docs/design/nuget-caching/nuget-caching.md" + - "docs/design/nuget-caching.md" # NuGetCaching - Specials - id: NuGetCaching-Architecture title: Review that NuGetCaching Architecture Satisfies Requirements paths: - - "docs/reqstream/nuget-caching/nuget-caching.yaml" + - "docs/reqstream/nuget-caching.yaml" - "docs/design/introduction.md" - - "docs/design/nuget-caching/nuget-caching.md" - - "docs/verification/nuget-caching/nuget-caching.md" + - "docs/design/nuget-caching.md" + - "docs/verification/nuget-caching.md" - "test/DemaConsulting.NuGet.Caching.Tests/NuGetCachingTests.cs" - id: NuGetCaching-Design title: Review that NuGetCaching Design is Consistent and Complete paths: - - "docs/reqstream/nuget-caching/nuget-caching.yaml" + - "docs/reqstream/nuget-caching.yaml" - "docs/reqstream/nuget-caching/platform-requirements.yaml" - "docs/design/introduction.md" + - "docs/design/nuget-caching.md" - "docs/design/nuget-caching/**/*.md" - "docs/verification/introduction.md" @@ -62,6 +63,7 @@ reviews: title: Review that All NuGetCaching Requirements are Complete paths: - "requirements.yaml" + - "docs/reqstream/nuget-caching.yaml" - "docs/reqstream/nuget-caching/**/*.yaml" - "docs/reqstream/ots/**/*.yaml" diff --git a/AGENTS.md b/AGENTS.md index 2d88e59..f69644d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ Result semantics for orchestrator decision-making: # Formatting (After Making Changes) After making changes, run the auto-fix pass. This applies all available fixers -silently and **always exits 0** — agents do not need to respond to its output. +silently and **always exits 0** - agents do not need to respond to its output. ```pwsh pwsh ./fix.ps1 @@ -108,7 +108,7 @@ pwsh ./fix.ps1 This automatically handles: `dotnet format`, markdown formatting, and YAML formatting. Full lint compliance is a **pre-PR responsibility**, not an agent -responsibility — invoke the lint-fix agent once before submitting a pull request. +responsibility - invoke the lint-fix agent once before submitting a pull request. ## CI Quality Tools @@ -118,7 +118,7 @@ reqstream, versionmark, and reviewmark. # Scope Discipline (ALL Agents Must Follow) - **No generated file access**: Files inside any `generated/` folder are build - outputs — do not read, lint, or modify them + outputs - do not read, lint, or modify them - **Minimum necessary changes**: Only modify files directly required by the task - **No speculative refactoring**: Do not refactor code adjacent to the change unless the task explicitly requests it diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index 60066a7..bfbc526 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -5,7 +5,7 @@ resource-path: input-files: - docs/design/title.txt - docs/design/introduction.md - - docs/design/nuget-caching/nuget-caching.md + - docs/design/nuget-caching.md - docs/design/nuget-caching/nuget-cache.md - docs/design/nuget-caching/path-helpers.md template: template.html diff --git a/docs/design/introduction.md b/docs/design/introduction.md index afce48c..e13857b 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -48,8 +48,8 @@ Design documentation mirrors the software structure: ```text docs/design/ ├── introduction.md — Design overview and software structure +├── nuget-caching.md — System-level design └── nuget-caching/ - ├── nuget-caching.md — System-level design ├── nuget-cache.md — NuGetCache unit design └── path-helpers.md — PathHelpers unit design ``` diff --git a/docs/design/nuget-caching/nuget-caching.md b/docs/design/nuget-caching.md similarity index 100% rename from docs/design/nuget-caching/nuget-caching.md rename to docs/design/nuget-caching.md diff --git a/docs/design/nuget-caching/nuget-cache.md b/docs/design/nuget-caching/nuget-cache.md index 7a7ca6c..764c0e1 100644 --- a/docs/design/nuget-caching/nuget-cache.md +++ b/docs/design/nuget-caching/nuget-cache.md @@ -1,6 +1,6 @@ -# NuGetCache Design +## NuGetCache Design -## Overview +### Overview The `NuGetCache` class is a public static class providing NuGet package caching functionality for the DemaConsulting NuGet Caching library. It is a software unit @@ -13,9 +13,9 @@ path) from the default machine settings, mirroring the behavior of the `dotnet` and Visual Studio package restore. It communicates with configured NuGet sources using the NuGet client SDK to download packages when they are not already present locally. -## Design Decisions +### Design Decisions -### Static Class +#### Static Class `NuGetCache` is designed as a static class because it provides a service — ensuring a package is cached — that does not require instance state. All configuration is @@ -23,14 +23,14 @@ read from the machine-level NuGet settings on each call, making the class natura stateless. A static class avoids unnecessary object instantiation and provides a simple, flat API surface for callers. -### Async Approach +#### Async Approach The primary method `EnsureCachedAsync` is asynchronous because NuGet source communication involves network I/O. Using `async`/`await` throughout allows the calling thread to be returned to the thread pool during network waits, keeping the library cooperative in concurrent or UI-driven environments. -### NuGet Settings Integration +#### NuGet Settings Integration Rather than accepting source URIs directly, `NuGetCache` reads from the default NuGet settings on the local machine via `Settings.LoadDefaultSettings(null)`. This @@ -38,7 +38,7 @@ ensures the library respects the same `nuget.config` hierarchy (machine-wide, us and project-level) as the `dotnet` CLI and Visual Studio, including authenticated feeds, proxy settings, and package source mapping. -### Early-Exit on Cache Hit +#### Early-Exit on Cache Hit The method checks for the presence of the `.nupkg.metadata` sentinel file before attempting any network communication. NuGet writes this file as the final step of @@ -47,14 +47,14 @@ fully installed. Checking for this file rather than the directory avoids a race condition where a partially-extracted package directory is mistaken for a complete installation. -### Package Source Mapping Support +#### Package Source Mapping Support When `PackageSourceMapping` is enabled in the NuGet configuration, `NuGetCache` filters the set of queried sources to only those explicitly mapped to the requested package ID. This mirrors the security and governance behavior of the NuGet toolchain, ensuring packages are only fetched from their authorized feeds. -### Resilient Source Enumeration +#### Resilient Source Enumeration Sources are queried sequentially. If a source is unreachable (`HttpRequestException`) or does not support the required NuGet protocol (`NuGetProtocolException`), the error @@ -69,7 +69,7 @@ which sources were tried — for troubleshooting feed configuration or intermitt network issues — can wrap `EnsureCachedAsync` and correlate the `InvalidOperationException` message against their `nuget.config` source list. -### Separation of Private Helpers +#### Separation of Private Helpers Two private methods encapsulate distinct sub-responsibilities: @@ -81,9 +81,9 @@ Two private methods encapsulate distinct sub-responsibilities: This separation keeps `EnsureCachedAsync` at a high level of abstraction and makes each sub-task individually readable. -## Method Descriptions +### Method Descriptions -### `EnsureCachedAsync(string packageId, string version, CancellationToken)` +#### `EnsureCachedAsync(string packageId, string version, CancellationToken)` Ensures a specific NuGet package version is available in the local global packages cache. The method: @@ -103,7 +103,7 @@ Returns the absolute path to the cached package folder. Satisfies requirements `Caching-NuGetCache-EnsureCached`, `Caching-NuGetCache-NullValidation`, and `Caching-NuGetCache-NotFound`. -### `TryDownloadPackageAsync` (private) +#### `TryDownloadPackageAsync` (private) Attempts to download a NuGet package from a single `SourceRepository`. The method: @@ -116,7 +116,7 @@ Attempts to download a NuGet package from a single `SourceRepository`. The metho `GlobalPackagesFolderUtility.AddPackageAsync`. 4. Returns the conventional package path on success. -### `GetPackagePath` (private) +#### `GetPackagePath` (private) Computes the conventional on-disk path that NuGet uses for an installed package: diff --git a/docs/design/nuget-caching/path-helpers.md b/docs/design/nuget-caching/path-helpers.md index 289b8f3..74d755e 100644 --- a/docs/design/nuget-caching/path-helpers.md +++ b/docs/design/nuget-caching/path-helpers.md @@ -1,6 +1,6 @@ -# PathHelpers Design +## PathHelpers Design -## Overview +### Overview `PathHelpers` is an internal static utility class providing a safe path-combination method in the DemaConsulting NuGet Caching library. It protects callers against path-traversal @@ -11,9 +11,9 @@ points, so this check guards against string-level traversal only. The class is marked `internal` because it is an implementation detail of the library and is not part of the public API surface. -## Class Structure +### Class Structure -### SafePathCombine Method +#### SafePathCombine Method ```csharp internal static string SafePathCombine(string basePath, string relativePath) @@ -33,22 +33,22 @@ the base directory. `Path.DirectorySeparatorChar` or `Path.AltDirectorySeparatorChar`, or is itself rooted (absolute), which would indicate the combined path escapes the base directory. -## Design Decisions +### Design Decisions -### Internal Class +#### Internal Class `PathHelpers` is declared `internal` to enforce encapsulation. Callers outside the assembly have no need to perform safe path combination using this class; they interact only with the `NuGetCache` public API. Keeping the class internal prevents accidental coupling to an implementation detail and keeps the public API surface minimal. -### Static Class +#### Static Class All operations in `PathHelpers` are pure functions that depend only on their input parameters and have no side effects. A static class is therefore appropriate: it requires no instantiation and has no lifecycle to manage. -### `Path.GetRelativePath` for Containment Check +#### `Path.GetRelativePath` for Containment Check Using `GetRelativePath` to verify containment handles root paths (e.g. `/`, `C:\`), platform case-sensitivity, and directory-separator normalization natively. The containment @@ -56,13 +56,13 @@ test treats `..` as an escaping segment only when it is the entire relative resu followed by a directory separator, avoiding false positives for valid in-base names such as `..data`. -### Post-Combine Canonical-Path Check +#### Post-Combine Canonical-Path Check Resolving paths after combining handles all traversal patterns — `../`, embedded `/../`, absolute-path overrides, and platform edge cases — without fragile pre-combine string inspection of `relativePath`. -### .NET Standard 2.0 Compatibility +#### .NET Standard 2.0 Compatibility `Path.GetRelativePath` is available on all supported target frameworks via the Polyfill library, which provides a compatible implementation for `netstandard2.0`. @@ -73,7 +73,7 @@ library, which provides a compatible implementation for `netstandard2.0`. > are therefore outside the scope of this protection; callers are responsible for ensuring > the base directory contains no untrusted symbolic links. -### Rejection Strategy +#### Rejection Strategy Rather than sanitizing or normalizing an invalid path, `SafePathCombine` throws an `ArgumentException` immediately when a violation is detected. Failing fast with a clear @@ -81,14 +81,14 @@ exception is preferable to silently correcting or ignoring potentially malicious as it surfaces bugs in calling code during development and makes security boundaries explicit. -### No Logging or Error Accumulation +#### No Logging or Error Accumulation `SafePathCombine` is a pure utility method that throws on invalid input; it does not interact with any context or output mechanism. -## Method Descriptions +### Method Descriptions -### `SafePathCombine(string basePath, string relativePath)` +#### `SafePathCombine(string basePath, string relativePath)` Safely combines `basePath` and `relativePath`, returning the resulting path string. diff --git a/docs/reqstream/nuget-caching/nuget-caching.yaml b/docs/reqstream/nuget-caching.yaml similarity index 100% rename from docs/reqstream/nuget-caching/nuget-caching.yaml rename to docs/reqstream/nuget-caching.yaml diff --git a/docs/verification/definition.yaml b/docs/verification/definition.yaml index 638d3a8..26f0abc 100644 --- a/docs/verification/definition.yaml +++ b/docs/verification/definition.yaml @@ -8,9 +8,10 @@ resource-path: input-files: - docs/verification/title.txt - docs/verification/introduction.md - - docs/verification/nuget-caching/nuget-caching.md + - docs/verification/nuget-caching.md - docs/verification/nuget-caching/nuget-cache.md - docs/verification/nuget-caching/path-helpers.md + - docs/verification/ots.md - docs/verification/ots/buildmark.md - docs/verification/ots/fileassert.md - docs/verification/ots/pandoc.md diff --git a/docs/verification/introduction.md b/docs/verification/introduction.md index f1c21ad..451530a 100644 --- a/docs/verification/introduction.md +++ b/docs/verification/introduction.md @@ -64,15 +64,15 @@ OTS Items In-house items have corresponding artifacts in parallel directory trees: -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source code: `src/{System}/.../{Item}.cs` (PascalCase for C#) -- Tests: `test/{System}.Tests/.../{Item}Tests.cs` (PascalCase for C#) +- Requirements: `docs/reqstream/{system-name}.yaml`, `docs/reqstream/{system-name}/.../{item}.yaml` +- Design: `docs/design/{system-name}.md`, `docs/design/{system-name}/.../{item}.md` +- Verification: `docs/verification/{system-name}.md`, `docs/verification/{system-name}/.../{item}.md` +- Source code: `src/{SystemName}/.../{Item}.cs` (PascalCase for C#) +- Tests: `test/{SystemName}.Tests/.../{Item}Tests.cs` (PascalCase for C#) OTS items have parallel artifacts in: -- Requirements: `docs/reqstream/ots/{ots-name}.yaml` (kebab-case) -- Verification: `docs/verification/ots/{ots-name}.md` (kebab-case) +- Requirements: `docs/reqstream/ots/{ots-name}.yaml` +- Verification: `docs/verification/ots/{ots-name}.md` Review-sets: defined in `.reviewmark.yaml` diff --git a/docs/verification/nuget-caching/nuget-caching.md b/docs/verification/nuget-caching.md similarity index 100% rename from docs/verification/nuget-caching/nuget-caching.md rename to docs/verification/nuget-caching.md diff --git a/docs/verification/nuget-caching/nuget-cache.md b/docs/verification/nuget-caching/nuget-cache.md index 12154a2..85ee425 100644 --- a/docs/verification/nuget-caching/nuget-cache.md +++ b/docs/verification/nuget-caching/nuget-cache.md @@ -1,23 +1,23 @@ -# NuGetCache Unit Verification +## NuGetCache Unit Verification This document provides the verification design for the `NuGetCache` unit. Requirements for this unit are defined in the NuGetCache Unit Requirements document. -## Required Functionality +### Required Functionality The `NuGetCache` unit shall ensure a specified NuGet package version is available in the local cache, reject null arguments, and report an error when the requested package cannot be found in any configured NuGet source. -## Verification Approach +### Verification Approach Unit requirements are verified by tests that exercise `NuGetCache.EnsureCachedAsync` through its full execution path, including network access for cache-miss scenarios. Each test scenario names a specific test method that provides evidence for one or more unit requirements. -## Test Scenarios +### Test Scenarios -### NuGetCache_EnsureCachedAsync_ValidPackageId_ReturnsPackageFolder +#### NuGetCache_EnsureCachedAsync_ValidPackageId_ReturnsPackageFolder **Scenario**: `EnsureCachedAsync` is called with a valid package ID and version. The package may already be cached (cache hit) or may require downloading (cache miss). @@ -26,7 +26,7 @@ already be cached (cache hit) or may require downloading (cache miss). **Requirement coverage**: `Caching-NuGetCache-EnsureCached`. -### NuGetCache_EnsureCachedAsync_CalledTwiceWithSamePackage_ReturnsSamePath +#### NuGetCache_EnsureCachedAsync_CalledTwiceWithSamePackage_ReturnsSamePath **Scenario**: `EnsureCachedAsync` is called twice with the same package ID and version. The second call exercises the early-exit cache-hit path via the `.nupkg.metadata` sentinel check. @@ -36,7 +36,7 @@ consistent results. **Requirement coverage**: `Caching-NuGetCache-EnsureCached`. -### NuGetCache_EnsureCachedAsync_NullPackageId_ThrowsArgumentNullException +#### NuGetCache_EnsureCachedAsync_NullPackageId_ThrowsArgumentNullException **Scenario**: `EnsureCachedAsync` is called with a null `packageId`. @@ -44,7 +44,7 @@ consistent results. **Requirement coverage**: `Caching-NuGetCache-NullValidation`. -### NuGetCache_EnsureCachedAsync_NullVersion_ThrowsArgumentNullException +#### NuGetCache_EnsureCachedAsync_NullVersion_ThrowsArgumentNullException **Scenario**: `EnsureCachedAsync` is called with a null `version`. @@ -52,7 +52,7 @@ consistent results. **Requirement coverage**: `Caching-NuGetCache-NullValidation`. -### NuGetCache_EnsureCachedAsync_PackageAbsentFromAllSources_ThrowsInvalidOperationException +#### NuGetCache_EnsureCachedAsync_PackageAbsentFromAllSources_ThrowsInvalidOperationException **Scenario**: `EnsureCachedAsync` is called with a package ID and version that is not present in any configured NuGet source. @@ -61,7 +61,7 @@ any configured NuGet source. **Requirement coverage**: `Caching-NuGetCache-NotFound`. -## Requirements Coverage +### Requirements Coverage - **`Caching-NuGetCache-EnsureCached`**: NuGetCache_EnsureCachedAsync_ValidPackageId_ReturnsPackageFolder, diff --git a/docs/verification/nuget-caching/path-helpers.md b/docs/verification/nuget-caching/path-helpers.md index 1be44f9..3dd95cc 100644 --- a/docs/verification/nuget-caching/path-helpers.md +++ b/docs/verification/nuget-caching/path-helpers.md @@ -1,22 +1,22 @@ -# PathHelpers Unit Verification +## PathHelpers Unit Verification This document provides the verification design for the `PathHelpers` unit. Requirements for this unit are defined in the PathHelpers Unit Requirements document. -## Required Functionality +### Required Functionality The `PathHelpers` unit shall safely combine a base path and a relative path, rejecting any combination that would escape the base directory. -## Verification Approach +### Verification Approach Unit requirements are verified by tests that exercise `PathHelpers.SafePathCombine` across a range of valid and invalid input combinations. Each test scenario names a specific test method that provides evidence for the unit requirement. -## Test Scenarios +### Test Scenarios -### PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly +#### PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly **Scenario**: `SafePathCombine` is called with a valid base path and a valid relative path that stays within the base. @@ -25,7 +25,7 @@ stays within the base. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException +#### PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException **Scenario**: `SafePathCombine` is called with a relative path of `..` that would escape the base directory. @@ -34,7 +34,7 @@ directory. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_DoubleDotsInMiddle_ThrowsArgumentException +#### PathHelpers_SafePathCombine_DoubleDotsInMiddle_ThrowsArgumentException **Scenario**: `SafePathCombine` is called with a relative path containing an embedded `../` that would escape the base directory. @@ -43,7 +43,7 @@ would escape the base directory. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException +#### PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException **Scenario**: `SafePathCombine` is called with an absolute path as the relative component. @@ -51,7 +51,7 @@ would escape the base directory. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_DotDotPrefixedName_CombinesCorrectly +#### PathHelpers_SafePathCombine_DotDotPrefixedName_CombinesCorrectly **Scenario**: `SafePathCombine` is called with a relative path whose name starts with `..` but does not perform traversal (e.g., `..data`). @@ -60,7 +60,7 @@ does not perform traversal (e.g., `..data`). **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly +#### PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly **Scenario**: `SafePathCombine` is called with a relative path containing nested subdirectories that stay within the base. @@ -69,7 +69,7 @@ that stay within the base. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_SimpleFilename_CombinesCorrectly +#### PathHelpers_SafePathCombine_SimpleFilename_CombinesCorrectly **Scenario**: `SafePathCombine` is called with a simple filename as the relative component. @@ -77,7 +77,7 @@ that stay within the base. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_GuidBasedFilename_CombinesSuccessfully +#### PathHelpers_SafePathCombine_GuidBasedFilename_CombinesSuccessfully **Scenario**: `SafePathCombine` is called with a GUID-format filename as the relative component. @@ -85,7 +85,7 @@ that stay within the base. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_EmptyRelativePath_ReturnsBasePath +#### PathHelpers_SafePathCombine_EmptyRelativePath_ReturnsBasePath **Scenario**: `SafePathCombine` is called with an empty string as the relative component. @@ -93,7 +93,7 @@ that stay within the base. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_CurrentDirectoryReference_CombinesCorrectly +#### PathHelpers_SafePathCombine_CurrentDirectoryReference_CombinesCorrectly **Scenario**: `SafePathCombine` is called with `.` or a path starting with `./` as the relative component. @@ -102,7 +102,7 @@ component. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_NullBasePath_ThrowsArgumentNullException +#### PathHelpers_SafePathCombine_NullBasePath_ThrowsArgumentNullException **Scenario**: `SafePathCombine` is called with a null base path. @@ -110,7 +110,7 @@ component. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -### PathHelpers_SafePathCombine_NullRelativePath_ThrowsArgumentNullException +#### PathHelpers_SafePathCombine_NullRelativePath_ThrowsArgumentNullException **Scenario**: `SafePathCombine` is called with a null relative path. @@ -118,7 +118,7 @@ component. **Requirement coverage**: `Caching-PathHelpers-SafeCombine`. -## Requirements Coverage +### Requirements Coverage - **`Caching-PathHelpers-SafeCombine`**: PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly, diff --git a/docs/verification/ots.md b/docs/verification/ots.md new file mode 100644 index 0000000..9073f28 --- /dev/null +++ b/docs/verification/ots.md @@ -0,0 +1,9 @@ +# OTS Software Verification + +This section provides verification evidence for the OTS (Off-The-Shelf) software items used by the +DemaConsulting NuGet Caching library. OTS items are third-party components not developed in-house; +their requirements are defined in the OTS Software Requirements documents and their verification +relies on self-validation test suites, CI pipeline evidence, and vendor-provided compliance data. + +Each OTS item has a dedicated verification document in this section covering the required +functionality, the verification approach, named test scenarios, and a requirements coverage mapping. diff --git a/docs/verification/ots/buildmark.md b/docs/verification/ots/buildmark.md index 3fc3cc2..b73ac39 100644 --- a/docs/verification/ots/buildmark.md +++ b/docs/verification/ots/buildmark.md @@ -1,15 +1,15 @@ -# BuildMark Verification +## BuildMark Verification This document provides the verification evidence for the `BuildMark` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and renders them as a markdown build-notes document included in the release artifacts. It runs as part of the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that BuildMark executed without error. -## Verification Approach +### Verification Approach BuildMark is verified by two complementary layers of evidence. First, the CI pipeline runs `buildmark --validate --results artifacts/buildmark-self-validation.trx`, which exercises @@ -22,9 +22,9 @@ artifact, and FileAssert asserts the PDF exists, has content, and contains expec (`WeasyPrint_BuildNotesPdf`). A CI build failure at any step in this chain is evidence that BuildMark did not produce the required output. -## Test Scenarios +### Test Scenarios -### BuildMark_MarkdownReportGeneration +#### BuildMark_MarkdownReportGeneration **Scenario**: A CI pipeline run triggers BuildMark with live GitHub Actions metadata. @@ -33,7 +33,7 @@ in the release artifacts. **Requirement coverage**: `Caching-OTS-BuildMark`. -### BuildMark_GitIntegration +#### BuildMark_GitIntegration **Scenario**: BuildMark self-validation reads version tags and commits from a mock Git history. @@ -41,7 +41,7 @@ in the release artifacts. **Requirement coverage**: `Caching-OTS-BuildMark`. -### BuildMark_IssueTracking +#### BuildMark_IssueTracking **Scenario**: BuildMark self-validation processes mock GitHub issues and pull requests. @@ -49,7 +49,7 @@ in the release artifacts. **Requirement coverage**: `Caching-OTS-BuildMark`. -### BuildMark_KnownIssuesReporting +#### BuildMark_KnownIssuesReporting **Scenario**: BuildMark self-validation includes open bugs in the generated report when requested. @@ -57,7 +57,7 @@ in the release artifacts. **Requirement coverage**: `Caching-OTS-BuildMark`. -### BuildMark_RulesRouting +#### BuildMark_RulesRouting **Scenario**: BuildMark self-validation assigns mock items to report sections based on label and type rules. @@ -66,7 +66,7 @@ type rules. **Requirement coverage**: `Caching-OTS-BuildMark`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-BuildMark`**: BuildMark_MarkdownReportGeneration, BuildMark_GitIntegration, BuildMark_IssueTracking, BuildMark_KnownIssuesReporting, BuildMark_RulesRouting diff --git a/docs/verification/ots/fileassert.md b/docs/verification/ots/fileassert.md index 9126020..bb779d7 100644 --- a/docs/verification/ots/fileassert.md +++ b/docs/verification/ots/fileassert.md @@ -1,9 +1,9 @@ -# FileAssert Verification +## FileAssert Verification This document provides the verification evidence for the FileAssert OTS software item. Requirements for this OTS item are defined in the FileAssert OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.FileAssert validates HTML and PDF documents produced during the build, asserting that each document exists, has a non-trivial size, is structurally valid, and contains expected content. @@ -11,7 +11,7 @@ It provides OTS evidence for Pandoc and WeasyPrint and independently confirms fi functioning. Self-validation proves the tool itself is operational before ReqStream consumes the results. -## Verification Approach +### Verification Approach FileAssert is verified by two complementary layers of evidence. First, the CI pipeline runs `fileassert --validate --results artifacts/fileassert-self-validation.trx` after all documents @@ -25,9 +25,9 @@ incorrect results, causing `reqstream --enforce` to report missing test coverage build. A passing CI build therefore constitutes transitive evidence that FileAssert correctly asserted document content at each stage of the pipeline. -## Test Scenarios +### Test Scenarios -### FileAssert_Results +#### FileAssert_Results **Scenario**: FileAssert self-validation exercises the `--results` option, generating TRX test results containing both passing and failing outcomes. @@ -36,7 +36,7 @@ results containing both passing and failing outcomes. **Requirement coverage**: `Caching-OTS-FileAssert`. -### FileAssert_Exists +#### FileAssert_Exists **Scenario**: FileAssert self-validation exercises a test configuration using a glob pattern to assert file existence. @@ -45,7 +45,7 @@ assert file existence. **Requirement coverage**: `Caching-OTS-FileAssert`. -### FileAssert_Contains +#### FileAssert_Contains **Scenario**: FileAssert self-validation exercises a test configuration using a `contains` assertion to verify file content. @@ -54,6 +54,6 @@ to verify file content. **Requirement coverage**: `Caching-OTS-FileAssert`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-FileAssert`**: FileAssert_Results, FileAssert_Exists, FileAssert_Contains diff --git a/docs/verification/ots/pandoc.md b/docs/verification/ots/pandoc.md index 0ce988d..8066733 100644 --- a/docs/verification/ots/pandoc.md +++ b/docs/verification/ots/pandoc.md @@ -1,23 +1,23 @@ -# Pandoc Verification +## Pandoc Verification This document provides the verification evidence for the `Pandoc` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.PandocTool converts Markdown source documents to HTML as part of the documentation build pipeline. FileAssert validates that each generated HTML file exists, has a non-trivial size, contains a valid HTML title element, and includes expected document content. Passing FileAssert assertions for each document type proves Pandoc executed correctly and produced meaningful output. -## Verification Approach +### Verification Approach Pandoc is verified by self-validation evidence from the CI pipeline. Each scenario is a FileAssert assertion that runs after Pandoc converts a specific Markdown document to HTML. A passing pipeline run for all scenarios constitutes evidence that the requirement is satisfied. -## Test Scenarios +### Test Scenarios -### Pandoc_BuildNotesHtml +#### Pandoc_BuildNotesHtml **Scenario**: FileAssert asserts the build-notes HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected document content. @@ -26,7 +26,7 @@ a valid HTML title element, and includes expected document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -### Pandoc_CodeQualityHtml +#### Pandoc_CodeQualityHtml **Scenario**: FileAssert asserts the code-quality HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected document content. @@ -35,7 +35,7 @@ a valid HTML title element, and includes expected document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -### Pandoc_ReviewPlanHtml +#### Pandoc_ReviewPlanHtml **Scenario**: FileAssert asserts the review plan HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected document content. @@ -44,7 +44,7 @@ a valid HTML title element, and includes expected document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -### Pandoc_ReviewReportHtml +#### Pandoc_ReviewReportHtml **Scenario**: FileAssert asserts the review report HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected document content. @@ -53,7 +53,7 @@ contains a valid HTML title element, and includes expected document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -### Pandoc_DesignHtml +#### Pandoc_DesignHtml **Scenario**: FileAssert asserts the design document HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected document content. @@ -62,7 +62,7 @@ contains a valid HTML title element, and includes expected document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -### Pandoc_VerificationHtml +#### Pandoc_VerificationHtml **Scenario**: FileAssert asserts the verification HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected verification document content. @@ -71,7 +71,7 @@ a valid HTML title element, and includes expected verification document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -### Pandoc_UserGuideHtml +#### Pandoc_UserGuideHtml **Scenario**: FileAssert asserts the user guide HTML file exists, is non-trivially sized, contains a valid HTML title element, and includes expected document content. @@ -80,7 +80,7 @@ a valid HTML title element, and includes expected document content. **Requirement coverage**: `Caching-OTS-Pandoc`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-Pandoc`**: Pandoc_BuildNotesHtml, Pandoc_CodeQualityHtml, Pandoc_ReviewPlanHtml, Pandoc_ReviewReportHtml, Pandoc_DesignHtml, Pandoc_VerificationHtml, Pandoc_UserGuideHtml diff --git a/docs/verification/ots/reqstream.md b/docs/verification/ots/reqstream.md index 1dc660d..caa2c5a 100644 --- a/docs/verification/ots/reqstream.md +++ b/docs/verification/ots/reqstream.md @@ -1,8 +1,8 @@ -# ReqStream Verification +## ReqStream Verification This document provides the verification evidence for the `ReqStream` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to produce a requirements report, justifications document, and traceability matrix. When run with `--enforce`, it @@ -10,7 +10,7 @@ exits with a non-zero code if any requirement lacks test evidence, making unprov build-breaking condition. A successful pipeline run with `--enforce` proves all requirements are covered and that ReqStream is functioning. -## Verification Approach +### Verification Approach ReqStream is verified by two complementary layers of evidence. First, the CI pipeline runs `reqstream --validate --results artifacts/reqstream-self-validation.trx`, which exercises @@ -25,9 +25,9 @@ non-zero if any requirement lacks test evidence, which would also fail the build CI build proves ReqStream correctly processed the project's real requirements and found complete test coverage. -## Test Scenarios +### Test Scenarios -### ReqStream_RequirementsProcessing +#### ReqStream_RequirementsProcessing **Scenario**: ReqStream self-validation loads and processes a set of requirements YAML files. @@ -35,7 +35,7 @@ complete test coverage. **Requirement coverage**: `Caching-OTS-ReqStream`. -### ReqStream_TraceMatrix +#### ReqStream_TraceMatrix **Scenario**: ReqStream self-validation generates a trace matrix from requirements and TRX test results. @@ -44,7 +44,7 @@ results. **Requirement coverage**: `Caching-OTS-ReqStream`. -### ReqStream_ReportExport +#### ReqStream_ReportExport **Scenario**: ReqStream self-validation exports a requirements report to a markdown file. @@ -52,7 +52,7 @@ results. **Requirement coverage**: `Caching-OTS-ReqStream`. -### ReqStream_TagsFiltering +#### ReqStream_TagsFiltering **Scenario**: ReqStream self-validation filters requirements by tags. @@ -60,7 +60,7 @@ results. **Requirement coverage**: `Caching-OTS-ReqStream`. -### ReqStream_EnforcementMode +#### ReqStream_EnforcementMode **Scenario**: ReqStream self-validation exercises enforcement mode where all requirements have test coverage. @@ -69,7 +69,7 @@ coverage. **Requirement coverage**: `Caching-OTS-ReqStream`. -### ReqStream_Lint +#### ReqStream_Lint **Scenario**: ReqStream self-validation exercises lint mode against a requirements file with deliberate issues. @@ -78,7 +78,7 @@ deliberate issues. **Requirement coverage**: `Caching-OTS-ReqStream`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-ReqStream`**: ReqStream_RequirementsProcessing, ReqStream_TraceMatrix, ReqStream_ReportExport, ReqStream_TagsFiltering, ReqStream_EnforcementMode, ReqStream_Lint diff --git a/docs/verification/ots/reviewmark.md b/docs/verification/ots/reviewmark.md index 9ae63fc..1cdff99 100644 --- a/docs/verification/ots/reviewmark.md +++ b/docs/verification/ots/reviewmark.md @@ -1,16 +1,16 @@ -# ReviewMark Verification +## ReviewMark Verification This document provides the verification evidence for the ReviewMark OTS software item. Requirements for this OTS item are defined in the ReviewMark OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.ReviewMark reads the `.reviewmark.yaml` configuration and the review evidence store to produce a review plan and review report documenting file review coverage and currency. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that ReviewMark executed without error. -## Verification Approach +### Verification Approach ReviewMark is verified by two complementary layers of evidence. First, the CI pipeline runs `reviewmark --validate --results artifacts/reviewmark-self-validation.trx`, which exercises @@ -24,9 +24,9 @@ WeasyPrint renders both to PDF and FileAssert asserts their content (`WeasyPrint_ReviewPlanPdf`, `WeasyPrint_ReviewReportPdf`). A CI build failure at any step is evidence that ReviewMark did not produce the required review documents. -## Test Scenarios +### Test Scenarios -### ReviewMark_ReviewPlanGeneration +#### ReviewMark_ReviewPlanGeneration **Scenario**: ReviewMark self-validation uses `--definition` and `--plan` to generate a review plan from a test configuration. @@ -35,7 +35,7 @@ from a test configuration. **Requirement coverage**: `Caching-OTS-ReviewMark`. -### ReviewMark_ReviewReportGeneration +#### ReviewMark_ReviewReportGeneration **Scenario**: ReviewMark self-validation uses `--definition` and `--report` to generate a review report from a test configuration and evidence store. @@ -44,7 +44,7 @@ report from a test configuration and evidence store. **Requirement coverage**: `Caching-OTS-ReviewMark`. -### ReviewMark_IndexScan +#### ReviewMark_IndexScan **Scenario**: ReviewMark self-validation uses `--index` to scan PDF evidence files and write an `index.json` catalogue. @@ -53,7 +53,7 @@ report from a test configuration and evidence store. **Requirement coverage**: `Caching-OTS-ReviewMark-Operations`. -### ReviewMark_WorkingDirectoryOverride +#### ReviewMark_WorkingDirectoryOverride **Scenario**: ReviewMark self-validation uses `--dir` to override the working directory for file operations. @@ -62,7 +62,7 @@ operations. **Requirement coverage**: `Caching-OTS-ReviewMark-Operations`. -### ReviewMark_Enforce +#### ReviewMark_Enforce **Scenario**: ReviewMark self-validation uses `--enforce` against a configuration with review issues. @@ -71,7 +71,7 @@ issues. **Requirement coverage**: `Caching-OTS-ReviewMark-Operations`. -### ReviewMark_Elaborate +#### ReviewMark_Elaborate **Scenario**: ReviewMark self-validation uses `--elaborate` to print a Markdown elaboration of a named review set. @@ -80,7 +80,7 @@ named review set. **Requirement coverage**: `Caching-OTS-ReviewMark-Operations`. -### ReviewMark_Lint +#### ReviewMark_Lint **Scenario**: ReviewMark self-validation uses `--lint` to validate a definition file and report issues. @@ -89,7 +89,7 @@ issues. **Requirement coverage**: `Caching-OTS-ReviewMark-Operations`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-ReviewMark`**: ReviewMark_ReviewPlanGeneration, ReviewMark_ReviewReportGeneration - **`Caching-OTS-ReviewMark-Operations`**: ReviewMark_IndexScan, ReviewMark_WorkingDirectoryOverride, diff --git a/docs/verification/ots/sarifmark.md b/docs/verification/ots/sarifmark.md index 897dbc6..fe4fa6e 100644 --- a/docs/verification/ots/sarifmark.md +++ b/docs/verification/ots/sarifmark.md @@ -1,16 +1,16 @@ -# SarifMark Verification +## SarifMark Verification This document provides the verification evidence for the SarifMark OTS software item. Requirements for this OTS item are defined in the SarifMark OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and renders it as a human-readable markdown document included in the release artifacts. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that SarifMark executed without error. -## Verification Approach +### Verification Approach SarifMark is verified by two complementary layers of evidence. First, the CI pipeline runs `sarifmark --validate --results artifacts/sarifmark-self-validation.trx`, which exercises @@ -24,9 +24,9 @@ renders the result to PDF and FileAssert asserts the PDF contains expected conte (`WeasyPrint_CodeQualityPdf`). A CI build failure at any step is evidence that SarifMark did not produce the required output. -## Test Scenarios +### Test Scenarios -### SarifMark_SarifReading +#### SarifMark_SarifReading **Scenario**: SarifMark is invoked with a CodeQL SARIF results file as input. @@ -34,7 +34,7 @@ not produce the required output. **Requirement coverage**: `Caching-OTS-SarifMark`. -### SarifMark_MarkdownReportGeneration +#### SarifMark_MarkdownReportGeneration **Scenario**: SarifMark renders the SARIF input as a markdown report included in the release artifacts. @@ -43,7 +43,7 @@ artifacts. **Requirement coverage**: `Caching-OTS-SarifMark`. -### SarifMark_Enforcement +#### SarifMark_Enforcement **Scenario**: SarifMark self-validation processes a SARIF file containing known issues in enforcement mode. @@ -52,7 +52,7 @@ enforcement mode. **Requirement coverage**: `Caching-OTS-SarifMark-Enforcement`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-SarifMark`**: SarifMark_SarifReading, SarifMark_MarkdownReportGeneration - **`Caching-OTS-SarifMark-Enforcement`**: SarifMark_Enforcement diff --git a/docs/verification/ots/sonarmark.md b/docs/verification/ots/sonarmark.md index 2f55275..14e0851 100644 --- a/docs/verification/ots/sonarmark.md +++ b/docs/verification/ots/sonarmark.md @@ -1,16 +1,16 @@ -# SonarMark Verification +## SonarMark Verification This document provides the verification evidence for the SonarMark OTS software item. Requirements for this OTS item are defined in the SonarMark OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and renders it as a markdown document included in the release artifacts. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that SonarMark executed without error. -## Verification Approach +### Verification Approach SonarMark is verified by two complementary layers of evidence. First, the CI pipeline runs `sonarmark --validate --results artifacts/sonarmark-self-validation.trx`, which exercises @@ -24,9 +24,9 @@ renders the result to PDF and FileAssert asserts the PDF contains expected conte (`WeasyPrint_CodeQualityPdf`). A CI build failure at any step is evidence that SonarMark did not retrieve and render quality data correctly. -## Test Scenarios +### Test Scenarios -### SonarMark_QualityGateRetrieval +#### SonarMark_QualityGateRetrieval **Scenario**: SonarMark queries the SonarCloud API for quality-gate status. @@ -34,7 +34,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Caching-OTS-SonarMark`. -### SonarMark_IssuesRetrieval +#### SonarMark_IssuesRetrieval **Scenario**: SonarMark queries the SonarCloud API for issues. @@ -42,7 +42,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Caching-OTS-SonarMark`. -### SonarMark_HotSpotsRetrieval +#### SonarMark_HotSpotsRetrieval **Scenario**: SonarMark queries the SonarCloud API for hot spots. @@ -50,7 +50,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Caching-OTS-SonarMark`. -### SonarMark_MarkdownReportGeneration +#### SonarMark_MarkdownReportGeneration **Scenario**: SonarMark renders quality-gate, issues, and hot-spots data as a markdown report. @@ -58,7 +58,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Caching-OTS-SonarMark`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-SonarMark`**: SonarMark_QualityGateRetrieval, SonarMark_IssuesRetrieval, SonarMark_HotSpotsRetrieval, SonarMark_MarkdownReportGeneration diff --git a/docs/verification/ots/versionmark.md b/docs/verification/ots/versionmark.md index df24a9a..51a68fd 100644 --- a/docs/verification/ots/versionmark.md +++ b/docs/verification/ots/versionmark.md @@ -1,15 +1,15 @@ -# VersionMark Verification +## VersionMark Verification This document provides the verification evidence for the `VersionMark` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the pipeline and writes a versions markdown document included in the release artifacts. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that VersionMark executed without error. -## Verification Approach +### Verification Approach VersionMark is verified by two complementary layers of evidence. First, the CI pipeline runs `versionmark --validate --results *.trx` in each build job, exercising VersionMark's built-in @@ -23,9 +23,9 @@ compilation would be incomplete. WeasyPrint renders the result to PDF and FileAs its content (`WeasyPrint_BuildNotesPdf`). A CI build failure at any step is evidence that VersionMark did not execute correctly. -## Test Scenarios +### Test Scenarios -### VersionMark_CapturesVersions +#### VersionMark_CapturesVersions **Scenario**: VersionMark reads version metadata for each dotnet tool defined in the pipeline. @@ -33,7 +33,7 @@ VersionMark did not execute correctly. **Requirement coverage**: `Caching-OTS-VersionMark`. -### VersionMark_GeneratesMarkdownReport +#### VersionMark_GeneratesMarkdownReport **Scenario**: VersionMark writes a versions markdown document to the release artifacts. @@ -41,7 +41,7 @@ VersionMark did not execute correctly. **Requirement coverage**: `Caching-OTS-VersionMark`. -### VersionMark_LintPassesForValidConfig +#### VersionMark_LintPassesForValidConfig **Scenario**: VersionMark self-validation exercises lint mode against a valid `.versionmark.yaml` config. @@ -50,7 +50,7 @@ config. **Requirement coverage**: `Caching-OTS-VersionMark`. -### VersionMark_LintReportsErrorsForInvalidConfig +#### VersionMark_LintReportsErrorsForInvalidConfig **Scenario**: VersionMark self-validation exercises lint mode against a malformed config with deliberate errors. @@ -59,7 +59,7 @@ deliberate errors. **Requirement coverage**: `Caching-OTS-VersionMark`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-VersionMark`**: VersionMark_CapturesVersions, VersionMark_GeneratesMarkdownReport, VersionMark_LintPassesForValidConfig, VersionMark_LintReportsErrorsForInvalidConfig diff --git a/docs/verification/ots/weasyprint.md b/docs/verification/ots/weasyprint.md index 2c11f62..6ce6dae 100644 --- a/docs/verification/ots/weasyprint.md +++ b/docs/verification/ots/weasyprint.md @@ -1,9 +1,9 @@ -# WeasyPrint Verification +## WeasyPrint Verification This document provides the verification evidence for the WeasyPrint OTS software item. Requirements for this OTS item are defined in the WeasyPrint OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.WeasyPrintTool converts HTML documents to PDF as part of the documentation build pipeline. FileAssert validates that each generated PDF file exists, has a non-trivial size, contains @@ -11,15 +11,15 @@ at least one page, and includes expected document content in the rendered text. assertions for each document type proves WeasyPrint executed correctly and produced meaningful output. -## Verification Approach +### Verification Approach WeasyPrint is verified by self-validation evidence from the CI pipeline. Each scenario is a FileAssert assertion that runs after WeasyPrint converts a specific HTML document to PDF. A passing pipeline run for all scenarios constitutes evidence that the requirement is satisfied. -## Test Scenarios +### Test Scenarios -### WeasyPrint_BuildNotesPdf +#### WeasyPrint_BuildNotesPdf **Scenario**: FileAssert asserts the build-notes PDF file exists, is non-trivially sized, contains at least one page, and includes expected document content. @@ -28,7 +28,7 @@ at least one page, and includes expected document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -### WeasyPrint_CodeQualityPdf +#### WeasyPrint_CodeQualityPdf **Scenario**: FileAssert asserts the code-quality PDF file exists, is non-trivially sized, contains at least one page, and includes expected document content. @@ -37,7 +37,7 @@ at least one page, and includes expected document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -### WeasyPrint_ReviewPlanPdf +#### WeasyPrint_ReviewPlanPdf **Scenario**: FileAssert asserts the review plan PDF file exists, is non-trivially sized, contains at least one page, and includes expected document content. @@ -46,7 +46,7 @@ at least one page, and includes expected document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -### WeasyPrint_ReviewReportPdf +#### WeasyPrint_ReviewReportPdf **Scenario**: FileAssert asserts the review report PDF file exists, is non-trivially sized, contains at least one page, and includes expected document content. @@ -55,7 +55,7 @@ at least one page, and includes expected document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -### WeasyPrint_DesignPdf +#### WeasyPrint_DesignPdf **Scenario**: FileAssert asserts the design document PDF file exists, is non-trivially sized, contains at least one page, and includes expected document content. @@ -64,7 +64,7 @@ contains at least one page, and includes expected document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -### WeasyPrint_VerificationPdf +#### WeasyPrint_VerificationPdf **Scenario**: FileAssert asserts the verification PDF file exists, is non-trivially sized, contains at least one page, and includes expected verification document content. @@ -73,7 +73,7 @@ at least one page, and includes expected verification document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -### WeasyPrint_UserGuidePdf +#### WeasyPrint_UserGuidePdf **Scenario**: FileAssert asserts the user guide PDF file exists, is non-trivially sized, contains at least one page, and includes expected document content. @@ -82,7 +82,7 @@ at least one page, and includes expected document content. **Requirement coverage**: `Caching-OTS-WeasyPrint`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-WeasyPrint`**: WeasyPrint_BuildNotesPdf, WeasyPrint_CodeQualityPdf, WeasyPrint_ReviewPlanPdf, WeasyPrint_ReviewReportPdf, WeasyPrint_DesignPdf, diff --git a/docs/verification/ots/xunit.md b/docs/verification/ots/xunit.md index bea4e46..c479bc0 100644 --- a/docs/verification/ots/xunit.md +++ b/docs/verification/ots/xunit.md @@ -1,24 +1,24 @@ -# xUnit Verification +## xUnit Verification This document provides the verification evidence for the xUnit OTS software item. Requirements for this OTS item are defined in the xUnit OTS Software Requirements document. -## Required Functionality +### Required Functionality xUnit v3 (xunit.v3 and xunit.runner.visualstudio) is the unit-testing framework used by the project. It discovers and runs all test methods and writes TRX result files that feed into coverage reporting and requirements traceability. Passing tests confirm the framework is functioning correctly. -## Verification Approach +### Verification Approach xUnit is verified by self-validation evidence from the CI pipeline. Each scenario names a specific test method that xUnit must discover, execute, and record in a TRX result file. A passing pipeline run for all scenarios constitutes evidence that both requirements are satisfied. -## Test Scenarios +### Test Scenarios -### NuGetCache_EnsureCachedAsync_ValidPackageId_ReturnsPackageFolder +#### NuGetCache_EnsureCachedAsync_ValidPackageId_ReturnsPackageFolder **Scenario**: xUnit discovers and runs this test; the test verifies that `EnsureCachedAsync` returns a valid path when called with a known package ID and version. @@ -27,7 +27,7 @@ returns a valid path when called with a known package ID and version. **Requirement coverage**: `Caching-OTS-xUnit-Execute`, `Caching-OTS-xUnit-Report`. -### PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly +#### PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly **Scenario**: xUnit discovers and runs this test; the test verifies that `SafePathCombine` correctly joins valid path segments. @@ -36,7 +36,7 @@ correctly joins valid path segments. **Requirement coverage**: `Caching-OTS-xUnit-Execute`, `Caching-OTS-xUnit-Report`. -### NuGetCache_EnsureCachedAsync_NullPackageId_ThrowsArgumentNullException +#### NuGetCache_EnsureCachedAsync_NullPackageId_ThrowsArgumentNullException **Scenario**: xUnit discovers and runs this test; the test verifies that a null package ID raises `ArgumentNullException`. @@ -45,7 +45,7 @@ correctly joins valid path segments. **Requirement coverage**: `Caching-OTS-xUnit-Execute`, `Caching-OTS-xUnit-Report`. -## Requirements Coverage +### Requirements Coverage - **`Caching-OTS-xUnit-Execute`**: NuGetCache_EnsureCachedAsync_ValidPackageId_ReturnsPackageFolder, PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly, diff --git a/requirements.yaml b/requirements.yaml index f56d672..859015f 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -20,7 +20,7 @@ # list below (system files first, then platform, then subsystem/unit files, then ots files) includes: - - docs/reqstream/nuget-caching/nuget-caching.yaml + - docs/reqstream/nuget-caching.yaml - docs/reqstream/nuget-caching/platform-requirements.yaml - docs/reqstream/nuget-caching/nuget-cache.yaml - docs/reqstream/nuget-caching/path-helpers.yaml From 9adf0db0d0c1a7b5f9f8e877295ffeb32f5cb59a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 5 May 2026 22:33:42 +0000 Subject: [PATCH 2/2] Add docs/verification/ots.md to NuGetCaching-Design review-set Agent-Logs-Url: https://github.com/demaconsulting/NuGetCaching/sessions/1506c0ac-d927-4664-8090-256b22a5f0f4 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index aa577c8..dd276f7 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -58,6 +58,7 @@ reviews: - "docs/design/nuget-caching.md" - "docs/design/nuget-caching/**/*.md" - "docs/verification/introduction.md" + - "docs/verification/ots.md" - id: NuGetCaching-AllRequirements title: Review that All NuGetCaching Requirements are Complete