Skip to content

docs: document the law card schema and its two axes - #19

Merged
ruleofcodedev merged 1 commit into
developfrom
feature/law-card-schema
Aug 8, 2026
Merged

docs: document the law card schema and its two axes#19
ruleofcodedev merged 1 commit into
developfrom
feature/law-card-schema

Conversation

@ruleofcodedev

Copy link
Copy Markdown
Contributor

Answers the question behind #11: 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.

The two axes

field question values
stack selection — does this law run here at all? frontend, typescript, python, absent (universal)
satisfiedBy keys guidance — which technology are the instructions written for? typescript, angular, python

They are orthogonal, and the registry proves it — no key maps onto a single stack:

key laws spread
typescript 71 12 typescript + 59 universal
python 70 37 python + 33 universal
angular 67 58 frontend + 3 typescript + 6 universal

angular 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".

We already shipped the contract, undocumented

"satisfiedByStacks": {
  "keys": ["typescript", "angular", "python"],
  "stackToKey": { "frontend": "angular", "typescript": "typescript", "python": "python" }
}

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 detectionLimits applies to detection, applied to remediation.

Verdict impact

None — documentation only.

Gate

  • npm run lint — 0 errors
  • node dist/cli.js audit — exit 0

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).
@ruleofcodedev
ruleofcodedev merged commit 787e250 into develop Aug 8, 2026
2 checks passed
@ruleofcodedev
ruleofcodedev deleted the feature/law-card-schema branch August 8, 2026 12:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant