fix: resolve VersionMark-CommandLine-Review, VersionMark-Utilities-Review, VersionMark-Configuration-Review, VersionMark-VersionInfo-Review, and VersionMark-Validation-Review failures

[Copilot]

Pull Request

Description

Formal reviews of VersionMark-CommandLine-Review, VersionMark-Utilities-Review, VersionMark-Configuration-Review, VersionMark-VersionInfo-Review, and VersionMark-Validation-Review identified failures in requirement metadata, traceability links, documentation consistency, requirement wording, stale code documentation, missing test coverage, incomplete argument documentation, and weak test assertions. All failures are resolved; all five reviews now pass all checks.

CommandLine-Review failures fixed:

• docs/reqstream/command-line.yaml — added missing justification and tags to VersionMark-Cmd-ErrorOutput, VersionMark-Cmd-InvalidArgs, VersionMark-Cmd-ExitCode
• docs/reqstream/publish.yaml — corrected four broken test references from non-existent VersionMark_GeneratesMarkdownReport → VersionMark_PublishCommand_GeneratesMarkdownReport; linked VersionMark-Pub-GlobPattern to tests that actually exercise glob patterns (VersionMark_PublishCommandWithCustomGlobPatterns_FiltersFiles, Context_Create_GlobPatternsAfterSeparator_CapturesPatterns)
• docs/reqstream/capture.yaml — removed non-existent VersionMark_CapturesVersions reference from VersionMark-Cap-Capture
• docs/design/command-line.md — priority table had banner labelled "Priority 2", shifting all subsequent entries vs. Program.cs comments; changed banner row to — (unconditional), aligning table with code (Help=2, Validate=3, Capture=4, Publish=4.5, Default=5)
• test/DemaConsulting.VersionMark.Tests/ProgramTests.cs — Program_Run_WithVersionFlag_DisplaysVersionOnly lacked a positive assertion that a version string was printed; added assertion
• test/DemaConsulting.VersionMark.Tests/IntegrationTests.cs — IntegrationTest_SilentFlag_SuppressesOutput never verified that output was actually suppressed; added assertions that banner and copyright text do not appear in captured output

Utilities-Review failure fixed:

• docs/reqstream/formatter.yaml — VersionMark-Fmt-MarkdownList said "subscript formatting" but both MarkdownFormatter.cs (emits **tool**) and utilities.md use bold; corrected to "bold formatting"

Configuration-Review failure fixed:

• src/DemaConsulting.VersionMark/VersionMarkConfig.cs — the <remarks> XML doc-comment on the private RunCommand method was a stale artifact describing a space-splitting approach that no longer exists; corrected to accurately describe the current shell-delegation design (cmd.exe /c on Windows, /bin/sh -c elsewhere via ArgumentList)

VersionInfo-Review failures fixed:

• docs/design/version-info.md — incorrectly attributed VersionMark-Cap-DefaultOutput to VersionInfo.SaveToFile; the default output filename is determined by the CLI layer in Program.cs, not by VersionInfo; corrected to attribute only VersionMark-Cap-JsonOutput to SaveToFile and note the CLI layer's role
• test/DemaConsulting.VersionMark.Tests/VersionInfoTests.cs — added VersionInfo_LoadFromFile_NullJson_ThrowsArgumentException to cover the null-JSON deserialization guard branch (if (versionInfo == null)) in LoadFromFile which had no test

Validation-Review failures fixed:

• docs/design/validation.md — RunCaptureTest step 3 was missing --silent and --log <file> from the documented argument list; corrected to match the full argument list constructed in Validation.cs
• docs/design/validation.md — RunPublishTest step 3 was missing --silent, --log <file>, and --report-depth 2; the omission of --report-depth 2 was particularly significant as step 5 asserts ## Tool Versions (heading level 2), which is directly produced by that flag; corrected to match the full argument list constructed in Validation.cs

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.VersionMark --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint .

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

Changes are confined to requirements YAML files, design documentation, XML doc-comments in source code, and unit tests. No functional logic was modified.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

This PR updates the VersionMark requirements and design documentation to address failures reported by the VersionMark-CommandLine-Review review-set, primarily around missing requirement metadata and broken requirement→test traceability.

Changes:

• Added missing justification and tags fields for three CLI requirements in docs/reqstream/command-line.yaml.
• Fixed/removed broken test references in reqstream YAML files (publish.yaml, capture.yaml) to restore traceability.
• Aligned the command dispatch priority table in docs/design/command-line.md with the priority comments in Program.cs (treating the banner as unconditional).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/reqstream/publish.yaml	Updates requirement test references for publish-mode requirements to point at existing tests.
docs/reqstream/command-line.yaml	Adds missing justification and tags fields to maintain consistent requirement metadata.
docs/reqstream/capture.yaml	Removes a non-existent test reference from the capture requirement’s traceability list.
docs/design/command-line.md	Fixes the dispatch priority table to reflect the unconditional banner and correct priority numbering.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Malcolmnixon]

@copilot Please use the code-review agent to re-run the formal VersionMark-CommandLine-Review

[Copilot]

@copilot Please use the code-review agent to re-run the formal VersionMark-CommandLine-Review

