Reorganize docs/design, docs/reqstream, and docs/user_guide into subsystem subfolders; implement --results and all YAML acceptance criteria

[Copilot]

Brings the repository into compliance with updated .github/standards for design documentation, requirements management, and file review tracking. The flat file layout in docs/design/ and docs/reqstream/ is replaced with a hierarchy that mirrors the source code subsystem structure. docs/guide/ is renamed to docs/user_guide/ with its content file renamed to introduction.md. Review-sets are updated to include the full set of requirements, design, code, and test files. All system capabilities are now captured in requirements with full traceability through design, code, and tests. The --results flag is fully implemented for the main file assertion path (not just --validate). All nine YAML acceptance criteria are fully implemented — the "Proposed: not yet implemented" disclaimer has been removed from the user guide and README.

Description

docs/design/ — subsystem subfolders

Moved subsystem and unit design docs into kebab-case subfolders; root-level files (introduction.md, system.md, program.md) remain at root:

• cli/ — cli.md, context.md
• configuration/ — configuration.md, file-assert-config.md, file-assert-data.md
• modeling/ — modeling.md, file-assert-test.md, file-assert-file.md, file-assert-rule.md
• utilities/ — utilities.md, path-helpers.md
• selftest/ — selftest.md, validation.md

docs/design/definition.yaml updated with new input-file paths.

docs/design/system.md updated to add "Configuration file path" and "Test filtering" responsibilities, and to expand the execution flow with explicit steps for --config, positional filter arguments, and --results output.

docs/design/program.md updated to name --config and context.Filters explicitly in the RunToolLogic description.

docs/design/cli/context.md updated to add ErrorCount to the properties table and design decisions.

docs/design/configuration/file-assert-config.md updated to document results serialization in the execution method and design decisions.

docs/design/modeling/file-assert-file.md updated to document Count, MinSize, and MaxSize properties and the size-enforcement execution phase.

docs/design/modeling/file-assert-rule.md updated to document FileAssertDoesNotContainRule and FileAssertDoesNotMatchRule classes and their YAML keys.

docs/design/configuration/file-assert-data.md updated to document all new DTO properties.

docs/reqstream/ — subsystem and ots subfolders

Reorganized from prefixed flat files (subsystem-*.yaml, unit-*.yaml, ots-*.yaml) into a mirrored hierarchy:

• system.yaml (renamed from fileassert-system.yaml)
• program.yaml (renamed from unit-program.yaml, top-level unit stays at root)
• cli/, configuration/, modeling/, utilities/, selftest/ subfolders for subsystem + unit YAMLs
• ots/ subfolder for all OTS dependency YAMLs
• Added new configuration/file-assert-data.yaml requirements file for the FileAssertData DTOs

requirements.yaml updated with new include paths.

System requirements added to docs/reqstream/system.yaml:

• FileAssert-System-ConfigFile — The tool shall load the YAML test suite from --config or the default path.
• FileAssert-System-Results — The tool shall write TRX or JUnit XML results when invoked with --results, covering both the --validate path and the main assertion path.
• FileAssert-System-TestFiltering — The tool shall run only tests matching the positional name/tag filters.
• FileAssert-System-MaxCountConstraint — The tool shall return a non-zero exit code when the file count exceeds the declared maximum.
• FileAssert-System-RegexRule — The tool shall apply a matches regex rule and return non-zero when content does not match.
• FileAssert-System-ExactCountConstraint — The tool shall return a non-zero exit code when the file count does not equal the declared exact count.
• FileAssert-System-FileSizeConstraints — The tool shall return a non-zero exit code when a file's size violates a min-size or max-size constraint.
• FileAssert-System-DoesNotContainRule — The tool shall return a non-zero exit code when a file contains the text specified in a does-not-contain rule.
• FileAssert-System-DoesNotContainRegexRule — The tool shall return a non-zero exit code when a file matches the pattern specified in a does-not-contain-regex rule.

Downstream requirements added to docs/reqstream/program.yaml:

• FileAssert-Program-Config — Program dispatches RunToolLogic using context.ConfigFile.
• FileAssert-Program-FilterTests — Program passes context.Filters to config.Run.

New unit and context requirements:

• FileAssert-Context-ErrorCount — The Context class shall expose a monotonically incrementing error count.
• FileAssert-FileAssertConfig-Results — The FileAssertConfig class shall write per-test pass/fail results to TRX or JUnit XML.
• FileAssert-FileAssertFile-ExactCount — The FileAssertFile class shall enforce an exact file count constraint.
• FileAssert-FileAssertFile-SizeConstraints — The FileAssertFile class shall enforce min-size and max-size per matched file.
• FileAssert-FileAssertRule-DoesNotContainRule — The FileAssertDoesNotContainRule class shall report an error when content contains the forbidden substring.
• FileAssert-FileAssertRule-DoesNotContainRegexRule — The FileAssertDoesNotMatchRule class shall report an error when content matches the forbidden pattern.

