open-standards/CLAUDE.md

# open-standards — Rules for Claude

This is the Transaction-Science **open-standards monorepo** (Apache-2.0 code + CC-BY spec text). The standards live here as **subdirectories, not separate repos** — including **wai**, jouleclaw, jcp, mesh, sandbox, map, aac (access), sense, openpay, smart-byte, eoc, arl, joulecontract, joule-code, joule-ui, joule-os, joulehook, jouledesk, jouletable, and proof. A change to any one standard is a commit in this one repo.

## Sovereign git & CI (canonical — READ FIRST)

**Canonical git home is the sovereign Forgejo forge at https://git.transaction.science/Transaction-Science/open-standards.** GitHub and Codeberg are **downstream mirrors that update automatically on every commit** — **push only to the forge** (`origin` on dev already points there; GitHub is preserved as the `github-backup` remote). Never treat GitHub as the source of truth: no "View on GitHub" as canonical, and no `github.com` in any standard's README, install snippet, or public site copy — name **`git.transaction.science`**.

- This is a fast-moving, multi-worktree repo; `main` moves under you. Land work by cherry-picking onto a fresh worktree off `origin/main`, build-verify, then rebase/retry the push (the forge auto-mirrors on success).
- **CI is Forgejo Actions** (GitHub-Actions-compatible) on self-hosted runners: use `runs-on: macos` / `linux` — never `ubuntu-22.04`, `windows-2022`, `namespace-*`, or bare `self-hosted`. Publish releases via the Forgejo release API, not `gh release`. A repo needs its Actions unit enabled before workflows run.
- **Buildable targets (all on live self-hosted runners):** macOS **aarch64 + x86_64** (`runs-on: macos`), Linux **x86_64** (`runs-on: linux`) and **arm64** (`runs-on: linux-arm64` — a native arm64 Linux VM on the Apple Silicon dev Mac; arm64 guest on an arm64 host is virtualization, not emulation), Windows **x86_64** (`runs-on: windows`). **Windows-arm64 is the only gap** — the same VM trick would close it (needs a licence/ISO). Linux-arm64 builds with `CC=gcc-14` + `REMOTE_SERVER_TARGET=aarch64-unknown-linux-gnu`; the x86_64 leg uses clang.

Dev-machine push/upload specifics (LAN push-routing, credential, release-asset upload) are in the global operator notes (`~/.claude/CLAUDE.md`).

## Add files of your own; insert beside the entry you build on

Many sessions' branches are open at once, and every line two of them append to is a conflict that serialises their merges. A change adds files of its own where the tree lets it (its changelog entry, and its lists in `wai-conformance.yml`), and inserts beside the entry it builds on in a file that stays shared:

- **WAI's changelog:** one new file per change, `wai/changes/<yyyy-mm-dd>-<slug>.md`, holding the entry exactly as `wai/CHANGELOG.md` would ([`wai/changes/README.md`](wai/changes/README.md)). Never edit the head of `wai/CHANGELOG.md`; a release renders the files into it (`scripts/changelog-assemble.py --write`). The repository checks fail a pull request that changes `wai/`, adds or edits no entry file directly in `wai/changes/`, and has no commit message whose trailer block holds the line `Changelog: none`, exactly (a release, which renders the files and removes them, passes); one opened since the check reached main (the merge that brought it in) that adds its entry to the head of `wai/CHANGELOG.md` instead fails too.
- **`wai-conformance.yml`:** a new step of the independent verifiers is a file of `.github/wai-conformance/verifiers/`, a new cargo-class corpus a file of `.github/wai-conformance/corpora/`, and a new fast-integer-kernel test tags itself (`// wai-conformance: int-kernels`). The workflow's feature lists, test lists, steps and corpora, and the paths its gate runs on, are derived from them; add no line to the workflow for them, unless a step's `# paths:` names a file under none of the trigger's paths (`check` names it). `python3 scripts/wai-conformance-lists.py dry-run` prints what runs; `wai/CONTRIBUTING.md` states the header keys.
- **Files still shared** (`wai/wai-rs/Cargo.toml`'s features and targets, `[[test]]` entries included, `wai/wai-rs/src/lib.rs`'s `mod` lines, the tables of `codecs/registry.rs`, `wai/.gitattributes`, and the corpus table of `wai/live-conformance/README.md` with the verifier commands under it) are grouped by topic, not sorted: insert beside the entry yours builds on, never at the end, and never re-sort. A corpus whose bytes must never be converted gives its own directory a `.gitattributes` (`* -text`), as `wai/pin-conformance/` and `wai/live-conformance/scene/` do, rather than a line in `wai/.gitattributes`. Generated files (`wai/registry/capabilities.json`, `wai/REGISTRY.md`'s table, `wai/vocab/v2.*`) are sorted by the export: regenerate them, never merge them by hand.

## Framing rules (public surfaces)

- Describe every standard **on its own terms** — ingest open/private efforts into permissive-licensed Rust; **no competitive / SWOT framing**, no comparisons, no us-vs-them. Copy is self-referential only.
- Don't manufacture cross-project dependencies; shared neutral primitives ≠ "X is built on Y." Verify before asserting a link.
- No vanity metrics (crate/test counts, LOC, "N+ adapters") — describe the shape, not the size.