# CONTRIBUTING.md · versecafe/strata

[View on GitCafe](https://git.cafe/versecafe/strata/blob/45a26bc126dbc37bc971405fef8e8a95ccca0b94/CONTRIBUTING.md)

Repository: [versecafe/strata](https://git.cafe/versecafe/strata)

Visibility: public

Requested revision: 45a26bc126dbc37bc971405fef8e8a95ccca0b94

Requested commit: 45a26bc126dbc37bc971405fef8e8a95ccca0b94

Commit: 45a26bc126dbc37bc971405fef8e8a95ccca0b94

Blob: dfb3c49d221ce809f113ac5289a762f80205a8df

Size: 1883 bytes

[Immutable source](https://git.cafe/versecafe/strata/blob/45a26bc126dbc37bc971405fef8e8a95ccca0b94/CONTRIBUTING.md?format=markdown)

````
# Contributing to strata

Design authority lives in `../proposal/` — start with `01-design-principles.md`
(P-1..P-11) and the decisions register `../proposal/decisions.md` (D-001–D-080).
Code that contradicts a settled decision is wrong even if it works.

## Promotion rule: probes → crates

Probe code (`../probes/`) is **rewritten with its tests carried, never
copied**. A promotion PR states which probe it promotes; the probe's test
corpus and gap ledger come along as the crate's test suite. Probe code itself
is a design artifact, not a dependency.

## Invariants that gate merges

- **D-053 fuzz suites**: fmt/parse invariants are CI-fuzzed from day one —
  idempotence (`fmt∘fmt = fmt`), lossless round-trip (`text(tree) == input`,
  including comment count and anchors), parse-error input returned untouched,
  cross-platform determinism.
- **No-panic**: tool crates must not panic on any input; malformed input yields
  P-9 diagnostics (`strata-diag/0`, see `docs/diagnostics.md`), never a crash.
- **Determinism (P-6)**: no wall clock, no env reads, no iteration-order
  nondeterminism, no HashMap ordering in any output path. `cargo xtask ci`
  runs the test suite twice and byte-compares generated artifacts; a diff
  fails the build.

Run the full gate locally before pushing:

```
cargo xtask ci                 # whole workspace
cargo xtask ci -p strata-cli   # scoped, while sibling crates are mid-build
```

(fmt-check → clippy `-D warnings` → tests ×2 + artifact byte-compare.)

## Spec divergences

If implementation forces a divergence from `../proposal/`, do **not** silently
adapt: record it in a `SPEC-ISSUES.md` at the crate root (what diverged, why,
which proposal section/decision it touches). These files feed back into
`../proposal/` — a divergence is resolved either by fixing the code or by a
decisions-register event, never by drift.

````