--results implementation for main assertion path

• Context.ErrorCount (Cli/Context.cs) — new internal int ErrorCount property incremented by every WriteError call.
• FileAssertConfig.Run (Configuration/FileAssertConfig.cs) — when context.ResultsFile is set, records a TestResult per test (Passed/Failed based on error count delta) and serializes to TRX or JUnit XML.

All YAML acceptance criteria now implemented

Previously five criteria were marked "Proposed: not yet implemented." All are now fully implemented:

• count — Exact file count constraint (FileAssertFile.Run enforces exact match after min/max checks)
• min-size / max-size — Per-file size enforcement using FileInfo.Length before content rules
• does-not-contain — New FileAssertDoesNotContainRule class; reports error when content contains the forbidden substring (ordinal comparison)
• does-not-contain-regex — New FileAssertDoesNotMatchRule class; reports error when content matches the forbidden pattern (compiled regex, 10-second timeout)

The "Proposed: not yet implemented" disclaimer is removed from both README.md and docs/user_guide/introduction.md. Pre-existing YAML key errors in the examples (path → pattern, count-min → min, count-max → max, contains-regex → matches, added rules: nesting) are also corrected.

docs/user_guide/ — renamed from docs/guide/

• docs/guide/ renamed to docs/user_guide/
• docs/user_guide/guide.md renamed to docs/user_guide/introduction.md
• docs/user_guide/definition.yaml updated with new resource-path and input-files paths
• README.md [link-guide] URL updated to point to docs/user_guide/introduction.md
• .github/workflows/build.yaml Pandoc and Weasyprint step paths updated to new location

.reviewmark.yaml — updated per reviewmark-usage.md standard

• Added requirements.yaml and docs/design/**/*.md to needs-review patterns
• All review-set file paths updated to match new folder structure
• FileAssert-FileAssertData: Added requirements yaml and test file references to complete the unit review-set
• Platform-Support: Added IntegrationTests.cs as test evidence proving multi-platform execution
• OTS-Dependencies: Uses docs/reqstream/ots/**/*.yaml glob pattern; no test file reference

New and updated tests

• IntegrationTest_TestFiltering_OnlyRunsMatchingTests — smoke filter skips a failing regression test
• IntegrationTest_PassingAssertions_WritesTrxWithPassedResults — verifies TRX outcome="Passed" for a passing contains assertion
• IntegrationTest_FailingAssertions_WritesJUnitWithFailedResults — verifies JUnit failures="1" for a failing contains assertion
• FileAssertConfig_Run_WithResultsFile_WritesTrxWithPassedOutcome and WritesJUnitWithFailedOutcome — unit-level equivalents
• Context_ErrorCount_IncrementsOnEachWriteError — verifies the new ErrorCount property
• IntegrationTest_MaxCountConstraint_TooManyFiles_ReturnsNonZero — max: 1 with 2 files
• IntegrationTest_RegexRule_MatchingContent_ReturnsZero and NonMatchingContent_ReturnsNonZero — matches: rule
• IntegrationTest_ExactCountConstraint_WrongCount_ReturnsNonZero — count: 1 with 2 files
• IntegrationTest_FileSizeConstraints_TooSmall_ReturnsNonZero — min-size: 10 with empty file
• IntegrationTest_FileSizeConstraints_TooLarge_ReturnsNonZero — max-size: 5 with large file
• IntegrationTest_DoesNotContainRule_ForbiddenTextPresent_ReturnsNonZero — does-not-contain: with matching file
• IntegrationTest_DoesNotContainRegexRule_ForbiddenPatternMatches_ReturnsNonZero — does-not-contain-regex: with matching file
• Unit tests in FileAssertFileTests.cs and FileAssertRuleTests.cs for all new criteria

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

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.FileAssert --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:

• All linters pass: ./lint.sh (Unix/macOS) or cmd /c lint.bat / ./lint.bat (Windows)

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

All 117 tests pass across .NET 8, 9, and 10. Source code changes are in Context.cs (new ErrorCount property), FileAssertConfig.cs (results serialization in Run), FileAssertData.cs (five new DTO properties), FileAssertFile.cs (exact count and size enforcement), and FileAssertRule.cs (two new rule classes and updated factory). Most documentation changes are performed via git mv to preserve history.

[Malcolmnixon]

