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). 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.