The conventions model
Conventions are a repository's rulebook for where files belong and what they are named, stored in a conventions document owned by the repository and synchronized to the server. They exist so "components go here, named like this, and do not rewrite a helper that already exists" is a machine-answerable question instead of tribal knowledge.
The three delivery surfaces
- Session-start summary — a short server-worded block injected when a session begins, saying which kinds this repository declares rules for. Advisory; fail-silent when the server is unreachable.
- Explicit lookup —
check_convention, called before creating, renaming or moving a file. Answers with an exact verdict, a corrected path when the proposal violates a rule, or a state code when no rule can be applied. Rename and move requiresource_path, because moving a file can change which rules govern it. - Pre-write enforcement — only on installs configured with dev or guardrails profiles, a validator hook can deny a nonconforming write outright. A default install does not deny writes; the summary and the lookup are its coverage.
Placement is checked on demand only
Folder placement is never checked by a pre-write hook on any profile: a
hook sees only a path and would have to guess what kind of file it is.
Placement is checked when you call check_convention and pass kind
yourself.
Opt-outs
A repository can disable convention checks entirely, or per-language,
via its cix configuration. When disabled, naming and duplicate checks
are skipped and the session-start summary says so. check_convention
remains callable regardless — it reports the opt-out rather than
pretending a check ran.
Reading a verdict honestly
valid: true/false is a rule verdict. State codes (see
[errors-conventions]) mean no rule could be applied — report those as
"not checked", never as "allowed".