Add ASCII-art architecture tree to introduction.md, restructure requirements files, restructure design docs, update reviewmark.yaml, audit requirement-test linkages, and fix requirement IDs and build-docs ordering

[Copilot]

Pull Request

Description

Adds a software architecture tree to docs/design/introduction.md, restructures all requirements files in docs/reqstream/ to follow the standard naming convention, splits all design documents into discrete per-subsystem and per-unit files, rewrites .reviewmark.yaml with complete per-unit, per-subsystem, and special review sets, audits all requirement-to-test linkages to confirm every test actually proves its requirement, expands all abbreviated requirement IDs to full readable names, fixes a requirement justification to match actual silent-mode behavior, and reorders the build-docs CI steps so all Pandoc jobs are grouped before all Weasyprint jobs.

docs/design/introduction.md

• Added Software Architecture section with a fully hierarchical ASCII-art tree. Every subsystem contains its units, and each node has a short 2–4 word description of its role:

VersionMark (Software System)               Version capture/publish tool
├── Command-Line Interface Subsystem        Argument parsing and dispatch
│   ├── Program (Software Unit)             Tool entry point
│   └── Context (Software Unit)             Command-line state container
├── Configuration Subsystem                 YAML configuration loading
│   ├── VersionMarkConfig (Software Unit)   Top-level config container
│   └── ToolConfig (Software Unit)          Per-tool config record
├── Capture Subsystem                       Tool version capture
│   └── VersionInfo (Software Unit)         JSON version data record
├── Publish Subsystem                       Markdown report publishing
│   └── MarkdownFormatter (Software Unit)   Version report formatter
├── Lint Subsystem                          Configuration file lint
│   └── Lint (Software Unit)                YAML configuration validator
└── Validation Subsystem                    Built-in self-validation
    ├── Validation (Software Unit)          Self-validation runner
    └── PathHelpers (Software Unit)         Safe path combination

• Updated Scope section to describe the six subsystems rather than five legacy "layers".

docs/design/ — design documents split into discrete subsystem and unit files

Each former monolithic design file has been split so that every review set references exactly one unique design file:

• command-line.md → subsystem-command-line.md + unit-program.md + unit-context.md
• configuration.md → subsystem-configuration.md + unit-version-mark-config.md + unit-tool-config.md
• capture.md → subsystem-capture.md + unit-version-info.md
• publish.md → subsystem-publish.md + unit-markdown-formatter.md
• lint.md → subsystem-lint.md + unit-lint.md
• validation.md → subsystem-validation.md + unit-validation.md + unit-path-helpers.md
• New: system.md — system-level design covering operational modes, typical workflow, system boundaries, and inter-subsystem interactions
• Removed: utilities.md and version-info.md — content redistributed into the correct subsystem and unit design files
• Updated: definition.yaml — lists all 17 discrete design files (2 intro/system + 6 subsystem + 9 unit)
• Fixed: subsystem-capture.md wording updated to correctly describe the Capture Subsystem as responsible for persisting JSON output (produced by VersionMarkConfig.FindVersions), not for executing commands

docs/reqstream/ — requirements files restructured

• New: versionmark-system.yaml — high-level user requirements (capture, publish, lint, validate)
• New: subsystem-validation.yaml — subsystem-level requirements for the Validation Subsystem
• Renamed: platform.yaml → platform-requirements.yaml
• Renamed: command-line.yaml, capture.yaml, publish.yaml, configuration.yaml, lint.yaml → subsystem-*.yaml
• Renamed: formatter.yaml → unit-formatter.yaml
• New unit files: unit-program.yaml, unit-context.yaml, unit-lint.yaml, unit-version-mark-config.yaml, unit-tool-config.yaml, unit-version-info.yaml, unit-path-helpers.yaml, unit-validation.yaml — requirements linked to existing tests
• Split: ots-software.yaml → individual ots-mstest.yaml, ots-reqstream.yaml, ots-buildmark.yaml, ots-sarifmark.yaml, ots-sonarmark.yaml, ots-reviewmark.yaml
• Fixed: Requirement IDs no longer use abbreviated/contracted segment names. All subsystem-level ID segments have been expanded: Cap → Capture, Cfg → Configuration, Cmd → CommandLine, Fmt → Formatter, Plt → Platform, Pub → Publish, Sys → System, Val → Validate (verb form, to avoid collision with VersionMark-Validation-* unit-level IDs). All references in design markdown files updated accordingly.
• Fixed: VersionMark-Capture-MultipleTools requirement was linked to a test that specifies an explicit tool filter, contradicting the "no tool names specified" scenario; the link has been updated to the new Program_Run_WithCaptureCommandNoToolFilter_CapturesAllConfiguredTools test
• Fixed: VersionMark-Context-WriteError justification updated to accurately state that silent mode suppresses all console output including errors, while the process still exits with a non-zero code

requirements.yaml

