Add root-tags orphan detection for requirements traceability

.config/dotnet-tools.json

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

docs/reqstream/api-mark-core.yaml

@@ -7,6 +7,7 @@ sections:
         title: ApiMarkCore shall provide a two-stage language-generator contract (Parse
           + Emit) that callers can use to invoke any supported language module with
           a configurable output format.
+        tags: [system]
         justification: |
           ApiMark needs a common contract so the CLI and any build integration can
           trigger documentation generation without knowing the implementation details
@@ -21,6 +22,7 @@ sections:
         title: ApiMarkCore shall provide a minimal output channel interface that language
           generators can use to emit informational and error messages without depending
           on Console.
+        tags: [system]
         justification: |
           ApiMark generators need to emit diagnostic output without depending on
           Console directly, so the channel can be captured, suppressed, or
@@ -29,10 +31,13 @@ sections:
         children:
           - ApiMarkCore-IContext-DefineWriteLineMethod
           - ApiMarkCore-IContext-DefineWriteErrorMethod
+          - ApiMarkCore-IContext-RejectNullWriteLine
+          - ApiMarkCore-IContext-RejectNullWriteError
         tests: [InMemoryContext_WriteLineAndWriteError_RouteToSeparateChannels]
       - id: ApiMarkCore-IMarkdownWriterFactory-ProvideMarkdownWriterFactoryInterface
         title: ApiMarkCore shall provide a factory interface for creating per-file
           Markdown writers so that language generators are decoupled from the file-system.
+        tags: [system]
         justification: |
           Decoupling generators from the file-system via a factory contract allows
           the same generator code to write to disk in production and to memory in
@@ -44,10 +49,19 @@ sections:
           - ApiMarkCore-IMarkdownWriterFactory-RejectEmptyOutputDirectory
           - ApiMarkCore-IMarkdownWriterFactory-RejectWhitespaceOutputDirectory
           - ApiMarkCore-IMarkdownWriterFactory-EnsureOutputDirectory
+          - ApiMarkCore-FileMarkdownWriterFactory-RejectNullOutputDirectory
+          - ApiMarkCore-FileMarkdownWriterFactory-RejectEmptyOutputDirectory
+          - ApiMarkCore-FileMarkdownWriterFactory-RejectWhitespaceOutputDirectory
+          - ApiMarkCore-FileMarkdownWriterFactory-RejectNullName
+          - ApiMarkCore-FileMarkdownWriterFactory-RejectEmptyName
+          - ApiMarkCore-FileMarkdownWriterFactory-RejectWhitespaceName
+          - ApiMarkCore-FileMarkdownWriterFactory-SupportRootLevelFiles
+          - ApiMarkCore-FileMarkdownWriterFactory-CreateOutputDirectoryOnUse
         tests: [ApiMarkCore_WriterFactory_CanCreate_RootAndSubfolderWriters]
       - id: ApiMarkCore-IMarkdownWriter-ProvideMarkdownOutputInterface
         title: ApiMarkCore shall provide a markdown output interface for writing individual
           documentation files.
+        tags: [system]
         justification: |
           A shared markdown-writing abstraction keeps the generated document shape
           consistent while allowing output helpers to evolve without changing each
@@ -62,10 +76,43 @@ sections:
           - ApiMarkCore-IMarkdownWriter-DefineWriteLink
           - ApiMarkCore-IMarkdownWriter-WriteHeadingRejectInvalidLevel
           - ApiMarkCore-IMarkdownWriter-ThrowObjectDisposedAfterDispose
