Add root-tags orphan-requirement detection - #211
Merged
Conversation
Introduces a --root-tags CLI option (and matching root-tags: field in requirements.yaml) that identifies one or more requirement tags as "roots" representing real product/quality purposes. When configured, ReqStream reports any requirement whose parent-child chain never reaches a root tag as an orphan, and --enforce fails the build when orphans are found. This targets a recurring problem where AI agents add low-level requirements, design, code, and tests that are individually well-formed but never connect to any user-facing functionality: orphaned features nobody asked for. Root-tags makes that class of defect mechanically detectable instead of relying on reviewers to notice a dangling chain. Changes: - Modeling/Requirements.cs: orphan-reachability algorithm (ReqStream-Requirements-RootTags / -OrphanReachability). - Cli/Context.cs: --root-tags parsing/merging with requirements.yaml root-tags:, plus a new WriteWarning API for non-fatal orphan reporting (never affects ExitCode, unlike WriteError). - Program.cs: enforce orphan-freedom under --enforce; fixed a regression where a --matrix run with no matching test files could skip orphan enforcement entirely. - docs/reqstream/quality.yaml (new): outcome-oriented root-level quality requirements (build integrity, traceable versions, static analysis, peer review, documentation generation, test infrastructure, architecture traceability) that give OTS tooling (VersionMark, SonarCloud, etc.) a real parent instead of sitting as orphaned requirements - the OTS pieces are HOW quality is met, not requirements in their own right. - Fixed 12 real orphaned requirements uncovered by dogfooding (--root-tags system,quality), tracing each to its actual usage. - Added a 7th self-test scenario (RunOrphanDetectionTest) to SelfTest/Validation.cs for qualification evidence, plus matching design/verification doc and test updates. - Updated README.md and docs/user_guide/introduction.md (including self-validation instructions) to document the feature. - Ran the built-in code-review agent plus 17 ReviewMark formal reviews (one per affected review-set) against this change set and fixed the resulting real findings: missing quality.yaml tests links, a mislevel test reference on ReqStream-Cli-RootTags, missing TemporaryDirectory unit in the architecture doc, missing orphan-detection verification coverage, a stale self-test count, a missing happy-path assertion, undocumented WriteWarning API, a non-compliant markdown anchor link, and a regression test for the Program.cs --matrix/--enforce fix. Added docs/reqstream/quality.yaml to the ReqStream-Design and ReqStream-AllRequirements review-sets. Note: requirements.yaml itself does not yet set root-tags: - the currently released ReqStream binary used elsewhere in this organization doesn't understand that field yet. Enabling it here is deferred to a follow-up change after this feature ships in a release. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds configurable “root tags” to ReqStream to detect orphaned requirements (requirements whose child-link chain never reaches a root-tagged requirement), reporting them as warnings by default and enforcing orphan-freedom as a build-breaking error under --enforce.
Changes:
- Implemented root-tag parsing/unioning (
root-tags:in YAML +--root-tagsCLI) and an orphan reachability algorithm (Requirements.FindOrphans). - Updated
Programenforcement so orphan enforcement is independent of test coverage and is not skipped by the--matrix“no matching tests” guard. - Added extensive unit/integration/self-validation tests and updated requirements/design/verification documentation to cover the new behavior (including a new
docs/reqstream/quality.yamlrequirements set).
Reviewed changes
Copilot reviewed 44 out of 44 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/DemaConsulting.ReqStream.Tests/SelfTest/ValidationTests.cs | Updates self-test log assertions to include the new orphan-detection validation test. |
| test/DemaConsulting.ReqStream.Tests/ProgramTests.cs | Adds system-level tests for orphan warning/enforcement behavior and a --matrix/--enforce regression scenario. |
| test/DemaConsulting.ReqStream.Tests/Modeling/RequirementsLoadTests.cs | Adds unit tests for orphan reachability behavior (FindOrphans). |
| test/DemaConsulting.ReqStream.Tests/Modeling/RequirementsLoadParsingTests.cs | Adds parsing/validation tests for YAML root-tags: handling. |
| test/DemaConsulting.ReqStream.Tests/IntegrationTests.cs | Adds end-to-end integration test for orphan detection under --enforce. |
| test/DemaConsulting.ReqStream.Tests/Cli/ContextTests.cs | Adds CLI parsing tests for --root-tags behavior. |
| src/DemaConsulting.ReqStream/SelfTest/Validation.cs | Adds a new self-validation scenario (RunOrphanDetectionTest) and updates counts/docs. |
| src/DemaConsulting.ReqStream/Program.cs | Wires root-tag merging + orphan reporting; enforces orphans under --enforce; fixes --matrix guard regression. |
| src/DemaConsulting.ReqStream/Modeling/RequirementsLoader.cs | Recognizes and parses root-tags: at the YAML document root and unions across includes. |
| src/DemaConsulting.ReqStream/Modeling/Requirements.cs | Stores RootTags and implements FindOrphans plus OrphanResult record. |
| src/DemaConsulting.ReqStream/Cli/Context.cs | Adds RootTags property, parses --root-tags, and introduces WriteWarning. |
| requirements.yaml | Includes new repository quality requirements file. |
| README.md | Documents the new orphan-detection feature and updated validation output. |
| docs/verification/reqstream/program.md | Adds verification narrative + requirement-to-test mapping for orphan warning/enforcement behaviors. |
| docs/verification/reqstream/modeling/requirements.md | Adds verification narrative + mapping for root-tags parsing and orphan detection behavior. |
| docs/verification/reqstream/modeling.md | Extends modeling verification overview to include orphan detection. |
| docs/verification/reqstream/cli/context.md | Documents and maps --root-tags behavior and WriteWarning. |
| docs/verification/reqstream/cli.md | Updates CLI verification overview/mapping for --root-tags. |
| docs/verification/reqstream.md | Adds system-level verification entry for orphan checking. |
| docs/user_guide/introduction.md | Updates user guide to document orphan detection, new help text, and enforcement semantics. |
| docs/sysml2/model/reqstream/program.sysml | Updates SysML2 doc string to reflect orphan checking responsibility. |
| docs/sysml2/model/reqstream/modeling/requirements.sysml | Updates SysML2 doc string to include root tags and orphan detection. |
| docs/sysml2/model/reqstream/cli/context.sysml | Updates SysML2 doc string to include root-tag configuration. |
| docs/reqstream/reqstream/utilities.yaml | Adds child links to eliminate orphaned utilities/OTS requirement entries. |
| docs/reqstream/reqstream/tracing/trace-matrix.yaml | Links tracing requirements to OTS test-result format requirements to avoid orphaning. |
| docs/reqstream/reqstream/self-test.yaml | Links self-test requirements to TemporaryDirectory and serializer OTS requirements. |
| docs/reqstream/reqstream/program.yaml | Adds atomic requirements for orphan warning + orphan enforcement behavior. |
| docs/reqstream/reqstream/platform-requirements.yaml | Adds platform qualification entries for the new orphan-detection self-test. |
| docs/reqstream/reqstream/modeling/requirements.yaml | Adds requirements covering root-tags parsing and orphan-detection semantics. |
| docs/reqstream/reqstream/modeling/requirements-loader.yaml | Updates lint requirements to include root-tags non-scalar/blank validation coverage. |
| docs/reqstream/reqstream/modeling.yaml | Adds modeling-level orphan detection requirement and links to atomic requirements. |
| docs/reqstream/reqstream/cli/context.yaml | Adds requirement for --root-tags parsing behavior. |
| docs/reqstream/reqstream/cli.yaml | Adds CLI-level --root-tags requirement grouping node. |
| docs/reqstream/reqstream.yaml | Updates system requirements to account for enforcement semantics and adds system orphan-checking requirement. |
| docs/reqstream/quality.yaml | New: repository/process-level quality outcome requirements (root-level “quality” tag). |
| docs/design/reqstream/self-test/validation.md | Updates design doc to reflect seven self-validation tests including orphan detection. |
| docs/design/reqstream/self-test.md | Updates self-test subsystem design to include the new validation scenario. |
| docs/design/reqstream/program.md | Updates program design to describe merged root tags, warning path, and enforcement semantics. |
| docs/design/reqstream/modeling.md | Adds API design documentation for Requirements.FindOrphans and root-tags behavior. |
| docs/design/reqstream/cli/context.md | Documents WriteWarning and updated caller interactions. |
| docs/design/reqstream/cli.md | Updates CLI design documentation to include WriteWarning and RootTags. |
| docs/design/reqstream.md | Updates system design diagram and option list to include TemporaryDirectory and --root-tags. |
| .reviewmark.yaml | Adds the new quality requirements file to relevant review sets. |
| .github/standards/reqstream-usage.md | Documents root-tags/orphan checking usage and adds guidance against unauthorized new roots. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Addresses Copilot PR review comment on #211: the --enforce help string still said it only fails on missing test coverage, but enforcement now also fails on orphaned requirements when root tags are configured. Updated Program.cs help output, README.md, and docs/user_guide/introduction.md consistently. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Addresses Copilot PR review comment on #211: the orphan summary message always used the plural verb ( equirements are orphaned), which read awkwardly when exactly 1 requirement was orphaned (e.g. 1 of 2 requirements are orphaned). Pluralizes the verb based on OrphanIds.Count (is/�re) and the noun based on TotalRequirements ( equirement/ equirements), and updates the affected test assertions in ProgramTests.cs to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduces a --root-tags CLI option (and matching root-tags: field in requirements.yaml) that identifies one or more requirement tags as "roots" representing real product/quality purposes. When configured, ReqStream reports any requirement whose parent-child chain never reaches a root tag as an orphan, and --enforce fails the build when orphans are found.
This targets a recurring problem where AI agents add low-level requirements, design, code, and tests that are individually well-formed but never connect to any user-facing functionality: orphaned features nobody asked for. Root-tags makes that class of defect mechanically detectable instead of relying on reviewers to notice a dangling chain.
Changes:
Note: requirements.yaml itself does not yet set root-tags: - the currently released ReqStream binary used elsewhere in this organization doesn't understand that field yet. Enabling it here is deferred to a follow-up change after this feature ships in a release.