sjames / sjames/syscribe

W804/W807 diagnostics reference `derivedFromCybersecurityGoal` but docs/template use `derivedFromSecurityGoal`

Open Beginner friendly
#84 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. Add derivedFromSecurityGoal: CSG-EM-001 (the documented name) to the requirement →
    W804 for CSG-EM-001 clears and E831 resolves. The field is honored.
  2. Rename it to derivedFromCybersecurityGoal: CSG-EM-001 (the diagnostic's name) →
    also honored; W804 stays clear.
  3. Remove the field entirely → W804 fires, and its message text tells you to add
    derivedFromCybersecurityGoal, which does not appear in any docs/template.

Impact

  • Authors reading W804/W807 are 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.