+          - ApiMarkCore-IMarkdownWriter-WriteTableRejectEmptyHeaders
+          - ApiMarkCore-IMarkdownWriter-WriteTableRejectMismatchedRowLength
+          - ApiMarkCore-IMarkdownWriter-WriteHeadingRejectEmptyText
+          - ApiMarkCore-IMarkdownWriter-WriteLinkRejectEmptyText
+          - ApiMarkCore-IMarkdownWriter-WriteTableRejectNullRowElements
+          - ApiMarkCore-IMarkdownWriter-WriteTableRejectNullHeaderElements
+          - ApiMarkCore-IMarkdownWriter-WriteTableRejectNullCellElements
+          - ApiMarkCore-FileMarkdownWriter-WriteHeadingAsAtxSyntax
+          - ApiMarkCore-FileMarkdownWriter-WriteSignatureAsCodeFence
+          - ApiMarkCore-FileMarkdownWriter-WriteParagraphAsText
+          - ApiMarkCore-FileMarkdownWriter-WriteTableAsPipeTable
+          - ApiMarkCore-FileMarkdownWriter-WriteCodeBlockAsCodeFence
+          - ApiMarkCore-FileMarkdownWriter-WriteLinkAsMarkdownLink
+          - ApiMarkCore-FileMarkdownWriter-FlushAndCloseOnDispose
+          - ApiMarkCore-FileMarkdownWriter-WriteHeadingRejectInvalidLevel
+          - ApiMarkCore-FileMarkdownWriter-ThrowObjectDisposedAfterDispose
+          - ApiMarkCore-FileMarkdownWriter-RejectNullSignatureLanguage
+          - ApiMarkCore-FileMarkdownWriter-RejectNullSignatureCode
+          - ApiMarkCore-FileMarkdownWriter-RejectNullParagraphText
+          - ApiMarkCore-FileMarkdownWriter-RejectNullTableHeaders
+          - ApiMarkCore-FileMarkdownWriter-RejectNullTableRows
+          - ApiMarkCore-FileMarkdownWriter-RejectNullCodeBlockLanguage
+          - ApiMarkCore-FileMarkdownWriter-RejectNullCodeBlockCode
+          - ApiMarkCore-FileMarkdownWriter-RejectNullLinkText
+          - ApiMarkCore-FileMarkdownWriter-RejectNullLinkRelativePath
+          - ApiMarkCore-FileMarkdownWriter-RejectEmptyHeaders
+          - ApiMarkCore-FileMarkdownWriter-RejectMismatchedRowLength
+          - ApiMarkCore-FileMarkdownWriter-RejectEmptyHeadingText
+          - ApiMarkCore-FileMarkdownWriter-RejectEmptyLinkText
+          - ApiMarkCore-FileMarkdownWriter-RejectNullRowElements
+          - ApiMarkCore-FileMarkdownWriter-RejectNullHeaderElements
+          - ApiMarkCore-FileMarkdownWriter-RejectNullCellElements
         tests: [InMemoryMarkdownWriter_Write_AllOperations_RecordsInOrder]
       - id: ApiMarkCore-PathHelpers-ProvideSafePathCombinationHelper
         title: ApiMarkCore shall provide an internal helper for safely combining caller-supplied
           relative path segments with a trusted base path.
+        tags: [system]
         justification: |
           ApiMark needs one auditable place to enforce path-safety rules so file-based
           helpers do not each implement their own traversal checks inconsistently.
@@ -80,6 +127,7 @@ sections:
           - PathHelpers_SafePathCombine_NullBasePath_ThrowsArgumentNullException
       - id: ApiMarkCore-ProvideEmitterContract
         title: ApiMark Core shall provide a well-defined emitter contract.
+        tags: [system]
         justification: |
           ApiMark needs a contract interface for the Emit stage so that language
           generators can produce Markdown output without depending on a concrete
@@ -90,18 +138,23 @@ sections:
           - ApiMarkCore-IApiEmitter-ProduceApiMdEntrypoint
           - ApiMarkCore-IApiEmitter-SupportGradualDisclosure
           - ApiMarkCore-IApiEmitter-SupportSingleFile
+          - ApiMarkCore-IApiEmitter-RejectNullFactory
+          - ApiMarkCore-IApiEmitter-RejectNullConfig
+          - ApiMarkCore-IApiEmitter-RejectNullContext
         tests:
           - IApiEmitter_Emit_WithGradualDisclosure_ProducesMultipleFiles
           - IApiEmitter_Emit_WithSingleFile_ProducesSingleApiMd
       - id: ApiMarkCore-ProvideEmitConfiguration
         title: ApiMark Core shall provide an emit configuration contract.
+        tags: [system]
         justification: |
           Callers (CLI, MSBuild task) need to communicate the desired output format
           and heading depth to the emitter at emit time without coupling those choices
           to language-specific generator options.
         children:
           - ApiMarkCore-EmitConfig-DefineFormat
           - ApiMarkCore-EmitConfig-DefineHeadingDepth
+          - ApiMarkCore-EmitConfig-ValidateHeadingDepthRange
         tests:
           - EmitConfig_DefaultFormat_IsGradualDisclosure
           - EmitConfig_DefaultHeadingDepth_IsOne
@@ -111,6 +164,7 @@ sections:
       - id: ApiMarkCore-GlobFileCollector-ProvideGlobFileCollector
         title: ApiMark Core shall provide a shared utility for discovering files from
           the filesystem using gitignore-style glob patterns.
+        tags: [system]
         justification: |
           Multiple language generators (C++ and VHDL) need to discover source files
           based on caller-supplied glob patterns. Providing a shared, tested utility
