Skip to content

docs: publish rule catalog for check --checks safety (and lint / policy) #1125

Description

@sahrizvi

Deferred from the v0.9.6 release review (End User + PM personas).

Context

v0.9.6 adds a new safety rule from the engine: unbalanced_quote. Users only learn its name when it fires — there's no rule catalog in the docs. Same for lint (mentions L003 in the example only) and policy (rules are user-defined but there's no reference for the built-ins).

The v0.9.6 release patch added a one-line hint in docs/docs/usage/check.md:

Every finding carries a machine-readable rule field... visible in --format json output, and how the safety, lint, and policy rule inventory is discovered in practice.

That's a workaround, not a catalog.

What to do

  • Add a "Safety Rules" section to docs/docs/usage/check.md listing every rule the engine can emit (name + one-line description + example)
  • Same for lint (built-in rules) and policy (built-in policy checks)
  • Auto-generate from engine metadata if the engine exposes it — otherwise curated markdown, updated with each altimate-core bump
  • Cross-link from the Available Checks table so users can navigate: check → rule catalog → example

Priority

P2 — no user is blocked, but "what's unbalanced_quote?" is a certain support-ticket generator on Monday morning after upgrade.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions