ww/CLAUDE.md

1. This is a project for ww programming language
2. ww is a programming language aiming for Hare + CSP, no GC
3. cmd/ is the C bootstrap toolchain (wcc frontend lib, w6c/w6a/w6l per-arch, ww driver); selfhost/ is the ww reimplementation
4. All C code must strictly align with plan 9 coding style
5. lib/ is the standard library; follow Hare APIs (signatures, layout, error idioms) — consult ref/hare/ before designing new modules. Package declaration form is Go-style explicit package foo; and imports use import foo; (executables declare package main;) per language design (rob-pike + plan-9 sensibility); lib/ API surface still mirrors Hare.
6. ref/hare and ref/plan9front are read-only references — consult before inventing data shapes or syntax
7. No workarounds. If a bug forces a workaround, STOP and report with a precise repro. Document any retained divergence at the site with a pointer to the filed task. Never silent.
8. Comments are WHY-only. Never narrate WHAT the code does — names carry the WHAT. Comment only non-obvious WHY: a constraint, a divergence from a reference, a citation to a filed task.
9. Hare-fidelity over convenience. No ad-hoc extensions, renames, or convenience wrappers in lib/. Cite ref/hare// for every signature ported. Carve-out: the Hare _unsafe suffix convention is dropped wholesale (ww is C/Plan-9-lineage, an unmanaged systems language — no GC, no "safe" baseline to be unsafe relative to). bytes→str is a pure reinterpret (strings.frombytes, renamed from Hare's fromutf8_unsafe); validation is opt-in via utf8.validate(b)? at the IO source, never wrapped per-construction. Rationale: ref/hare/strings/utf8.ha:10,22 — the suffix flags Hare's managed-bytes-safety axis, which ww doesn't have. The honest name (frombytes) reserves fromutf8 for a future true validating helper. Carve-out: lib/ tests use Go's external-test-package idiom (package <mod>_test; + import <mod>;), a sanctioned Go-over-Hare departure — ww hard-rejects self-import (full Go), and Hare's same-package @test colocation now has a ww analogue: in-package white-box @test files (package <mod>;, colocated) are sanctioned alongside the external black-box package <mod>_test; split — Go's foo/foo_test model — now that the non-T @test drop landed (#6, harec check.c:3941, 08a76cf; #5 closed). Rule 5/9 binds lib/ API surface, not test-authoring style. Ref: Go foo_test convention; task #16.
10. Symmetric stages. cstage and wwstage MUST emit byte-identical asm for the same input. When inference power differs, align the richer side DOWN to the leaner side, not the other way.
11. Split commits when they bundle unrelated concerns. Bisect-cleanliness is the default. Multi-fix commits need a body paragraph explaining why they couldn't split.
12. Simple data, simple algorithms. Sea-of-stars style. Mirror Hare's structural choices over clever alternatives.
13. No hardcoded size literals in size-computation contexts. Always route through the type table (tinfo.size / Type.size / ty_*->size / size(T) / primtypesize / tyslicesize). Per Drew's framing of Hare's discipline. make sizelint enforces and runs as a dep of make test. Exemptions documented inline with // sizelint-ok: <reason> (ww) or /* sizelint-ok: <reason> */ (C). Optional local enforcement: ln -s ../../tools/sizelint .git/hooks/pre-commit.
14. Test targets. Inner-loop dev runs make test-unit (~3.8s, skips wwstage-driver tests: 950, 990–997). Pre-commit runs make test-commit (content-keyed tier: the 10 pure gates — 950, 989_lib_byteid, 990–997 — report cached when the input key matches the last green full run; ~25s on a hit, full gate run on any miss; key = stage-binary md5s + tracked selfhost/lib/cmd/rt/test/examples sources + harness + Makefile; cache in out/.testcache, wiped by make clean; mtime keys and partial keys are vetoed). Pre-push runs full make test (~3:40 measured at f940072, all 353 incl. byte-id gates) — the bootstrap-correctness gate, never cached; never push without it green. test-unit is a fast confidence check on unit-level code (stages, stdlib, smoke); a green test-unit doesn't prove bootstrap, only that the unit set is intact. New wwstage-driver tests are no longer confined to the 950/990–997 range for correctness: T3 (test-perf arc) made every build's intermediates follow its OUTPUT (ww build -o <stem> / ww run's per-pid temp) instead of landing next to every traversed source, so concurrent driver builds no longer race on selfhost/cmd/<tool>/main.{s,combined.ww,o} fixtures — the phase-2 byte-id group (incl. 993/995/950) now runs fully parallel. The 950/990–997 NNN prefixes still drive test/run's phase-2 membership, the make test-unit skip set, and the make test-commit cache set, so a heavy 43k self-compile gate should still use that range to be skipped by test-unit and cached by test-commit; a light wwstage-driver test may live at any NNN (just -o-redirect its intermediates off the source tree).