docs: the Craft Register — the line's engineering doctrine

[hartsock]

Summary

Adds docs/CRAFT.md — the Craft Register: the engineering and structural doctrine of the line, as a companion to the Charter. The Charter says what the system must guarantee to stay non-Demiurgic (the six invariants + Reach). The Craft Register says how the code that implements those guarantees is built so it stays legible, testable, and refusable.

Why

The values/safety doctrine has a canonical home here; the craft doctrine did not. Laws the whole line already works by — loosely-coupled/functionally-cohesive, the three Cs, composition-roots-are-manifests, freeze-minimally, law-minimalism, name-properties-pin-at-the-edge, TDD + the regression rule, coverage/test-separation/least-code, keep-files-small, one-issue-one-PR, zero-warnings, hooks-mirror-pipelines — were scattered across per-repo agent instructions, working notes, and memory. This gives them one citable, versioned home, owned by no product and cited by all, in the Charter's own two-register spirit.

What's in it

14 laws across four families (Structure · Freeze-and-law · Craft · Flow), each with a normative statement, a rationale, and — where one exists — the Charter invariant it serves. The mapping is the interesting part: several craft laws are the mechanical face of an invariant:

• a regression test is a scar (metabolized failure kept as first-class state)
• a blocking quality gate (zero-warnings, coverage floor) is a refusal made mechanical
• a self-describing identifier (multihash, not a bare "sha256") is provenance
• a manifest root / minimal facade is writ — least exposed surface is least authority

Laws that are pure buildability with no safety invariant behind them say so, rather than forcing a link. The register closes by submitting to the same falsification discipline as VALIDATION.md: any craft law whose removal costs nothing should be cut.

README gains a pointer to it under "How the invariants get built."

Test plan

Docs-only — no crate touched. just check (fmt + clippy -D warnings + test) runs green via the pre-push hook.

🤖 Generated with Claude Code

[hartsock]

Review from the gnuc build-farm side, with this week's work as the evidence base. The register reads true — every law here is one the grind actually operated under, and the invariant mappings are the honest kind (saying "pure buildability" where no safety story exists is exactly right). Two folds from lived doctrine before this freezes:

1. Missing law candidate (family III): the characterization net. No refactor lands without a behavior-pinning net over the product boundaries — and every gate must be shown to fail. This is as load-bearing as TDD in practice and it's absent from the register. Evidence from this week: the newt golden masters (newt-agent#1319) pinned the ACP reply, the MCP catalog, and the help surface before the god-file decomposition began, with three disciplines that deserve normative status: a missing golden fails (never silently passes), every master double-captures per run (a nondeterministic gate cannot be baselined), and golden_negative_controls proves every stored gate rejects a perturbed expectation. Four consecutive carves (#1326/#1328/#1329/#1330) then ran byte-identical against it. The negative-control half already exists in the line's own words — grade-548.sh: "an instrument that reports success is worthless until you have watched it report failure" — and maps cleanly: the net serves novice (fresh eyes can restructure safely because behavior is pinned), the negative control is refusal exercised on the gate itself. Without this law, "zero warnings" and "coverage" gate the code while nothing gates the gates — which is the repo-documented pathology (gates that pass while nothing changed).

2. Sharpening for "Name properties, pin at the edge": a requirement names the API floor it compiles against. The bridle 0.7.11 incident is the perfect rationale example: tool-shell used the brush-ocap-core 0.5.1-only interceptor API but declared "0.5" — a downstream resolver holding 0.5.0 satisfied the requirement and a published crate failed to compile (broke newt's mesh contract job on every PR; fixed by naming the floor in 0.7.12). Pin-at-the-edge includes minimum edges: a version requirement is an identifier that must self-describe the API it needs, or the pin is fiction.

Both are offered as folds, not blockers — the register's own falsification clause applies: if the characterization-net law's removal costs nothing, cut it; this week it would have cost four refactors their proof.

Meanwhile I'm folding citations outward: newt's CLAUDE.md and the two law-style specs (semantic-cheat.md, ide-project-model.md) will cite docs/CRAFT.md as the canonical home rather than restating, per the register's own purpose.