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:
parent
2d86151e3b
commit
fe5e6b290b
3 changed files with 256 additions and 4 deletions
21
README.md
21
README.md
|
|
@ -24,7 +24,7 @@ As a `git subtree` (recommended: history is preserved and upgrades are a single
|
|||
|
||||
```bash
|
||||
git subtree add --prefix vendor/commons \
|
||||
https://git.fromaitochitta.com/open/llm-security-commons.git v0.4.1 --squash
|
||||
https://git.fromaitochitta.com/open/llm-security-commons.git v0.4.2 --squash
|
||||
|
||||
# later, to move to a newer tag
|
||||
git subtree pull --prefix vendor/commons \
|
||||
|
|
@ -34,7 +34,7 @@ git subtree pull --prefix vendor/commons \
|
|||
Or pin a tag and copy — `fork-and-own` is an explicitly supported path:
|
||||
|
||||
```bash
|
||||
git clone --depth 1 --branch v0.4.1 \
|
||||
git clone --depth 1 --branch v0.4.2 \
|
||||
https://git.fromaitochitta.com/open/llm-security-commons.git
|
||||
```
|
||||
|
||||
|
|
@ -61,14 +61,14 @@ and keeping it that small is the point.
|
|||
| [`schema/conformance-declaration.schema.json`](schema/conformance-declaration.schema.json) | **Normative.** The shape a runtime publishes alongside a conformance result: which commons tables it implements, the commons commit it measured, and the four verdict counts. Required by the corpus spec §1.1; not validated by anything here, because nothing here runs. |
|
||||
| [`spec/conformance-corpus.md`](spec/conformance-corpus.md) | **Normative.** How to read the corpus: what a case is, why `input.txt` is bytes rather than text, what `exact-within-scope` requires of a runtime, and how a runtime declares its table set so a case scoped outside it reads as `not-applicable` rather than as a failure. |
|
||||
| [`conformance/`](conformance/) | 90 cases. One directory per case: `input.txt` in, `expected.json` out. Ground truth. 84 cover the injection lexicon — 83 one per pattern, both seeding runtimes measured producing the same verdict on all 83, plus one variant case gating a pattern form against its predecessor. Six cover active content and are measured against the one runtime that implements that table — `not-applicable` for the other, not failing. See [`conformance/manifest.json`](conformance/manifest.json). |
|
||||
| `spec/decode-pipeline.md` | **Planned, still not shipped as of v0.4.1.** The decode order, in RFC 2119 language. Two runtimes that decode in different orders will disagree on identical input. Writing it needs the decode implementation, which is engine code and has not been supplied — and a normative spec guessed from a data dump would be worse than an absent one. |
|
||||
| `spec/decode-pipeline.md` | **Planned, still not shipped as of v0.4.2.** The decode order, in RFC 2119 language. Two runtimes that decode in different orders will disagree on identical input. Writing it needs the decode implementation, which is engine code and has not been supplied — and a normative spec guessed from a data dump would be worse than an absent one. |
|
||||
| [`docs/extraction-plan.md`](docs/extraction-plan.md) | Informative: where each file was seeded from, and what v0.1.0 promised. |
|
||||
| [`docs/lexicon-port-divergence.md`](docs/lexicon-port-divergence.md) | Informative: a measured disagreement between two ports of the injection lexicon — 13 patterns that behave differently, in both directions. Most of it is still open, and the two rows that closed in v0.4.0 closed because the runtime that owns the value decided, not because this document found them wrong. |
|
||||
|
||||
Every JSON file carries a top-level `version`. Every normative specification carries a
|
||||
`Status: normative` marker. Rows marked **Planned** are named here because the layout is
|
||||
part of the contract, but the file does not exist yet — they are not links, and nothing in
|
||||
v0.4.1 depends on them.
|
||||
v0.4.2 depends on them.
|
||||
|
||||
Each data file records its own provenance and, in `verified`, how strongly it is backed.
|
||||
`calibration/calibration.json` is currently the one file that says `false`: it was
|
||||
|
|
@ -150,6 +150,19 @@ so the gap is visible rather than inferred.
|
|||
- **The homoglyph map is finite.** Confusable coverage is a long tail; absence from the map
|
||||
is not evidence a character is safe.
|
||||
|
||||
## Contributing
|
||||
|
||||
[CONVENTIONS.md](CONVENTIONS.md) is the whole rule set a change here is held to: the charter
|
||||
(nothing runs, and why that is load-bearing rather than fussy), the file conventions, when a
|
||||
detection value is allowed to move, how the two version numbers work, and the four offline
|
||||
checks that stand in for the CI this organisation does not have.
|
||||
|
||||
It also answers the question the forge surface raises on its own: **pull requests are switched
|
||||
off, deliberately.** This repository is vendored into independent runtimes that pin a tag, so a
|
||||
change to detection data changes what they *find* — that has to be coordinated with each
|
||||
consumer before it exists, which a merge button cannot do. Fork-and-own is the supported path;
|
||||
a wrong entry is reported privately.
|
||||
|
||||
## Reporting a wrong entry
|
||||
|
||||
A wrong code point or a mis-escaped regex here is a silent false negative in every runtime
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue