docs(conventions): the merge button is off for a reason, and the reason now lives in the repo

CONVENTIONS.md consolidates rules that already applied but were readable only to
the maintainer: the charter (CLAUDE.md), versioning and vendoring (README.md),
the reporting route (SECURITY.md), and file conventions visible only in the shape
of the files.

Two things stop being inferences. Why pull requests are off: this repository is
vendored into runtimes that pin a tag, so a data change changes what they find,
and that must be coordinated before it exists. And when a value may change: the
three recorded mechanisms - re-extraction, retraction, owner-directed authoring -
each tied to its source_fidelity key, with merit named as not among them.

The four offline checks are included and were each proven to go red on a planted
violation, not merely green on a clean tree. They are one-liners because a script
would be .sh and check 4 would fail on it.

No data file changed; a runtime passing 0.4.1 passes 0.4.2 unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KDRVXSFhKpFTzdoyjpjL17
This commit is contained in:
Kjell Tore Guttormsen 2026-08-11 22:12:37 +02:00
commit fe5e6b290b
3 changed files with 256 additions and 4 deletions

View file

@ -9,6 +9,46 @@ Versioning note: the repository tag versions **the contract** (file set, key nam
case ids, disposition semantics). Each JSON file additionally carries its own
`"version"` field, bumped when that file changes.
## [0.4.2] — 2026-08-11
**No data file changed and no pattern moved.** A runtime that passes `0.4.1` passes `0.4.2`
unchanged; there is nothing here to re-measure. What the release adds is the rule set an outside
contributor could not previously read — including the reason the forge surface is shaped the way
it is.
### Added
- `CONVENTIONS.md` — the whole rule set a change here is held to, consolidated. **Not new
policy:** the charter lives in `CLAUDE.md`, the versioning and vendoring rules in `README.md`,
the reporting route in `SECURITY.md`, and the file conventions were visible only in the shape
of the files. Collected because a convention that exists only in the maintainer's head is not
one an outside reader can meet.
Two things in it were previously inferable at best. **Why pull requests are off:** this
repository is vendored into independent runtimes that pin a tag, so a change to detection data
changes what they *find*, and that has to be coordinated with each consumer **before it
exists** — which a merge button cannot do. `org-ops` reached that conclusion on 2026-08-11
from a README line, and the conclusion was right; this file is the ground it was missing.
**When a value may change:** the three mechanisms that have moved one so far — re-extraction,
retraction, and owner-directed authoring — each named with the `source_fidelity` key that
records it, and merit named explicitly as *not* on that list.
It also carries the four offline checks that stand in for the CI this organisation does not
have. Each was confirmed to go **red** on a violation, not merely green on a clean tree: a
JSON file with no `version`, a `spec/` file with no normative marker, and a planted `.sh` were
each detected. A check that cannot fail proves nothing. The checks are shell one-liners rather
than a script because a script would be `.sh`, and check 4 would fail on the tooling meant to
enforce it.
- `README.md` — a short **Contributing** section pointing at it, carrying the pull-request answer
inline so a reader who never opens the file still gets it. Same pattern the
**Reporting a wrong entry** section followed for `SECURITY.md` in `0.3.1`.
The four `v0.4.1` references in the install block and the layout table move to `v0.4.2`.
This closes the second half of what `org-ops` recorded as missing against the org standard on
2026-08-11. `SECURITY.md` was the first half, in `0.3.1`.
## [0.4.1] — 2026-08-11
**No data file changed and no pattern moved. A number this repository published was wrong, and