• Updated includes list to reference all 23 renamed/new requirement files, with each unit file grouped immediately after its parent subsystem file.

.reviewmark.yaml — review sets rewritten

• Special sets:
  • VersionMark-System — system requirements, platform requirements, introduction.md, system.md, IntegrationTests.cs, AssemblyInfo.cs, Runner.cs
  • VersionMark-Design — system requirements and all design markdowns
  • VersionMark-AllRequirements — requirements.yaml and all requirement files
• Per-subsystem sets (requirements + subsystem design file + associated tests) for all six subsystems
• Per-unit sets (requirements + unit design file + code + tests) for all nine units: Program, Context, VersionMarkConfig, ToolConfig, VersionInfo, MarkdownFormatter, Lint, Validation, PathHelpers
• Each design file appears in at most two review sets: its specific unit/subsystem set and VersionMark-Design; no design file is shared across multiple unit review sets

.github/workflows/build.yaml — build-docs step ordering fixed

• All eight Pandoc HTML generation steps are now grouped together under # === GENERATE HTML DOCUMENTS WITH PANDOC ===
• All eight Weasyprint PDF generation steps follow under # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
• Previously the Pandoc and Weasyprint steps were interleaved document-by-document

test/DemaConsulting.VersionMark.Tests/ProgramTests.cs

• New test: Program_Run_WithCaptureCommandNoToolFilter_CapturesAllConfiguredTools — creates a two-tool config (dotnet + git), runs capture without specifying any tool names, and asserts both tools are captured; proves VersionMark-Capture-MultipleTools

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

All new unit requirement files link to pre-existing passing tests. The OTS split is content-identical to the removed ots-software.yaml; requirement IDs are unchanged, so existing traceability is preserved. The subsystem-validation.yaml requirements file was added to cover the new Validation Subsystem.

A full audit of all requirement-to-test linkages was performed. All linkages were confirmed sound except VersionMark-Capture-MultipleTools, which was previously linked to IntegrationTest_CaptureCommandWithDefaultOutput_UsesDefaultFilename — a test that explicitly passes -- dotnet as a tool filter, directly contradicting the "no tool names specified" scenario. A new test was added to provide proper coverage and the requirement link was updated accordingly.

Requirement IDs that previously used abbreviated segment names (e.g., Cap, Cfg, Cmd) have been expanded to full readable names across all reqstream YAML files and design markdown documents. The Val abbreviation was expanded to Validate (verb form) rather than Validation to avoid collision with the existing VersionMark-Validation-* unit-level requirement IDs.

---

⚡ Quickly spin up Copilot coding agent tasks from anywhere on your macOS or Windows machine with Raycast.

[Malcolmnixon]

@copilot Excellent - the tree now looks good, but it's listing yaml requirement files - it should be having a short 2-4 word description of each item in the tree.

Now that we've correctly identified all subsystems and units, can you examine the design files and make sure they match this list; and can you check the .reviewmark.yaml review-sets. Each software unit MUST be reviewed with its requirements/design/code/tests. Each software subsystem must have its requirements and design reviewed, and any associated tests.

There also need to be some special review-sets:

• VersionMark-System (system-requirements, platform-requirements, introduction.md, system.md, IntegrationTests.cs, AssemblyInfo.cs, Runner.cs)
• VersionMark-Design (system-requirements, all design markdowns)
• VersionMark-AllRequirements (requirements.yaml, and all requirement files)

[Copilot]

@copilot Excellent - the tree now looks good, but it's listing yaml requirement files - it should be having a short 2-4 word description of each item in the tree.

Now that we've c...

Done in commit d9a297a. Here's a summary of everything addressed:

ASCII-art tree — YAML filenames replaced with 2–4 word descriptions:

VersionMark (Software System)               Version capture/publish tool
├── Command-Line Interface Subsystem        Argument parsing and dispatch
│   ├── Program (Software Unit)             Tool entry point
│   └── Context (Software Unit)             Command-line state container
├── Configuration Subsystem                 YAML configuration loading
│   ├── VersionMarkConfig (Software Unit)   Top-level config container
│   └── ToolConfig (Software Unit)          Per-tool config record
├── Capture Subsystem                       Tool version capture
│   └── VersionInfo (Software Unit)         JSON version data record
├── Publish Subsystem                       Markdown report publishing
│   └── MarkdownFormatter (Software Unit)   Version report formatter
├── Lint Subsystem                          Configuration file lint
│   └── Lint (Software Unit)                YAML configuration validator
└── Validation Subsystem                    Built-in self-validation
    ├── Validation (Software Unit)          Self-validation runner
    └── PathHelpers (Software Unit)         Safe path combination

Design files restructured to match the subsystem/unit list:

• New system.md — system-level design (workflow, boundaries, inter-subsystem interactions)
• utilities.md → publish.md (Publish Subsystem: MarkdownFormatter)
• version-info.md → capture.md (Capture Subsystem: VersionInfo)
• validation.md updated to include PathHelpers as a unit of the Validation Subsystem
• lint.md added to definition.yaml (was missing)
• definition.yaml updated: adds system.md, capture.md, publish.md, lint.md

.reviewmark.yaml rewritten with:

• Special sets: VersionMark-System, VersionMark-Design, VersionMark-AllRequirements
• Per-subsystem sets (requirements + design + associated tests): VersionMark-CommandLine-Subsystem, VersionMark-Configuration-Subsystem, VersionMark-Capture-Subsystem, VersionMark-Publish-Subsystem, VersionMark-Lint-Subsystem, VersionMark-Validation-Subsystem
• Per-unit sets (requirements + design + code + tests): VersionMark-Program-Review, VersionMark-Context-Review, VersionMark-VersionMarkConfig-Review, VersionMark-ToolConfig-Review, VersionMark-VersionInfo-Review, VersionMark-MarkdownFormatter-Review, VersionMark-Lint-Review, VersionMark-Validation-Review, VersionMark-PathHelpers-Review

[Malcolmnixon]

@copilot I don't think you've split the design markdown files into discrete unit and subsystem files. I'm seeing configuration.md added to three different review-sets.

[Copilot]

@copilot I don't think you've split the design markdown files into discrete unit and subsystem files. I'm seeing configuration.md added to three different review-sets.

Done in commit a38bf58. Each design file has been split into discrete files per subsystem and unit:

• command-line.md → subsystem-command-line.md + unit-program.md + unit-context.md
• configuration.md → subsystem-configuration.md + unit-version-mark-config.md + unit-tool-config.md
• capture.md → subsystem-capture.md + unit-version-info.md
• publish.md → subsystem-publish.md + unit-markdown-formatter.md
• lint.md → subsystem-lint.md + unit-lint.md
• validation.md → subsystem-validation.md + unit-validation.md + unit-path-helpers.md

Each file now appears in at most two review sets — once in VersionMark-Design (the all-design review) and once in its specific subsystem or unit review set. No design file is shared across multiple unit review sets. definition.yaml was also updated with the new file list.

[Malcolmnixon]

@copilot The build-docs steps aren't in the correct order. There's a block "# === GENERATE HTML DOCUMENTS WITH PANDOC ===" which is supposed to have all the pandoc jobs after it, then later there's a "# === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===" which is supposed to have all the weasyprint jobs after it... however the pandoc and weasyprint jobs are intertwined.

[Copilot]

@copilot Please compare all requirements to the tests they link to, and confirm the tests are actually proving the requirement.

Audit complete. I reviewed all requirements files against their linked test methods. All linkages were sound with one exception:

VersionMark-Cap-MultipleTools ("The tool shall capture all tools defined in configuration when no tool names are specified") was linked to IntegrationTest_CaptureCommandWithDefaultOutput_UsesDefaultFilename, which actually passes -- dotnet as a tool filter — directly contradicting the "no tool names specified" scenario the requirement describes.

Fixed in commit 029ec45: added Program_Run_WithCaptureCommandNoToolFilter_CapturesAllConfiguredTools to ProgramTests.cs. The test creates a two-tool config (dotnet + git), runs capture without specifying any tool names, and asserts both tools are present in the output. subsystem-capture.yaml updated to link VersionMark-Cap-MultipleTools to this test instead.

All 141 tests pass across net8.0, net9.0, and net10.0.

[Malcolmnixon]

@copilot I'm seeing a requirement with a three-letter-acronym "Cap" in the middle - please change the semantic IDs not to use contractions - they should be short, but also clear to understand.

[Copilot]

@copilot apply changes based on the comments in this thread

The wording suggested in that review thread was already applied in a previous commit — subsystem-capture.md currently reads exactly as the reviewer suggested (the subsystem persists JSON written by VersionMarkConfig.FindVersions, not the one that executes commands). No further change needed.

@copilot The build-docs steps aren't in the correct order. There's a block "# === GENERATE HTML DOCUMENTS WITH PANDOC ===" which is supposed to have all the pandoc jobs after it, then later there's a ...

Fixed in commit 1e80d20. All eight Pandoc HTML generation steps are now grouped together under # === GENERATE HTML DOCUMENTS WITH PANDOC ===, followed by all eight Weasyprint PDF generation steps under # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===.

@copilot I'm seeing a requirement with a three-letter-acronym "Cap" in the middle - please change the semantic IDs not to use contractions - they should be short, but also clear to understand.

Fixed in commit 1e80d20. All abbreviated/contracted segment names have been expanded across every reqstream YAML file and design markdown doc:

• Cap → Capture
• Cfg → Configuration
• Cmd → CommandLine
• Fmt → Formatter
• Plt → Platform
• Pub → Publish
• Sys → System
• Val → Validate (verb form, to avoid collision with VersionMark-Validation-* unit-level IDs)