@copilot There seem to be review-sets which don't contain the full set of requirements, design, code, and tests.

[Copilot]

@copilot There seem to be review-sets which don't contain the full set of requirements, design, code, and tests.

Fixed in commit 3c00da1. The three incomplete review-sets were:

1. FileAssert-FileAssertData — had only design.md and source.cs; added a new docs/reqstream/configuration/file-assert-data.yaml requirements file (also added to requirements.yaml), and referenced FileAssertConfigTests.cs, FileAssertFileTests.cs, and FileAssertRuleTests.cs as the test files that exercise the DTO classes.

2. Platform-Support — had only the requirements yaml; added IntegrationTests.cs as test evidence (it exercises version/help display to prove multi-platform execution).

3. OTS-Dependencies — had only the OTS requirements yamls; added IntegrationTests.cs as integration test evidence proving the OTS components work end-to-end.

[Copilot]

Pull request overview

Reorganizes design and requirements documentation into subsystem/unit subfolders to comply with updated .github/standards, and updates review tracking to match the new structure.

Changes:

• Restructured docs/reqstream/ into subsystem/unit/ots subfolders and updated the root requirements.yaml include list.
• Restructured docs/design/ into subsystem/unit subfolders and updated docs/design/definition.yaml input paths.
• Updated .reviewmark.yaml patterns and review-set paths to reflect the new documentation hierarchy.

Reviewed changes

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

Show a summary per file

