Placeholder grammar

How the placeholder vocabulary lets rules treat template tokens as opaque rather than flagging them as content violations.

Placeholder grammar is an opt-in vocabulary of named tokens that rules can treat as opaque. A rule with a placeholders: setting consults the shared helper and suppresses diagnostics for content that matches a configured token. This lets template files coexist with linting: rules that apply to real content still run, but placeholder tokens do not trigger false positives.

# Token vocabulary

The vocabulary is closed: the token list lives in one place inside the engine, and no rule hardcodes token names in its own logic. Adding a token requires updating that shared list and opting each relevant rule in.

# The placeholders: setting contract

Any rule that opts in exposes placeholders: as a setting through the Configurable interface. The value is a list of token names:

kinds:
  proto:
    rules:
      first-line-heading:
        placeholders: [heading-question]
      heading-increment:
        placeholders: [heading-question, placeholder-section]
      cross-file-reference-integrity:
        placeholders: [var-token]
      paragraph-readability:
        placeholders: [var-token]
      paragraph-structure:
        placeholders: [var-token]
      required-structure:
        placeholders: [cue-frontmatter]

When placeholders: is empty (the default), every rule produces the same diagnostics it does today — there is no behavioral change.

# How rules opt in

A rule adds Placeholders []string to its struct and calls the helper from internal/placeholders:

• ContainsBodyToken(text, tokens) — returns true if text matches any configured body token. Used by heading and paragraph rules to skip checks on placeholder content.
• MaskBodyTokens(text, tokens) — replaces matched tokens with neutral text for analysis (e.g. {title} → word). Used by paragraph-readability and paragraph-structure to check non-placeholder parts of the text.
• HasCUEFrontmatter(tokens) — returns true if cue-frontmatter is configured. Used by required-structure to skip CUE front-matter validation.

# Opt-in rules