Add root-tags orphan detection and close CLI traceability gap

.config/dotnet-tools.json

@@ -33,7 +33,7 @@
       ]
     },
     "demaconsulting.reqstream": {
-      "version": "1.10.0",
+      "version": "1.11.0",
       "commands": [
         "reqstream"
       ]

docs/reqstream/quality.yaml

@@ -0,0 +1,176 @@
+---
+# Repository quality requirements
+#
+# These requirements express repository/process-level quality outcomes that are
+# satisfied through the CI pipeline's use of off-the-shelf compliance and
+# documentation tools. They are distinct from the VersionMark product requirements
+# in version-mark.yaml: each requirement here states WHAT quality outcome the
+# repository needs (e.g. "changes are peer reviewed"), never HOW that outcome is
+# currently achieved. The OTS tool that currently satisfies each outcome is
+# recorded only as a `children` link, never in the requirement title or
+# justification, so that satisfying the outcome by different or additional means
+# in the future would not require rewriting the requirement itself.
+sections:
+  - title: Repository Quality Requirements
+    requirements:
+      - id: VersionMark-Quality-BuildIntegrity
+        title: >-
+          Every release shall carry a documented record of the CI build that
+          produced it, captured automatically from pipeline metadata.
+        justification: |
+          Regulated and quality-conscious consumers of VersionMark require assurance that
+          each release artifact was produced by a specific, auditable build rather than
+          an ad-hoc or undocumented process. Capturing build provenance (workflow run
+          identity, commit, timestamp) automatically as part of the CI pipeline, rather
+          than relying on manual record-keeping, ensures the record is always present,
+          accurate, and resistant to after-the-fact tampering.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-BuildMark
+        tests:
+          - BuildMark_MarkdownReportGeneration
+
+      - id: VersionMark-Quality-StaticAnalysis
+        title: >-
+          Code shall be automatically scanned for defects, vulnerabilities, and
+          quality regressions before merge.
+        justification: |
+          Manual code review alone cannot reliably catch every security vulnerability,
+          code smell, or quality regression introduced by a change. Automated static
+          analysis on every pull request, with results captured as auditable reports,
+          provides continuous, objective quality and security assurance that scales
+          with the size of the codebase and does not depend solely on reviewer
+          attentiveness.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-SarifMark
+          - VersionMark-OTS-SonarMark
+        tests:
+          - SarifMark_SarifReading
+          - SarifMark_MarkdownReportGeneration
+          - SonarMark_QualityGateRetrieval
+          - SonarMark_IssuesRetrieval
+
+      - id: VersionMark-Quality-PeerReview
+        title: >-
+          Every change shall receive documented, enforced peer review evidence
+          before merge.
+        justification: |
+          Peer review is a core defense against defects and unintended behavior
+          reaching production, but review activity that is not tracked cannot be
+          audited or enforced. Generating a review plan identifying the reviews
+          required for a change, and a review report documenting the reviews actually
+          completed, provides objective, auditable evidence that the review process
+          was followed, supporting compliance and quality assurance activities.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-ReviewMark-PlanGeneration
+          - VersionMark-OTS-ReviewMark-ReportGeneration
+        tests:
+          - ReviewMark_ReviewPlanGeneration
+          - ReviewMark_ReviewReportGeneration
+
+      - id: VersionMark-Quality-DocumentationGeneration
+        title: >-
+          Repository documentation shall be generated in reviewable and
+          distributable formats and validated before release.
+        justification: |
+          Design, verification, review, and user-guide documentation authored in
+          Markdown must be converted into distributable formats (HTML for review,
+          PDF for archival and distribution) as part of the release pipeline, and
+          each generated document must be validated to confirm it exists, is
+          well-formed, and contains the expected content, so that a broken
+          conversion step cannot silently ship incomplete or corrupt compliance
+          documentation.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-Pandoc
+          - VersionMark-OTS-WeasyPrint
+          - VersionMark-OTS-FileAssert
+        tests:
+          - Pandoc_BuildNotesHtml
+          - Pandoc_CodeQualityHtml
+          - WeasyPrint_BuildNotesPdf
+          - WeasyPrint_CodeQualityPdf
+          - FileAssert_VersionDisplay
+          - FileAssert_HelpDisplay
+
+      - id: VersionMark-Quality-TestInfrastructure
+        title: >-
+          The project's own developer test suite shall execute automatically
+          and report results in every CI run.
+        justification: |
+          Requirements traceability depends on evidence that tests actually executed
+          and passed; that evidence has no value unless the test framework reliably
+          discovers, runs, and reports every test method on every CI run, across all
+          supported platforms and .NET versions, without manual intervention.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-xUnit
+        tests:
+          - Context_Create_NoArguments_ReturnsDefaultContext
+          - Context_Create_VersionFlag_SetsVersionTrue
+          - Context_Create_HelpFlag_SetsHelpTrue
+          - Context_Create_SilentFlag_SetsSilentTrue
+          - Context_Create_ValidateFlag_SetsValidateTrue
+          - Context_Create_ResultsFlag_SetsResultsFile
+          - Context_Create_LogFlag_OpensLogFile
+          - Context_Create_UnknownArgument_ThrowsArgumentException
+          - Context_Create_ShortVersionFlag_SetsVersionTrue
+
+      - id: VersionMark-Quality-RequirementsTraceability
+        title: >-
+          Every requirement shall be linked to passing tests and enforced as part
+          of the release pipeline.
+        justification: |
+          Requirements that are not linked to verifying tests, or whose tests are not
+          checked as part of the pipeline, provide no real assurance that the software
+          behaves as documented. Automatically enforcing requirements-to-test
+          traceability on every CI run ensures untested or orphaned requirements are
+          caught before release rather than discovered later.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-ReqStream
+        tests:
+          - ReqStream_EnforcementMode
+
+      - id: VersionMark-Quality-ArchitectureTraceability
+        title: >-
+          The project's software structure shall be modeled, validated, and
+          rendered independent of source code, so its architecture can be
+          queried and reviewed without reading implementation.
+        justification: |
+          Reviewers, auditors, and automated agents need to understand system
+          structure and responsibilities without reading through source code line by
+          line. Maintaining an explicit architecture model that is automatically
+          validated for structural correctness and rendered as diagrams embedded in
+          design documentation ensures the documented architecture remains
+          internally consistent and stays usable as a standalone reference.
+          This requirement is satisfied by its children: it is a non-atomic (grouping)
+          requirement, and verification evidence is carried by each atomic child
+          requirement's tests.
+        tags: [quality]
+        children:
+          - VersionMark-OTS-SysML2Tools-Lint
+          - VersionMark-OTS-SysML2Tools-Render
+        tests:
+          - SysML2Tools_LintSelfTest
+          - SysML2Tools_RenderSvgSelfTest

docs/reqstream/version-mark.yaml

@@ -8,6 +8,7 @@ sections:
           The primary purpose of VersionMark is to record which tool versions were
           present in each CI/CD job so that version differences across environments
           can be detected and reported.
+        tags: [system]
         children:
           - VersionMark-Capture-Capture
           - VersionMark-Capture-JobId
@@ -23,6 +24,7 @@ sections:
           - VersionMark-Capture-ConfigError
           - VersionMark-Capture-CommandFailure
           - VersionMark-VersionMarkConfig-FindVersions
+          - VersionMark-Program-RunCapture
         tests:
           - IntegrationTest_CaptureCommand_CapturesToolVersions
 
@@ -33,6 +35,7 @@ sections:
           Teams need a human-readable summary of tool versions across all jobs.
           Publishing to markdown enables the report to be included in release
           documentation and artifact archives.
+        tags: [system]
         children:
           - VersionMark-Publish-Publish
           - VersionMark-Publish-Report
@@ -43,6 +46,7 @@ sections:
           - VersionMark-Publish-ConflictReport
           - VersionMark-Publish-ConflictDisplay
           - VersionMark-Publish-FileError
+          - VersionMark-Program-RunPublish
         tests:
           - VersionMark_PublishCommand_GeneratesMarkdownReport
 
@@ -53,6 +57,7 @@ sections:
           Detecting configuration errors early, before a CI/CD run proceeds, reduces
           wasted build time and provides precise error locations so users can fix
           problems quickly.
+        tags: [system]
         children:
           - VersionMark-Load-FileExistence
           - VersionMark-Load-YamlParsing
@@ -72,6 +77,10 @@ sections:
           - VersionMark-Load-VersionMarkLoadResult-Bundle
           - VersionMark-Load-VersionMarkLoadResult-ErrorRouting
           - VersionMark-Load-VersionMarkLoadResult-WarnRouting
+          - VersionMark-Load-LintIssue-Fields
+          - VersionMark-Load-LintIssue-Format
+          - VersionMark-CommandLine-Lint
+          - VersionMark-Program-RunLint
         tests:
           - IntegrationTest_LintFlag_ValidConfig_ReturnsSuccess
           - IntegrationTest_LintFlag_InvalidConfig_ReturnsError
@@ -82,11 +91,51 @@ sections:
           A built-in self-validation suite lets operators confirm that the installed
           tool is functioning correctly in the deployment environment without
           requiring external fixtures or test data.
+        tags: [system]
         children:
           - VersionMark-Validate-Capture
           - VersionMark-Validate-Publish
           - VersionMark-Validate-LintValid
           - VersionMark-Validate-LintInvalid
           - VersionMark-Validate-Results
+          - VersionMark-CommandLine-Validate
+          - VersionMark-CommandLine-Results
+          - VersionMark-OTS-TestResults
         tests:
           - IntegrationTest_ValidateFlag_RunsValidation
+
+      - id: VersionMark-System-CommandLine
+        title: >-
+          The tool shall provide a consistent command-line interface across all
+          invocations, including flags to display version and help information,
+          suppress console output, write a log file, and report errors for
+          unrecognized arguments.
+        justification: |
+          Every DEMA Consulting DotNet Tool exposes the same baseline command-line
+          conventions so users and CI/CD scripts can rely on predictable behavior
+          for version display, usage help, output verbosity, logging, and error
+          reporting regardless of which specific capture, publish, or lint
+          operation is invoked.
+        tags: [system]
+        children:
+          - VersionMark-CommandLine-Context
+          - VersionMark-CommandLine-Version
+          - VersionMark-CommandLine-Help
+          - VersionMark-CommandLine-Silent
+          - VersionMark-CommandLine-Log
+          - VersionMark-CommandLine-ErrorOutput
+          - VersionMark-CommandLine-InvalidArgs
+          - VersionMark-CommandLine-ExitCode
+          - VersionMark-Program-Version
+          - VersionMark-Program-Dispatch
+          - VersionMark-Context-Create
+          - VersionMark-Context-WriteLine
+          - VersionMark-Context-WriteError
+          - VersionMark-Context-WriteErrorLog
+          - VersionMark-Context-WriteErrorExitCode
+        tests:
+          - Cli_Run_VersionFlag_ExitsCleanly
+          - Cli_Run_HelpFlag_DisplaysUsageInformation
+          - Cli_Run_SilentWithVersionFlag_SuppressesOutput
+          - Cli_Run_LogFlag_WritesOutputToLogFile
+          - Cli_Run_InvalidArgs_ThrowsArgumentException

docs/reqstream/version-mark/capture.yaml

@@ -46,6 +46,8 @@ sections:
               enabling integration with existing workflows and file structures.
             tags:
               - capture
+            children:
+              - VersionMark-Utilities-SafePath
             tests:
               - Capture_Run_NoToolFilter_CapturesAllConfiguredTools
 
@@ -90,6 +92,14 @@ sections:
               capture and how to capture them.
             tags:
               - capture
+            children:
+              - VersionMark-Configuration-YamlConfig
+              - VersionMark-Configuration-ToolDefinition
+              - VersionMark-Configuration-OsCommandOverride
+              - VersionMark-Configuration-OsRegexOverride
+              - VersionMark-Configuration-ValidateTools
+              - VersionMark-Configuration-ReadError
+              - VersionMark-Configuration-ParseError
             tests:
               - Capture_Config_ReadFromFile_LoadsToolDefinitions
 
@@ -114,6 +124,7 @@ sections:
               - capture
             children:
               - VersionMark-VersionInfo-Save
+              - VersionMark-VersionInfo-WriteError
             tests:
               - Capture_SaveAndLoad_PreservesAllVersionData
               - Capture_MultipleCaptures_EachFileHasDistinctJobId

docs/reqstream/version-mark/configuration.yaml

@@ -14,6 +14,7 @@ sections:
             children:
               - VersionMark-VersionMarkConfig-ReadFromFile
               - VersionMark-VersionMarkConfig-Load
+              - VersionMark-OTS-YamlDotNet
             tests:
               - Configuration_ReadFromFile_MultipleTools_AllToolsAccessible
 

docs/reqstream/version-mark/platform-requirements.yaml

@@ -10,6 +10,7 @@ sections:
               DEMA Consulting tools must support Windows as a major development platform.
             tags:
               - platform
+              - system
             tests:
               # Tests link to "windows" to ensure results come from Windows platform
               - "windows@VersionMark_CapturesVersions"
@@ -21,6 +22,7 @@ sections:
               DEMA Consulting tools must support Linux for CI/CD and containerized environments.
             tags:
               - platform
+              - system
             tests:
               # Tests link to "ubuntu" to ensure results come from Linux platform
               - "ubuntu@VersionMark_CapturesVersions"
@@ -33,6 +35,7 @@ sections:
               and macOS CI/CD runners.
             tags:
               - platform
+              - system
             tests:
               # Tests link to "macos" to ensure results come from macOS platform
               - "macos@VersionMark_CapturesVersions"
@@ -44,6 +47,7 @@ sections:
               .NET 8 is an LTS release providing long-term stability for enterprise users.
             tags:
               - platform
+              - system
             tests:
               - "dotnet8.x@VersionMark_CapturesVersions"
               - "dotnet8.x@VersionMark_GeneratesMarkdownReport"
@@ -54,6 +58,7 @@ sections:
               .NET 9 support enables users to leverage the latest .NET features.
             tags:
               - platform
+              - system
             tests:
               - "dotnet9.x@VersionMark_CapturesVersions"
               - "dotnet9.x@VersionMark_GeneratesMarkdownReport"
@@ -64,6 +69,7 @@ sections:
               .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem.
             tags:
               - platform
+              - system
             tests:
               - "dotnet10.x@VersionMark_CapturesVersions"
               - "dotnet10.x@VersionMark_GeneratesMarkdownReport"