The formal VersionMark-CommandLine-Review has been re-run. All 22 checks across all 8 review sections pass (Requirements, Documentation, Code, Testing, Req↔Doc, Req↔Implementation, Req↔Testing, Code↔Documentation). The updated report is in AGENT_REPORT_review-VersionMark-CommandLine-Review.md (excluded from git per .gitignore).

[Malcolmnixon]

@copilot Please use the code-review agent to perform the formal VersionMark-Utilities-Review review.

[Copilot]

@copilot Please use the code-review agent to perform the formal VersionMark-Utilities-Review review.

The formal VersionMark-Utilities-Review has been run. It initially found one failure (REQ-02, DOC-02, REQDOC-02, REQIMP-02) — the requirement VersionMark-Fmt-MarkdownList said "subscript formatting" but both the documentation (utilities.md) and the implementation (MarkdownFormatter.cs) use bold formatting. Fixed in commit 915c35b by correcting the requirement wording to "bold formatting". Re-running after the fix: all checks pass.

[Malcolmnixon]

@copilot Please use the code-review agent to execute the formal VersionMark-Configuration-Review review.

[Copilot]

@copilot Please use the code-review agent to execute the formal VersionMark-Configuration-Review review.

The formal VersionMark-Configuration-Review has been run. It found one failure: the <remarks> XML doc-comment on the private RunCommand method in VersionMarkConfig.cs (lines 333–336) was a stale artifact describing a space-splitting approach that no longer exists in the implementation.

Fixed in commit a2528e0 — the remarks now accurately describe the current shell-delegation design (cmd.exe /c on Windows, /bin/sh -c elsewhere via ArgumentList). All 22 checks across all 8 review sections now pass.

[Malcolmnixon]

@copilot Please use the code-review agent to execute the formal VersionMark-VersionInfo-Review review.

[Copilot]

@copilot Please use the code-review agent to execute the formal VersionMark-VersionInfo-Review review.

The formal VersionMark-VersionInfo-Review has been run. Two failures were found and fixed (commit 059b670):

1. DOC-01/DOC-02 — version-info.md incorrectly attributed VersionMark-Cap-DefaultOutput to VersionInfo.SaveToFile; the default output filename is actually determined by the CLI layer in Program.cs. Corrected to attribute only VersionMark-Cap-JsonOutput to SaveToFile and note the CLI layer's role in VersionMark-Cap-DefaultOutput.

2. TEST-02 — No test existed for the null-JSON deserialization guard (if (versionInfo == null)) in LoadFromFile. Added VersionInfo_LoadFromFile_NullJson_ThrowsArgumentException to cover this branch. All 111 tests pass across net8.0, net9.0, and net10.0.

[Malcolmnixon]

@copilot Please use the code-review agent to execute the formal review of VersionMark-Validation-Review

[Copilot]

@copilot Please use the code-review agent to execute the formal review of VersionMark-Validation-Review

The formal VersionMark-Validation-Review has been run. Two documentation failures were found and fixed (commit 5a5e641):

1. DOC-01/DOC-02 (RunCaptureTest) — step 3 was missing --silent and --log <file> from the documented argument list.

2. DOC-01/DOC-02 (RunPublishTest) — step 3 was missing --silent, --log <file>, and --report-depth 2. The --report-depth 2 omission was particularly significant as step 5 asserts ## Tool Versions (heading level 2), which is directly produced by that flag.

Both step-3 descriptions in docs/design/validation.md now include the complete argument lists, matching Validation.cs. All checks pass.

[Malcolmnixon]

@copilot Please use the code-review agent to perform all formal reviews [VersionMark-CommandLine-Review, VersionMark-Utilities-Review, VersionMark-Configuration-Review, VersionMark-VersionInfo-Review, VersionMark-Validation-Review]. I need them performed separately (one after the other) with the results reported separately for formal review documentation purposes.

[Copilot]

@copilot Please use the code-review agent to perform all formal reviews [VersionMark-CommandLine-Review, VersionMark-Utilities-Review, VersionMark-Configuration-Review, VersionMark-V...

All five formal reviews have been run separately. Here are the results:

---

1. VersionMark-CommandLine-Review — ✅ Pass (after fixes, commit 0c41e4d)

Two TEST-01 gaps found and fixed:

• Program_Run_WithVersionFlag_DisplaysVersionOnly — lacked a positive assertion that a version string was printed; added Assert.IsFalse(string.IsNullOrWhiteSpace(output)).
• IntegrationTest_SilentFlag_SuppressesOutput — never verified that output was actually suppressed; added assertions that banner/copyright text does not appear in captured output.

All 22 checks across 8 sections pass.

---

2. VersionMark-Utilities-Review — ✅ Pass (no changes required)

All 26 checks across 8 sections pass. No failures.

---

3. VersionMark-Configuration-Review — ✅ Pass (no changes required)

All 28 checks across 8 sections pass. No failures.

---

4. VersionMark-VersionInfo-Review — ✅ Pass (no changes required)

All 16 applicable checks (DOC, CODE, TEST, CODEDOC) pass. No failures.

---

5. VersionMark-Validation-Review — ✅ Pass (no changes required)

All 12 applicable checks (DOC, CODE, CODEDOC) pass. No failures.