Spec leads code

Informative guide. This Book page explains Beskid but does not define the standard. For normative requirements, use the Beskid Standard.

Tests prove the current implementation. They do not replace missing contract text. Spec leads code means:

If you change what valid Beskid means or what the CLI must do, you update Platform specification in the same change set (or immediately before merge).

Authority: Specification authority and embedded decisions.

Practical workflow

gitGraph
  accTitle: Spec change and implementation in one change set
  accDescr: A design gap or bug starts one branch. The branch carries the OpenSpec change with its spec delta, then the compiler, corelib or tooling changes, conformance tests and OpenSpec validation, and merges to main together.
  commit id: "design gap or bug"
  branch change
  commit id: "openspec change and spec delta"
  commit id: "compiler, corelib, tooling"
  commit id: "conformance tests"
  commit id: "openspec validate"
  checkout main
  merge change

Text equivalent: A design gap or bug leads to one change set. It carries the OpenSpec change with its spec delta, then the implementation, conformance tests and OpenSpec validation, and merges together.

1. Classify the topic (language law vs implementation).
2. Extend the owning feature hub or article: no circular “canonical chapter is this page” stubs.
3. Anchor crates in implementation map when touching compiler/.
4. Land tests in beskid_tests / beskid_e2e_tests when behavior is platform-wide.

Anti-patterns

Anti-pattern	Why it hurts
”Docs follow-up ticket”	Shipped behavior without law
README-only normative rules	Not searchable, not validated
Copy-paste tables across domains	Drift within a sprint

Next

Language law vs implementation