Fix documentation, requirements, and subsystem test suite issues identified in formal review

.cspell.yaml

@@ -82,6 +82,7 @@ words:
   - spdx
   - streetsidesoftware
   - testname
+  - selftest
   - trace_matrix
   - triaging
   - Trivy

.reviewmark.yaml

@@ -93,38 +93,28 @@ reviews:
     paths:
       - "docs/reqstream/review-mark/cli/cli.yaml"                # subsystem requirements
       - "docs/design/review-mark/cli/cli.md"                     # Cli subsystem design
-      - "docs/design/review-mark/cli/context.md"                 # Context design
-      - "docs/design/review-mark/program.md"                     # Program design
-      - "test/**/Cli/ContextTests.cs"                            # Context unit tests
-      - "test/**/ProgramTests.cs"                                # Program unit tests
+      - "test/**/Cli/CliTests.cs"                                # Cli subsystem tests
 
   - id: ReviewMark-Configuration
     title: Review of Configuration subsystem (configuration parsing and file pattern matching)
     paths:
       - "docs/reqstream/review-mark/configuration/configuration.yaml"           # subsystem requirements
       - "docs/design/review-mark/configuration/configuration.md"                # Configuration subsystem design
-      - "docs/design/review-mark/configuration/review-mark-configuration.md"    # ReviewMarkConfiguration design
-      - "docs/design/review-mark/configuration/glob-matcher.md"                 # GlobMatcher design
-      - "test/**/Configuration/ReviewMarkConfigurationTests.cs"                 # ReviewMarkConfiguration tests
-      - "test/**/Configuration/GlobMatcherTests.cs"                             # GlobMatcher tests
+      - "test/**/Configuration/ConfigurationTests.cs"                           # Configuration subsystem tests
 
   - id: ReviewMark-Indexing
     title: Review of Indexing subsystem (review evidence loading and path utilities)
     paths:
       - "docs/reqstream/review-mark/indexing/indexing.yaml"      # subsystem requirements
       - "docs/design/review-mark/indexing/indexing.md"           # Indexing subsystem design
-      - "docs/design/review-mark/indexing/review-index.md"       # ReviewIndex design
-      - "docs/design/review-mark/indexing/path-helpers.md"       # PathHelpers design
-      - "test/**/Indexing/IndexTests.cs"                         # ReviewIndex tests
-      - "test/**/Indexing/PathHelpersTests.cs"                   # PathHelpers tests
+      - "test/**/Indexing/IndexingTests.cs"                      # Indexing subsystem tests
 
   - id: ReviewMark-SelfTest
     title: Review of SelfTest subsystem (self-validation)
     paths:
       - "docs/reqstream/review-mark/self-test/self-test.yaml"    # subsystem requirements
       - "docs/design/review-mark/self-test/self-test.md"         # SelfTest subsystem design
-      - "docs/design/review-mark/self-test/validation.md"        # Validation design
-      - "test/**/SelfTest/ValidationTests.cs"                    # Validation tests
+      - "test/**/SelfTest/SelfTestTests.cs"                      # SelfTest subsystem tests
 
   # Special review-sets
   - id: ReviewMark-Architecture

docs/design/review-mark/cli/context.md

@@ -20,7 +20,7 @@ arguments:
 | `Validate` | bool | Requests self-validation run |
 | `Lint` | bool | Requests configuration linting |
 | `ResultsFile` | string? | Path for TRX/JUnit test results output |
-| `DefinitionFile` | string | Path to the `.reviewmark.yaml` configuration |
+| `DefinitionFile` | string? | Path to the `.reviewmark.yaml` configuration |
 | `PlanFile` | string? | Output path for the Review Plan document |
 | `PlanDepth` | int | Heading depth for the Review Plan |
 | `ReportFile` | string? | Output path for the Review Report document |

docs/design/review-mark/configuration/review-mark-configuration.md

@@ -17,6 +17,16 @@ The `.reviewmark.yaml` file is deserialized into the following model:
 | `EvidenceSourceYaml` | Describes how to locate the evidence index (`type`, `location`, optional `credentials`) |
 | `ReviewYaml` | Describes a single review-set (`id`, `title`, file patterns) |
 
+### Evidence Source Types
+
+The `type` field of `EvidenceSourceYaml` controls how the evidence index is located:
+
+| Type | Description |
+| ---- | ----------- |
+| `none` | No evidence index is available. The `location` field is optional and ignored. All review-sets are reported as Missing. |
+| `fileshare` | The evidence index is read from the file path specified in `location`. |
+| `url` | The evidence index is downloaded from the HTTP or HTTPS URL specified in `location`. |
+
 ## ReviewMarkConfiguration.Load()
 
 `ReviewMarkConfiguration.Load(filePath)` is the unified loading mechanism that performs
@@ -38,7 +48,7 @@ The fingerprint for a review-set uniquely identifies the exact content of its fi
 The algorithm is:
 
 1. For each file in the review-set, read its contents and compute a SHA-256 hash.
-2. Collect all per-file hashes and sort them lexicographically.
+2. Convert each hash to a lowercase hex string, then collect all per-file hashes and sort them lexicographically.
 3. Concatenate the sorted hashes and compute a SHA-256 hash of the result.
 4. Return the final hash as a hex string — this is the review-set fingerprint.
 

docs/design/review-mark/indexing/path-helpers.md

@@ -1,4 +1,4 @@
-# PathHelpers Design
+# PathHelpers
 
 ## Overview
 

docs/design/review-mark/indexing/review-index.md

@@ -62,22 +62,31 @@ workflow.
 `ReviewIndex.Empty()` returns an index with no records. It is used when the evidence
 source type is `none`, resulting in all review-sets being reported as Missing.
 
-## ReviewIndex.GetStatus()
-
-`ReviewIndex.GetStatus(id, fingerprint)` determines the review status of a
-review-set by looking up the `id` in the loaded index:
-
-1. Look up `id` in the index
-   - If not found — return `Missing`
-2. Check if there is a record whose `Fingerprint` matches the supplied `fingerprint`
-   - If no matching fingerprint exists — return `Stale`
-   - If a matching fingerprint exists:
-     - If the `Result` is `pass` — return `Current`
-     - If the `Result` is not `pass` — return `Failed`
-
-| Status | Meaning |
-| ------ | ------- |
-| `Current` | The review record matches the current fingerprint and has a passing result |
-| `Failed` | The review record matches the current fingerprint but the result is not passing |
-| `Stale` | A record exists for the id but the fingerprint does not match the current one |
-| `Missing` | No review record exists for the id |
+## ReviewIndex.Save()
+
+`ReviewIndex` provides two overloads for persisting the index to `index.json` format:
+
+- `Save(string filePath)` — writes the serialized index to the specified file path
+- `Save(Stream stream)` — writes the serialized index to the provided stream
+
+Both overloads serialize all `ReviewEvidence` records in the index to JSON format.
+The `Save(string filePath)` overload is used by the `--index` workflow in `Program`
+to write the output file after scanning.
+
+## ReviewIndex.GetEvidence()
+
+`ReviewIndex.GetEvidence(string id, string fingerprint)` returns the `ReviewEvidence`
+record whose `Id` matches `id` and whose `Fingerprint` matches `fingerprint`, or `null`
+if no such record exists.
+
+## ReviewIndex.HasId()
+
+`ReviewIndex.HasId(string id)` returns `true` if the index contains at least one record
+with the given `id`, regardless of fingerprint. Returns `false` if no record exists for
+the id.
+
+## ReviewIndex.GetAllForId()
+
+`ReviewIndex.GetAllForId(string id)` returns all `ReviewEvidence` records that have the
+given `id`, as an enumerable collection. Returns an empty collection if no records exist
+for the id.

docs/design/review-mark/self-test/validation.md

@@ -15,7 +15,7 @@ where the tool itself is part of a qualified software chain.
 2. Executes each test case in sequence
 3. Writes results to the configured output file (TRX or JUnit format) if `ResultsFile` is set
 4. Writes a summary table and per-test results to the console via `Context.WriteLine()`
-5. Sets `Context.ExitCode` to a non-zero value if any test fails
+5. Calls `Context.WriteError()` when any test fails, which causes `Context.ExitCode` to return a non-zero value
 
 ## Test Output Format
 

docs/reqstream/review-mark/cli/cli.yaml

@@ -22,6 +22,7 @@ sections:
           - Context_Create_ValidateFlag_SetsValidateTrue
           - Context_Create_ResultsFlag_SetsResultsFile
           - Context_Create_LogFlag_OpensLogFile
+        children: [ReviewMark-Context-Parsing, ReviewMark-Context-Output]
 
       - id: ReviewMark-Cmd-Version
         title: The tool shall support -v and --version flags to display version information.
@@ -34,6 +35,8 @@ sections:
           - Program_Run_WithVersionFlag_DisplaysVersionOnly
           - Program_Version_ReturnsNonEmptyString
           - IntegrationTest_VersionFlag_OutputsVersion
+          - Cli_VersionFlag_OutputsVersionOnly
+        children: [ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Help
         title: The tool shall support -?, -h, and --help flags to display usage information.
@@ -46,6 +49,8 @@ sections:
           - Context_Create_ShortHelpFlag_Question_SetsHelpTrue
           - Program_Run_WithHelpFlag_DisplaysUsageInformation
           - IntegrationTest_HelpFlag_OutputsUsageInformation
+          - Cli_HelpFlag_OutputsUsageInformation
+        children: [ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Silent
         title: The tool shall support --silent flag to suppress console output.
@@ -56,6 +61,8 @@ sections:
           - Context_Create_SilentFlag_SetsSilentTrue
           - Context_WriteLine_Silent_DoesNotWriteToConsole
           - IntegrationTest_SilentFlag_SuppressesOutput
+          - Cli_SilentFlag_SuppressesOutput
+        children: [ReviewMark-Context-Output]
 
       - id: ReviewMark-Cmd-Validate
         title: The tool shall support --validate flag to run self-validation tests.
@@ -66,6 +73,8 @@ sections:
           - Context_Create_ValidateFlag_SetsValidateTrue
           - Program_Run_WithValidateFlag_RunsValidation
           - IntegrationTest_ValidateFlag_RunsValidation
+          - Cli_ValidateFlag_RunsValidation
+        children: [ReviewMark-Program-Dispatch, ReviewMark-Validation-Run]
 
       - id: ReviewMark-Cmd-Results
         title: The tool shall support --results flag to write validation results in TRX or JUnit format.
@@ -75,6 +84,7 @@ sections:
           - Context_Create_ResultsFlag_SetsResultsFile
           - IntegrationTest_ValidateWithResults_GeneratesTrxFile
           - IntegrationTest_ValidateWithResults_GeneratesJUnitFile
+        children: [ReviewMark-Validation-ResultsFile]
 
       - id: ReviewMark-Cmd-Log
         title: The tool shall support --log flag to write output to a log file.
@@ -83,6 +93,7 @@ sections:
         tests:
           - Context_Create_LogFlag_OpensLogFile
           - IntegrationTest_LogFlag_WritesOutputToFile
+        children: [ReviewMark-Context-Output]
 
       - id: ReviewMark-Cmd-ErrorOutput
         title: The tool shall write error messages to stderr.
@@ -92,6 +103,7 @@ sections:
         tests:
           - Context_WriteError_NotSilent_WritesToConsole
           - IntegrationTest_UnknownArgument_ReturnsError
+        children: [ReviewMark-Context-Output]
 
       - id: ReviewMark-Cmd-InvalidArgs
         title: The tool shall reject unknown or malformed command-line arguments with a descriptive error.
@@ -103,6 +115,7 @@ sections:
           - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException
           - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException
           - IntegrationTest_UnknownArgument_ReturnsError
+        children: [ReviewMark-Context-Parsing]
 
       - id: ReviewMark-Cmd-ExitCode
         title: The tool shall return a non-zero exit code on failure.
@@ -112,6 +125,7 @@ sections:
         tests:
           - Context_WriteError_SetsErrorExitCode
           - IntegrationTest_UnknownArgument_ReturnsError
+        children: [ReviewMark-Context-Output]
 
       - id: ReviewMark-Cmd-Definition
         title: The tool shall support --definition flag to specify the definition YAML file.
@@ -123,6 +137,7 @@ sections:
           - Context_Create_DefinitionFlag_WithoutValue_ThrowsArgumentException
           - ReviewMark_ReviewPlanGeneration
           - ReviewMark_ReviewReportGeneration
+        children: [ReviewMark-Config-Loading, ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Plan
         title: The tool shall support --plan flag to write the review plan to a Markdown file.
@@ -132,6 +147,7 @@ sections:
         tests:
           - Context_Create_PlanFlag_SetsPlanFile
           - ReviewMark_ReviewPlanGeneration
+        children: [ReviewMark-Config-Reading, ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-PlanDepth
         title: The tool shall support --plan-depth flag to set the Markdown heading depth for the review plan.
@@ -143,6 +159,7 @@ sections:
           - Context_Create_PlanDepthFlag_WithInvalidValue_ThrowsArgumentException
           - Context_Create_PlanDepthFlag_WithZeroValue_ThrowsArgumentException
           - Context_Create_NoArguments_PlanDepthDefaultsToOne
+        children: [ReviewMark-Context-Parsing]
 
       - id: ReviewMark-Cmd-Report
         title: The tool shall support --report flag to write the review report to a Markdown file.
@@ -152,6 +169,7 @@ sections:
         tests:
           - Context_Create_ReportFlag_SetsReportFile
           - ReviewMark_ReviewReportGeneration
+        children: [ReviewMark-Config-Reading, ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-ReportDepth
         title: The tool shall support --report-depth flag to set the Markdown heading depth for the review report.
@@ -161,6 +179,7 @@ sections:
         tests:
           - Context_Create_ReportDepthFlag_SetsReportDepth
           - Context_Create_NoArguments_ReportDepthDefaultsToOne
+        children: [ReviewMark-Context-Parsing]
 
       - id: ReviewMark-Cmd-Index
         title: The tool shall support --index flag to scan PDF evidence files matching a glob path and write
@@ -174,6 +193,7 @@ sections:
           - Context_Create_IndexFlag_MultipleTimes_AddsAllPaths
           - Context_Create_NoArguments_IndexPathsEmpty
           - ReviewMark_IndexScan
+        children: [ReviewMark-Index-PdfParsing, ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Enforce
         title: The tool shall support --enforce flag to exit with a non-zero code when there are review issues.
@@ -185,6 +205,7 @@ sections:
           - Context_Create_EnforceFlag_SetsEnforceTrue
           - Context_Create_NoArguments_EnforceFalse
           - ReviewMark_Enforce
+        children: [ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Dir
         title: The tool shall support --dir flag to set the working directory for file operations.
@@ -197,6 +218,7 @@ sections:
           - Context_Create_NoArguments_WorkingDirectoryIsNull
           - Context_Create_DirFlag_MissingValue_ThrowsArgumentException
           - ReviewMark_WorkingDirectoryOverride
+        children: [ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Elaborate
         title: The tool shall support --elaborate <id> flag to print a Markdown elaboration of a review set.
@@ -219,6 +241,7 @@ sections:
           - Program_Run_WithElaborateFlag_OutputsElaboration
           - Program_Run_WithElaborateFlag_UnknownId_ReportsError
           - ReviewMark_Elaborate
+        children: [ReviewMark-Config-Reading, ReviewMark-Program-Dispatch]
 
       - id: ReviewMark-Cmd-Lint
         title: The tool shall support --lint flag to validate the definition file and report issues.
@@ -241,3 +264,4 @@ sections:
           - ReviewMarkConfiguration_Load_MissingEvidenceSource_ReturnsNullConfigWithErrorIssue
           - ReviewMarkConfiguration_Load_MultipleErrors_ReturnsAllIssues
           - ReviewMark_Lint
+        children: [ReviewMark-Config-Loading, ReviewMark-Program-Dispatch]

docs/reqstream/review-mark/configuration/configuration.yaml

@@ -19,6 +19,8 @@ sections:
           and generate accurate review plans.
         tests:
           - ReviewMarkConfiguration_GetNeedsReviewFiles_ReturnsMatchingFiles
+          - Configuration_LoadConfig_ResolvesNeedsReviewFiles
+        children: [ReviewMark-Config-Reading, ReviewMark-GlobMatcher-IncludeExclude]
 
       - id: ReviewMark-Configuration-Fingerprinting
         title: The tool shall compute SHA-256 fingerprints for review-sets to detect file changes.
@@ -31,6 +33,8 @@ sections:
           - ReviewSet_GetFingerprint_SameContent_ReturnsSameFingerprint
           - ReviewSet_GetFingerprint_DifferentContent_ReturnsDifferentFingerprint
           - ReviewSet_GetFingerprint_RenameFile_ReturnsSameFingerprint
+          - Configuration_LoadConfig_FingerprintReflectsFileContent
+        children: [ReviewMark-Config-Reading]
 
       - id: ReviewMark-Configuration-PlanGeneration
         title: The tool shall generate a Review Plan Markdown document listing review-set coverage.
@@ -40,6 +44,8 @@ sections:
           are included in at least one review-set before reviews are conducted.
         tests:
           - ReviewMark_ReviewPlanGeneration
+          - Configuration_LoadConfig_PlanGenerationSucceeds
+        children: [ReviewMark-Config-Reading, ReviewMark-Config-Loading]
 
       - id: ReviewMark-Configuration-ReportGeneration
         title: The tool shall generate a Review Report Markdown document showing review-set status.
@@ -49,6 +55,7 @@ sections:
           confirm that all review-sets have current evidence before a release.
         tests:
           - ReviewMark_ReviewReportGeneration
+        children: [ReviewMark-Config-Reading, ReviewMark-Config-Loading]
 
       - id: ReviewMark-Configuration-Elaboration
         title: The tool shall elaborate a review-set by providing its ID, fingerprint, and file list.
@@ -59,3 +66,4 @@ sections:
           review documentation.
         tests:
           - ReviewMark_Elaborate
+        children: [ReviewMark-Config-Reading]

docs/reqstream/review-mark/configuration/glob-matcher.yaml

@@ -27,3 +27,5 @@ sections:
           - GlobMatcher_GetMatchingFiles_NullBaseDirectory_ThrowsArgumentNullException
           - GlobMatcher_GetMatchingFiles_NullPatterns_ThrowsArgumentNullException
           - GlobMatcher_GetMatchingFiles_NoMatchingFiles_ReturnsEmptyList
+          - GlobMatcher_GetMatchingFiles_EmptyPatterns_ReturnsEmptyList
+          - GlobMatcher_GetMatchingFiles_MultipleIncludePatterns_ReturnsAllMatching

docs/reqstream/review-mark/configuration/review-mark-configuration.yaml

@@ -28,7 +28,6 @@ sections:
           - ReviewSet_GetFingerprint_SameContent_ReturnsSameFingerprint
           - ReviewSet_GetFingerprint_DifferentContent_ReturnsDifferentFingerprint
           - ReviewSet_GetFingerprint_RenameFile_ReturnsSameFingerprint
-          - ReviewMarkConfiguration_Load_NonExistentFile_ReturnsNullConfigWithErrorIssue
           - ReviewMarkConfiguration_Load_FileshareRelativeLocation_ResolvesToAbsolutePath
       - id: ReviewMark-Config-Loading
         title: ReviewMarkConfiguration.Load shall perform linting and return both the configuration and lint issues.

docs/reqstream/review-mark/indexing/indexing.yaml

@@ -26,6 +26,8 @@ sections:
           - ReviewIndex_Load_EvidenceSource_Fileshare_LoadsFromFile
           - ReviewIndex_Load_EvidenceSource_Fileshare_ValidJson_ReturnsPopulatedIndex
           - ReviewIndex_Load_EvidenceSource_Url_SuccessResponse_LoadsIndex
+          - Indexing_SafePathCombine_WithIndexPath_LoadsIndex
+        children: [ReviewMark-Index-EvidenceSource, ReviewMark-EvidenceSource-None]
 
       - id: ReviewMark-Indexing-ScanPdfEvidence
         title: The tool shall scan PDF evidence files and extract embedded review metadata to build an index.
@@ -39,6 +41,13 @@ sections:
           - ReviewIndex_Scan_MultiplePdfs_PopulatesAllEntries
           - ReviewIndex_Scan_NoMatchingFiles_LeavesIndexEmpty
           - ReviewIndex_Scan_ClearsExistingEntries
+          - ReviewIndex_Scan_PdfWithMissingId_SkipsWithWarning
+          - ReviewIndex_Scan_PdfWithMissingFingerprint_SkipsWithWarning
+          - ReviewIndex_Scan_PdfWithMissingDate_SkipsWithWarning
+          - ReviewIndex_Scan_PdfWithMissingResult_SkipsWithWarning
+          - ReviewIndex_Scan_PdfWithNoKeywords_SkipsWithWarning
+          - Indexing_ReviewIndex_SaveAndLoad_RoundTrip
+        children: [ReviewMark-Index-PdfParsing]
 
       - id: ReviewMark-Indexing-SafePathCombine
         title: The tool shall combine file paths safely, rejecting path traversal sequences.
@@ -55,3 +64,4 @@ sections:
           - PathHelpers_SafePathCombine_CurrentDirectoryReference_CombinesCorrectly
           - PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly
           - PathHelpers_SafePathCombine_EmptyRelativePath_ReturnsBasePath
+        children: [ReviewMark-PathHelpers-SafeCombine]