@@ -137,6 +191,7 @@ sections:
         title: ApiMark Core shall provide an optional documentation-coverage
           enforcement capability interface that language generators can
           implement to expose a language-agnostic coverage scan to callers.
+        tags: [system]
         justification: |
           ApiMark supports opt-in documentation-coverage enforcement
           (`--enforce-docs`) across multiple languages (dotnet, cpp, vhdl).
@@ -148,5 +203,8 @@ sections:
         children:
           - ApiMarkCore-IDocumentationCoverageCapable-DefineCheckDocumentationCoverageMethod
           - ApiMarkCore-DocumentationCoverageResult-ProvideSharedResultType
+          - ApiMarkCore-IDocumentationCoverageCapable-FallBackToConfiguredTierWhenParameterOmitted
+          - ApiMarkCore-IDocumentationCoverageCapable-RejectUnrecognizedEnforceTier
+          - ApiMarkCore-IDocumentationCoverageCapable-RequireParseBeforeCheck
         tests:
           - ApiMarkCore_DocumentationCoverageContract_SupportedLanguage_CanBeInvoked

docs/reqstream/api-mark-cpp.yaml

@@ -6,6 +6,7 @@ sections:
       - id: ApiMarkCpp-CppGenerator-GenerateDocumentationFromCppHeaders
         title: ApiMarkCpp shall generate API documentation from C++ header files and
           their Doxygen doc comments.
+        tags: [system]
         justification: |
           ApiMark needs to document C++ libraries from public header files without requiring
           a full build, using the headers for API structure and Doxygen doc comments for the
@@ -46,6 +47,7 @@ sections:
       - id: ApiMarkCpp-EmitExternalTypesSection
         title: ApiMarkCpp shall render unrecognized non-std type references in an
           External Types section on the affected page.
+        tags: [system]
         justification: |
           When a documented type references a type outside the library and outside the
           C++ standard library, readers need a clear indication of the external dependency.

docs/reqstream/api-mark-dot-net.yaml

@@ -6,6 +6,7 @@ sections:
       - id: ApiMarkDotNet-GenerateDocumentationFromAssembliesAndXml
         title: ApiMarkDotNet shall generate API documentation from .NET assemblies
           and XML documentation files.
+        tags: [system]
         justification: |
           ApiMark needs to document compiled .NET libraries without requiring source
           code access, using the assembly for API structure and the XML file for the
@@ -15,6 +16,7 @@ sections:
           - ApiMarkDotNet-DotNetGenerator-DiscoverTypesAndMembers
           - ApiMarkDotNet-DotNetGenerator-ReadXmlDocumentationComments
           - ApiMarkDotNet-DotNetGenerator-FilterByVisibility
+          - ApiMarkDotNet-DotNetGenerator-FilterByExcludePattern
           - ApiMarkDotNet-DotNetGenerator-IncludeObsoleteApisWhenRequested
           - ApiMarkDotNet-DotNetGenerator-RecognizeNamespaceDocCarrierClass
           - ApiMarkDotNet-DotNetGenerator-ExcludeNamespaceDocCarrierFromTypeListing
@@ -68,6 +70,7 @@ sections:
       - id: ApiMarkDotNet-TypeNameSimplifier-ProduceReadableTypeNames
         title: ApiMarkDotNet shall render .NET type names in a concise C#-style form
           that is readable in generated documentation.
+        tags: [system]
         justification: |
           Raw CLR type names are noisy and difficult to read, so the .NET system needs
           a consistent simplification policy that keeps signatures compact for both
@@ -85,6 +88,7 @@ sections:
         title: ApiMarkDotNet shall optionally check parsed assemblies for missing XML
           doc summaries at a caller-selected visibility tier, independent of Markdown
           emission.
+        tags: [system]
         justification: |
           Users have asked whether ApiMark can enforce API documentation completeness
           — warning or failing a build when public (or optionally protected, internal,

docs/reqstream/api-mark-msbuild.yaml

@@ -6,6 +6,7 @@ sections:
       - id: ApiMarkMsbuild-ApiMarkTask-IntegrateWithMsbuild
         title: ApiMarkMsbuild shall integrate ApiMark documentation generation as
           an MSBuild task for both .csproj and .vcxproj builds.
+        tags: [system]
         justification: |
           Teams using C# and C++ need documentation generation to run automatically
           during normal builds so the published API reference stays aligned with the
@@ -30,12 +31,21 @@ sections:
           - ApiMarkMsbuild-ApiMarkTask-ForwardFormatProperty
           - ApiMarkMsbuild-ApiMarkTask-ForwardEnforceDocsProperties
           - ApiMarkMsbuild-ApiMarkTask-SupportOutputsItemGroup
+          - ApiMarkMsbuild-ApiMarkTask-ForwardExcludePatterns
+          - ApiMarkMsbuild-ApiMarkTask-OverrideOutputProperties
+          - ApiMarkMsbuild-ApiMarkTask-RestoreOutputProperties
+          - ApiMarkMsbuild-ApiMarkTask-ResolveDotNetFromEnvironment
+          - ApiMarkMsbuild-ApiMarkTask-ReportMissingDotNetExe
+          - ApiMarkMsbuild-ApiMarkTask-SurfaceToolExitCode
+          - ApiMarkMsbuild-ApiMarkTask-ForwardStdoutToLog
+          - ApiMarkMsbuild-ApiMarkTask-ForwardStderrErrors
         tests:
           - ApiMarkMsbuild_NuGetPackage_DotNetProject_AutoDocumentsOnBuild
           - windows@ApiMarkMsbuild_NuGetPackage_CppVcxprojProject_AutoDocumentsOnBuild
       - id: ApiMarkMsbuild-IncludeDocsInNuGetPackage
         title: ApiMarkMsbuild shall support an opt-in ApiMarkPackDocs property that,
           when set to true, includes generated documentation in the NuGet package.
+        tags: [system]
         justification: |
           Projects that distribute API documentation alongside their library need a single
           opt-in flag to bundle the generated markdown in the NuGet package so consumers

docs/reqstream/api-mark-tool.yaml

@@ -6,6 +6,7 @@ sections:
       - id: ApiMarkTool-ProvideMultiLanguageCli
         title: ApiMarkTool shall provide a .NET executable that supports multiple
           documentation language subcommands.
+        tags: [system]
         justification: |
           A command-line executable gives ApiMarkTask and developers an automation-friendly
           way to run ApiMark for any supported language. Targeting net8.0 and later as a standalone

docs/reqstream/api-mark-tool/cli.yaml

@@ -28,6 +28,7 @@ sections:
               - ApiMarkTool-Cli-Context-ParseExcludes
               - ApiMarkTool-Cli-Context-ParseEnforceDocsOption
               - ApiMarkTool-Cli-Context-ParseEnforceDocsSeverityOption
+              - ApiMarkTool-Cli-Context-RejectFlagAsOptionValue
               - ApiMarkTool-Cli-SuppressOutputWhenSilent
               - ApiMarkTool-Cli-RouteOutputThroughContext
             tests: [Context_Cli_ParsesAllGlobalFlags]

docs/reqstream/api-mark-tool/self-test.yaml

@@ -24,4 +24,8 @@ sections:
               - ApiMarkTool-SelfTest-Validation-RunVhdlGenerationTest
               - ApiMarkTool-SelfTest-Validation-SkipCppWhenClangUnavailable
               - ApiMarkTool-SelfTest-Validation-ReportSkippedCount
+              - ApiMarkTool-SelfTest-Validation-RunDotNetEnforceDocsTest
+              - ApiMarkTool-SelfTest-Validation-RunCppEnforceDocsTest
+              - ApiMarkTool-SelfTest-Validation-RunVhdlEnforceDocsTest
+              - ApiMarkTool-SelfTest-Validation-SuppressGeneratorOutput
             tests: [Validation_Run_WithValidContext_ExitsZero]

docs/reqstream/api-mark-vhdl.yaml

@@ -6,6 +6,7 @@ sections:
       - id: ApiMarkVhdl-VhdlGenerator-GenerateDocumentationFromVhdlSources
         title: ApiMarkVhdl shall generate API documentation from VHDL source files
           and their --! doc comments.
+        tags: [system]
         justification: |
           ApiMark needs to document VHDL IP cores from .vhd source files so that AI agents
           and developers can browse entity interfaces, generics, ports, and architectures
@@ -26,4 +27,7 @@ sections:
           - ApiMarkVhdl-DocumentationCoverageChecker-FallBackToConfiguredTierWhenParameterOmitted
           - ApiMarkVhdl-DocumentationCoverageChecker-RejectUnrecognizedEnforceTier
           - ApiMarkVhdl-DocumentationCoverageChecker-RequireParseBeforeCheck
+          - ApiMarkVhdl-VhdlGenerator-ValidatesLibraryName
+          - ApiMarkVhdl-VhdlGenerator-ReportParseErrors
+          - ApiMarkVhdl-VhdlAstParser-RejectInvalidSyntax
         tests: [VhdlGenerator_Generate_FixtureFile_CreatesApiEntrypoint]