docs: document the law card schema and its two axes - #19
Merged
Conversation
A consumer rendering law cards from `laws --json` had to infer that
`stack: "frontend"` means "read satisfiedBy.angular". Nothing said so,
so they coded against an observation and reported the difference as an
inconsistency. It is not one — but the contract was undocumented, which
is our fault, not theirs.
`stack` answers selection: does this law run here at all. A
`satisfiedBy` key answers guidance: which technology the instructions
are written for. The two are orthogonal, and the registry proves it —
no key maps onto a single stack:
typescript 71 laws = 12 typescript-stack + 59 universal
python 70 laws = 37 python-stack + 33 universal
angular 67 laws = 58 frontend-stack + 3 typescript
+ 6 universal
`angular` sitting on TypeScript-stack and universal laws is the
clearest evidence that a key is not a stack label. Renaming it to
`frontend` would make the field lie: the advice really is
Angular-specific, and a React project matches `stack: "frontend"`.
The JSON already ships the mapping as `satisfiedByStacks.stackToKey`,
so the section points renderers at that field rather than a table to
copy — a key added later is then picked up rather than missed. It also
states the gap plainly: all 58 frontend laws carry only Angular
guidance, and a card should say so rather than present Angular steps as
universal (#12).
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.
Answers the question behind #11: a consumer rendering law cards from
laws --jsonhad to infer thatstack: "frontend"means "readsatisfiedBy.angular". Nothing said so, so they coded against an observation.The two axes
stackfrontend,typescript,python, absent (universal)satisfiedBykeystypescript,angular,pythonThey are orthogonal, and the registry proves it — no key maps onto a single stack:
typescripttypescript+ 59 universalpythonpython+ 33 universalangularfrontend+ 3typescript+ 6 universalangularon TypeScript-stack and universal laws is the clearest evidence that a key is not a stack label. Renaming it tofrontendwould make the field lie: the advice really is Angular-specific, and a React project matchesstack: "frontend".We already shipped the contract, undocumented
The section points renderers at that field rather than a table to copy, so a key added later is picked up rather than missed.
The gap, stated plainly
All 58 frontend laws carry only Angular guidance (#12). A card should say "written for Angular — no React/Vue instructions yet" rather than present Angular steps as universal. The honesty
detectionLimitsapplies to detection, applied to remediation.Verdict impact
None — documentation only.
Gate
npm run lint— 0 errorsnode dist/cli.js audit— exit 0