[bmscomp]

Why

The Conformity Checks chapter (#431) teaches the KafkaReference language step by step. The book had no single place that lists every field, value kind, rule id, report field and lint code. This adds one as an appendix, after the version matrix, and commits the plan behind #439.

Both files sat uncommitted in the main checkout while ten PRs (#434–#443) landed. Three of those changed what the appendix described, so it's brought up to date with main here.

What changes

docs/book/appendix-conformity-language.md: Conformity Language Reference. It covers:

• the document and its value kinds;
• constraint forms and severity;
• rule ids and settings;
• each rule section, with what the check reads and when a rule is UNKNOWN;
• waivers, the report and its fields;
• every lint code, including the cross-rule checks from feat(conformity): lint finds placement, quorum and durability rules no cluster can meet #430 and feat(conformity): lint finds resource, version and listener rules no cluster can meet #432;
• the canonical form, the size limits and the shipped examples.

Aligned with main:

• fix(cli): kates conformity lint refuses a key set twice to the same value, as the check does #437: a key set twice to the same value is an error that fmt fixes, not a warning. This covers the prose in The Document and the duplicate-key row, as handed over from that PR.
• feat(chart,conformity): rbac.scope=namespace runs tests and conformity checks without cluster admin #439, rbac.scope=namespace:
  • when nodes can't be listed, zones, skew and kafka.rackAwareness (source cr) read the zones from the EndpointSlices of <cluster>-kafka-brokers;
  • monitoring.podMonitor looks in the Kafka namespace only, and is UNKNOWN when none there selects the brokers;
  • a refused get of the Kafka resource is a 503 that names the grant.
• fix(chart): the Kates API's chaos, topology and conformity follow the Kafka namespace and cluster name #441: the chart sets the checked namespace and cluster from networkPolicy.kafka.namespace and kafka.clusterName.

Links to it:

• _quarto.yml and README.md list it.
• The Reference part's intro describes it.
• The CLI Reference's Conformity entry points to it.
• The chapter's lint paragraph now points to its Lint Findings section, and its Language at a Glance points to the full reference.

11-api-reference.md: the conformity endpoint's 503 now also covers a Kubernetes API that refuses the Kafka resource (#439). Before, it covered only an unreachable one.

plans/adminless-kubernetes.md: the plan behind #439. A status block at the top records:

• What shipped: feat(chart,conformity): rbac.scope=namespace runs tests and conformity checks without cluster admin #439, fix(chart): the Kates API's chaos, topology and conformity follow the Kafka namespace and cluster name #441, fix(chaos): a fault that names no targetNamespace is in the Kafka cluster's namespace, wherever it is #442 and docs(book): Recipe 7 gates a CI pipeline on Kafka, on either install mode #443.
• D4 differs from the plan. The zones come from EndpointSlices, so they aren't left UNKNOWN.
• Orphan recovery stays on. The chart doesn't set KATES_CHAOS_ORPHAN_RECOVERY_ENABLED=false.
• Still open:
  • the ClusterRole name collision;
  • dns-detect running before the node check;
  • a rule's source that names nodes for EndpointSlice zones;
  • the kates watch default namespaces;
  • the consumer-isolation playbook's targetNamespace: kates.

Tests

Run locally, for the jobs docs/book/** triggers:

• scripts/check-book-style.sh passes; the structure ratchet holds.
• scripts/check-book-contrast.py passes.
• scripts/gen-version-matrix.sh --check and scripts/gen-chart-table.sh --check pass. I ran both in a clean worktree, because this checkout has a leftover, untracked charts/minio directory that only trips them locally.
• Scratch-copy HTML render (prepare-book-render.sh, quarto render --to html) shows no warnings. check-book-fragments.py passes: all 7,981 fragment links in 40 pages land on an id.
• A scratch-copy PDF render (--to pdf -M keep-tex:true) builds, with the appendix in it. The only missing glyphs are the six emoji (⏳ ⛔ ✅ ❌ 📊 🔥) this Mac always lacks; the new text adds only …, which the book already uses.
• No Mermaid in the changed files.