File	Description
requirements.yaml	Updates requirement include paths to new docs/reqstream/** hierarchy.
docs/reqstream/system.yaml	Adds system-level requirements file at new standardized location/name.
docs/reqstream/program.yaml	Adds top-level unit requirements for Program at root per standards.
docs/reqstream/cli/cli.yaml	Adds Cli subsystem requirements under subsystem folder.
docs/reqstream/cli/context.yaml	Adds Context unit requirements under Cli subsystem folder.
docs/reqstream/configuration/configuration.yaml	Adds Configuration subsystem requirements under subsystem folder.
docs/reqstream/configuration/file-assert-config.yaml	Adds FileAssertConfig unit requirements under Configuration folder.
docs/reqstream/configuration/file-assert-data.yaml	Adds FileAssertData DTO unit requirements under Configuration folder.
docs/reqstream/modeling/modeling.yaml	Adds Modeling subsystem requirements under subsystem folder.
docs/reqstream/modeling/file-assert-test.yaml	Adds FileAssertTest unit requirements under Modeling folder.
docs/reqstream/modeling/file-assert-file.yaml	Adds FileAssertFile unit requirements under Modeling folder.
docs/reqstream/modeling/file-assert-rule.yaml	Adds FileAssertRule unit requirements under Modeling folder.
docs/reqstream/utilities/utilities.yaml	Adds Utilities subsystem requirements under subsystem folder.
docs/reqstream/utilities/path-helpers.yaml	Adds PathHelpers unit requirements under Utilities folder.
docs/reqstream/selftest/selftest.yaml	Adds SelfTest subsystem requirements under subsystem folder.
docs/reqstream/selftest/validation.yaml	Adds Validation unit requirements under SelfTest folder.
docs/reqstream/ots/mstest.yaml	Moves MSTest OTS requirements into ots/ folder.
docs/reqstream/ots/reqstream.yaml	Moves ReqStream OTS requirements into ots/ folder.
docs/reqstream/ots/buildmark.yaml	Moves BuildMark OTS requirements into ots/ folder.
docs/reqstream/ots/versionmark.yaml	Moves VersionMark OTS requirements into ots/ folder.
docs/reqstream/ots/sarifmark.yaml	Moves SarifMark OTS requirements into ots/ folder.
docs/reqstream/ots/sonarmark.yaml	Moves SonarMark OTS requirements into ots/ folder.
docs/reqstream/ots/reviewmark.yaml	Moves ReviewMark OTS requirements into ots/ folder.
docs/design/definition.yaml	Updates design doc build inputs to new docs/design/** hierarchy.
docs/design/cli/cli.md	Adds/moves Cli subsystem design doc into subsystem folder.
docs/design/cli/context.md	Adds/moves Context unit design doc into Cli folder.
docs/design/configuration/configuration.md	Adds/moves Configuration subsystem design doc into subsystem folder.
docs/design/configuration/file-assert-config.md	Adds/moves FileAssertConfig unit design doc into Configuration folder.
docs/design/configuration/file-assert-data.md	Adds/moves FileAssertData DTO design doc into Configuration folder.
docs/design/modeling/modeling.md	Adds/moves Modeling subsystem design doc into subsystem folder.
docs/design/modeling/file-assert-test.md	Adds/moves FileAssertTest unit design doc into Modeling folder.
docs/design/modeling/file-assert-file.md	Adds/moves FileAssertFile unit design doc into Modeling folder.
docs/design/modeling/file-assert-rule.md	Adds/moves FileAssertRule unit design doc into Modeling folder.
docs/design/utilities/utilities.md	Adds/moves Utilities subsystem design doc into subsystem folder.
docs/design/utilities/path-helpers.md	Adds/moves PathHelpers unit design doc into Utilities folder.
docs/design/selftest/selftest.md	Adds/moves SelfTest subsystem design doc into subsystem folder.
docs/design/selftest/validation.md	Adds/moves Validation unit design doc into SelfTest folder.
.reviewmark.yaml	Updates needs-review patterns and review-set paths to match new structure.

---

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

[Malcolmnixon]

@copilot The docs/guide should be docs/user_guide and its guide.md should be introduction.md - and you may need to update README.md to handle this.

[Copilot]

@copilot The docs/guide should be docs/user_guide and its guide.md should be introduction.md - and you may need to update README.md to handle this.

Done in commit 800ae22. docs/guide/ renamed to docs/user_guide/ and guide.md renamed to introduction.md. Updated references in docs/user_guide/definition.yaml, README.md ([link-guide]), and .github/workflows/build.yaml (Pandoc --defaults/--output and Weasyprint input paths).

[Malcolmnixon]

@copilot Please add the missing requirements from #14 (comment)

Note that these requirements may flow down and update other subsystem and unit requirements, and in turn may result in design, code, and test changes. Please do this additional work as necessary.

[Copilot]

@copilot Please add the missing requirements from #14 (comment)

Note that these requirements may flow down and update other subsystem ...

Done in commit 4cfe8a9. Here's what was added and why:

Three new system requirements (docs/reqstream/system.yaml):

• FileAssert-System-ConfigFile — linked to the two existing IntegrationTest_ValidConfig_* tests (both already use --config)
• FileAssert-System-Results — linked to the two existing IntegrationTest_ValidateWithResults_* tests
• FileAssert-System-TestFiltering — linked to a new IntegrationTest_TestFiltering_OnlyRunsMatchingTests test (creates a config with a passing smoke test and a failing regression test, runs with filter smoke, verifies exit code 0 because the failing test was skipped)

Two new program-level requirements (docs/reqstream/program.yaml) to complete the traceability chain from system → program:

• FileAssert-Program-Config — Program dispatches to RunToolLogic using context.ConfigFile
• FileAssert-Program-FilterTests — Program passes context.Filters to config.Run

Design document updates:

• docs/design/system.md — added "Configuration file path" and "Test filtering" rows to the responsibilities table; expanded execution flow steps 3 and 5 to name --config and context.Filters explicitly, and added step 10 for --results
• docs/design/program.md — updated RunToolLogic description to name --config and context.Filters

All 95 tests pass across .NET 8/9/10; all linters pass.

[Malcolmnixon]

@copilot So given this, do you feel confident the tool actually implements the functionality it tells the user is available? How well is this functionality demonstrated in integration tests? Do we actually test by producing files, running .fileassert.yaml checks, and verifying the TRX/JUnit result files contain the expected pass/fail results?

[Copilot]

Pull request overview

Copilot reviewed 12 out of 46 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

.github/workflows/build.yaml:1

• The workflow now references docs/user_guide/definition.yaml, but the changes shown include an update to docs/guide/definition.yaml (old path). If the file wasn’t actually moved/renamed to docs/user_guide/definition.yaml, this workflow step will fail at runtime. Align the repo paths by either renaming/moving the defaults file to docs/user_guide/definition.yaml or updating the workflow to point at the actual file location.

---

requirements.yaml:1

• The root requirements.yaml now includes docs/reqstream/system.yaml and docs/reqstream/program.yaml, but the diffs shown add new requirements to docs/reqstream/fileassert-system.yaml and docs/reqstream/unit-program.yaml. If those files were not actually renamed/moved to match system.yaml/program.yaml, the requirements aggregation will miss the updated content (or fail if the new paths don’t exist). Ensure the physical file names/paths match the includes, or update the includes to match the actual files.
  test/DemaConsulting.FileAssert.Tests/IntegrationTests.cs:1
• This test only asserts the exit code. It can become a false positive if the tool exits 0 for other reasons (e.g., test discovery failure, config not loaded, or filters being ignored but failures not surfaced). Strengthen the assertion by capturing the tool output and verifying that the smoke test is reported as executed while the regression test (or missing.txt) is not mentioned, or by asserting an expected run-count/summary if the CLI emits one.

---

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

[Copilot]

@copilot So given this, do you feel confident the tool actually implements the functionality it tells the user is available? How well is this functionality demonstrated in integration tests? Do we act...

The review identified a real gap, now fixed in commit a7a9e00.

What was missing: The user guide (and system requirements added in the previous commit) documented fileassert --results results.trx working for normal file assertions, but --results was only implemented in Validation.Run. The main RunToolLogic path never wrote any results file at all.

What was implemented:

• Context.ErrorCount — a monotonically incrementing counter, incremented by every WriteError call. This lets FileAssertConfig.Run snapshot the count before each test and compare afterwards to determine per-test pass/fail without needing a separate context per test.
• FileAssertConfig.Run — when context.ResultsFile is set, it now creates a TestResults collection, records a TestResult for each executed test (with Passed or Failed outcome based on the error count delta), and serializes to TRX (.trx) or JUnit XML (.xml) after all tests complete.

End-to-end tests that create actual files and verify result file content:

• IntegrationTest_PassingAssertions_WritesTrxWithPassedResults — creates a sample.txt containing "Copyright", runs a LicenseCheck assertion against it, then checks that the TRX file contains LicenseCheck and outcome="Passed".
• IntegrationTest_FailingAssertions_WritesJUnitWithFailedResults — creates a sample.txt without "Copyright", runs the same assertion, then checks that the JUnit XML contains LicenseCheck and failures="1".
• Two matching unit tests in FileAssertConfigTests.cs exercise the same logic at the unit level.

All 100 tests pass across .NET 8/9/10.

[Malcolmnixon]

@copilot Are there system requirements and integration tests for all types of acceptance criteria identified in the README.md?

[Copilot]

@copilot Are there system requirements and integration tests for all types of acceptance criteria identified in the README.md?

Addressed in commit 6168cbe.

The README lists 9 acceptance criteria in the YAML format table (under the "Proposed" disclaimer). Of those, 4 are currently implemented in code:

Criterion	YAML key	System requirement	Integration test
Min count	min	FileAssert-System-CoreExecution (uses min: 1)	✅ already existed
Max count	max	missing	missing
Contains rule	contains	FileAssert-System-CoreExecution + FailureDetection	✅ already existed
Regex/matches rule	matches	missing	missing

The remaining 5 criteria (count exact, min-size, max-size, does-not-contain, does-not-contain-regex) are not yet implemented in code — the README correctly marks them "Proposed: not yet implemented."

Added for the two missing ones:

• FileAssert-System-MaxCountConstraint requirement + IntegrationTest_MaxCountConstraint_TooManyFiles_ReturnsNonZero (creates 2 files, config asserts max: 1, verifies non-zero exit)
• FileAssert-System-RegexRule requirement + IntegrationTest_RegexRule_MatchingContent_ReturnsZero and IntegrationTest_RegexRule_NonMatchingContent_ReturnsNonZero (creates files with/without a semver string, uses matches: "\\d+\\.\\d+\\.\\d+", verifies expected exit codes)

[Malcolmnixon]

@copilot I want you to implement them - that means removing the "Proposed: not yet implemented." and actually putting in requirements (flowing down from system to subsystem to unit, then doing the design, then the code, then the tests (system, subsystem, and unit).

[Copilot]

@copilot I want you to implement them - that means removing the "Proposed: not yet implemented." and actually putting in requirements (flowing down from system to subsystem to unit, then doing the des...

Done in commit f1354c4. All 5 remaining criteria are now fully implemented end-to-end:

Criterion	YAML key	New code
Exact count	count:	FileAssertFile.Run enforces exact match after min/max
Min file size	min-size:	Per-file FileInfo.Length check in FileAssertFile.Run
Max file size	max-size:	Per-file FileInfo.Length check in FileAssertFile.Run
Does not contain	does-not-contain:	New FileAssertDoesNotContainRule class
Does not contain regex	does-not-contain-regex:	New FileAssertDoesNotMatchRule class

Each criterion has the full traceability chain:

• System requirement (system.yaml) → unit requirement (file-assert-file.yaml or file-assert-rule.yaml)
• Design doc updates (file-assert-file.md, file-assert-rule.md, file-assert-data.md)
• Unit tests (3 new in FileAssertFileTests.cs, 6 new in FileAssertRuleTests.cs)
• Integration tests (5 new end-to-end in IntegrationTests.cs)

The "Proposed: not yet implemented" disclaimer is removed from both README.md and docs/user_guide/introduction.md. The YAML examples were also corrected (wrong key names like path → pattern, count-min → min, contains-regex → matches, added rules: nesting) so the documentation matches the actual implementation. All 117 tests pass.