Check Field Mandates
The concrete engine for the rule that a definition's declared fields and its prose agree. Skill
and agent definitions ship structured blocks — an Input, an Output, a dispatch payload — whose
fields the surrounding prose also mandates. A field the prose mandates and the block omits does not
fail loudly: the stage that depends on it silently never fires. Nothing else in the repo diffs the
two token sets.
What it checks
Every plugins/<plugin>/skills/**/SKILL.md and plugins/<plugin>/agents/*.md, both directions:
- unexplained — a block declares a field that carries no gloss and that the prose never names.
- undeclared — the prose names a known field in a code span, and none of the file's blocks declare it.
- miscased — the prose names, in a code span, a field this file's block declares, but spelled
in the other case (
governances_loadedagainstGOVERNANCES_LOADED).
A field token is UPPER_CASE or snake_case; the two spellings name the same field. A lowercase
word needs an underscore to be a token, so ordinary prose (owner) is never a field.
A structured block is a fenced code block with no info string (or text). A declaration is a
block line opening with field tokens then a colon (STATUS: complete | blocked), a comma list of two
or more tokens (SPEC_PATH, FEATURE_PATH), or a list item opening with bold tokens
(- **SUBJECT** — …). A gloss is the text after the colon or the bold lead, through to the next
declaration.
A field is explained by a gloss or by the prose. A glossed declaration already says what it carries; the rule catches the bare one nothing explains.
A mandate is a code span naming a known field — a token some definition in the tree declares.
That vocabulary separates a field from an uppercase literal such as TODO. A definition that
declares no field at all is a consumer, and its prose is not held to a block.
Naming another agent's field on purpose — a conductor describing what it passes a judge — is marked beside the line, with its reason:
Pass the zero-based `ROW` to the case judge. <!-- field-mandate-ignore: the case judge's input, not ours -->
A marker with no reason excuses nothing. There is no allow-list file: a real mismatch is fixed.
Run it
node "<skill>/scripts/check-field-mandates.mjs" [--root <dir>]
--root defaults to the working directory. A finding always exits non-zero, as does a root that is
not a readable directory and an unrecognized flag — there is deliberately no report-only mode.
It joins the root check chain as check:fields, so it runs on every pnpm verify and in CI.