W804/W807 diagnostics reference `derivedFromCybersecurityGoal` but docs/template use `derivedFromSecurityGoal`
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 7
- Forks
- 1
- Avg merge
- 21m
- Merged PRs (30d)
- 2
Description
Summary
The W804 and W807 validator diagnostics refer to a requirement field named
derivedFromCybersecurityGoal, but every documentation surface — the Requirement
template, --agent-instructions, spec fields, and even the spec validation rows for
W804/W807 themselves — names the field derivedFromSecurityGoal.
Both names are in fact honored by the parser (see repro), so this is a naming
inconsistency between the diagnostics and the docs, not a broken field. But it is
actively misleading: an author who hits W804/W807 is told to add a field
(derivedFromCybersecurityGoal) that appears nowhere in the documentation, while an
author following the docs (derivedFromSecurityGoal) sees messages that name a different
field. I initially concluded the docs were wrong and switched my whole model to the
message's field name before discovering both work.
Environment
syscribe 0.30.0
Evidence
Documentation consistently uses derivedFromSecurityGoal:
$ syscribe template Requirement | grep -i securitygoal
# derivedFromSecurityGoal: CSG-PREFIX-001
$ syscribe spec fields | grep -i securitygoal
| `derivedFromSecurityGoal` | string | CybersecurityGoal ID/QName |
| `derivedFromSecurityGoal` | Requirement | string | `CSG-*` that generated this requirement |
$ syscribe spec validation | grep -iE 'W804|W807'
| `W804` | `CybersecurityGoal` has no `Requirement` with `derivedFromSecurityGoal` pointing to it |
| `W807` | `Requirement` with `derivedFromSecurityGoal` has no `verificationMethod` |
$ syscribe --agent-instructions | grep -i securitygoal
| `derivedFromSecurityGoal` | ID of the `CybersecurityGoal` that motivated this requirement. Requires `verificationMethod:` (W807). |
... create `Requirement` elements with `derivedFromSecurityGoal: CSG-SYS-001` and set `verificationMethod:`.
- [ ] If `derivedFromSecurityGoal:` is set → `verificationMethod:` is also set (W807)
But the runtime diagnostics name derivedFromCybersecurityGoal:
| W804 | .../TARA-EM-001.md | CybersecurityGoal 'CSG-EM-001' has no Requirement with `derivedFromCybersecurityGoal` pointing to it |
| W807 | .../REQ-EM-SEC-001.md | security Requirement (derivedFromCybersecurityGoal set) has no verificationMethod — add test, inspection, analysis, or demonstration |
Reproduction
Given a TARASheet defining CSG-EM-001 and a leaf Requirement:
- Add
derivedFromSecurityGoal: CSG-EM-001(the documented name) to the requirement →
W804forCSG-EM-001clears andE831resolves. The field is honored. - Rename it to
derivedFromCybersecurityGoal: CSG-EM-001(the diagnostic's name) →
also honored;W804stays clear. - Remove the field entirely →
W804fires, and its message text tells you to add
derivedFromCybersecurityGoal, which does not appear in any docs/template.
Impact
- Authors reading
W804/W807are pointed at a field name that is absent from the
template,spec fields,spec validation, and--agent-instructions. - Leads to unnecessary edits / confusion about which name is canonical (both work).
Suggested fix
Pick one canonical field name and use it everywhere. Easiest: change the W804 and
W807 message strings to say derivedFromSecurityGoal so they match the documentation.
(If derivedFromCybersecurityGoal is meant to be canonical, update the template,
spec fields, spec validation, and --agent-instructions to match instead — and
consider keeping the other as a documented alias.)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the W804 and W807 validator diagnostics and compare their field names with the Requirement template, --agent-instructions, spec fields, and spec validation output. Confirm the documented field remains honored by the parser and update the diagnostics or documentation so one canonical name is used consistently; verify the supplied reproduction no longer produces misleading guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 70/100