CLAUDE.md: the entry point an agent actually reads

The handoff was comprehensive as a document and unreachable as a
bootstrap. An agent starting cold on a new machine reads CLAUDE.md
automatically; it would have to be told to open spec/HANDOFF_2026-08-07.md,
and the rules this work actually ran on lived only in conversation and
in an agent memory directory that git does not carry.

So the method is now a tracked file and the handoff is the state it
assumes. CLAUDE.md carries what an agent must not learn by discovering
it: contracts are frozen after ratification and defects are reported
rather than patched in place; the touch table is the staging allowlist,
with the two files that keep escaping it named; mutation-first, and a
compile error is not a test failure; verify subagent claims by re-running,
because agents here have misattributed failures and guarded the wrong
path; never git add -A, never reset/checkout/stash against a tree another
session may share; never cargo fmt --all, since it crosses into spikes/
through path dependencies; xelatex not pdflatex; the green baseline; and
the live no-canonical-base constraint that makes correct refusals look
like bugs until P13-S27 lands.

The handoff gains §0a pointing at it, and saying plainly what an agent
does not inherit — the memory directory and the conversation — so a thin
inheritance is stated rather than papered over.

The editor/T4 track's half of these rules is recorded as observed from
its contracts; that session should review it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QjsEnYhm1gPpf6ii2iFxFV

CLAUDE.md

@@ -0,0 +1,98 @@
+# Epiphany — working agreements for agents
+
+FOSS music-notation platform: a specified, deterministic, CRDT-based score
+model with a LaTeX specification suite as its source of truth.
+
+## Read this first
+
+1. **`spec/HANDOFF_2026-08-07.md`** — current state of both tracks, what
+   transfers between machines, environment setup, and what to do next. Start
+   there; everything below is the standing rules that document assumes.
+2. **`spec/PASS13_CANDIDATES.md`** — the spec-track ledger. Status cells are
+   **appended to, not rewritten**, so an opener can lag the truth by several
+   rungs. Read the whole cell.
+3. The contract for whatever you are about to touch: `spec/CONTRACT_*.md`.
+
+## The two tracks
+
+| Track | Lives in | Current head |
+|---|---|---|
+| **Spec / Pass 13** — wire format, bundle, ops, text projection, the `.tex` suite | `spec/`, `crates/epiphany-{core,ops,bundle,textproj,testkit}` | P13-S27 unblocked and dispatchable |
+| **Editor / T4** — the editing seam, engraving, the toolkit spike | `spec/PLAN_EDITOR_APP.md`, `spec/CONTRACT_EDITOR_*`, `spikes/`, `crates/epiphany-{editor-core,editor-gui,engrave,layout-ir,glyphs,render-svg}` | T4 spike, round 2 built but not run |
+
+They are currently independent. **They collide when T1b opens**, because T1b
+and P13-S27 both land in `epiphany-bundle/src/bundle.rs`. Do not fly those two
+together.
+
+## How work is done here
+
+**Contracts are ratified, then frozen.** Substantive work is scoped into a
+`spec/CONTRACT_*.md` with numbered pins, tests, mutations, a touch table and a
+gate; it goes through adversarial review rounds before dispatch. **After
+ratification the pins are executed, not edited.** A defect found during
+execution is **reported, not patched in place** — if it needs a pin change,
+that is its own amendment with its own review round.
+
+**The touch table is the staging allowlist.** A file that must change but is
+not listed silently drops out of the commit. Two recurring escapees, in no
+contract's table: `crates/epiphany-testkit/tests/requirement_labels.rs` (its
+hardcoded requirement counts move whenever a `.tex` gains a requirement), and
+version literals in `.tex` prose.
+
+**Mutation-first.** Every regression test is verified by re-introducing the bug
+and **observing** the failure. Reasoning that a mutation *would* fail signs
+nothing. A **compile error is not a test failure** — a mutation that does not
+compile observed nothing. Restore by hand-editing back, never with git.
+
+**Verify subagent claims before committing them.** Re-run the tests, re-read
+the diff. Agents in this repo have misattributed failures, missed failing
+suites, and guarded the wrong code path — all found only by re-running.
+
+**Before believing a zero-result search, ask what it would miss if the claim
+were false.** Different encoding, different spelling, a propagating rather than
+constructing path, output truncated by `head`. Never conclude a universal
+negative from a piped `head`.
+
+**Guard every reachable path, not the one the spec sentence names.** Enumerate
+the public entry points into an invariant and ask which a caller can actually
+reach today.
+
+## Git
+
+- **Stage explicit paths. Never `git add -A`.**
+- **Never `git reset`, `git restore --staged`, `git checkout`, or `git stash`**
+  against the working tree — sessions have run concurrently here, and these
+  destroy work that is not yours. Undo by hand-editing.
+- Re-check `HEAD` before staging and before committing.
+- Subagents do not commit. They leave work for review.
+
+## Build and environment traps
+
+- **Never run `cargo fmt --all`.** It reaches the `spikes/` workspace through
+  path dependencies and reformats across workspaces. Use `cargo fmt -p <crate>`.
+  The `--check` form CI runs is safe; the *writing* form is not.
+- **The spec builds with `xelatex`, not `pdflatex`** — `fontspec` refuses
+  pdfTeX outright: `cd spec && latexmk -xelatex -interaction=nonstopmode <doc>.tex`.
+  Re-run until `undefined references` clears; one pass is often not enough. The
+  six PDFs are tracked and must be rebuilt when their `.tex` changes.
+- Toolchains: pinned stable **1.95.0**, MSRV floor **1.85**. The MSRV CI job
+  excludes `epiphany-editor-gui`.
+- `spikes/` is **its own workspace** — root `cargo test --workspace` does not
+  reach it. Gate it separately.
+
+## Green baseline
+
+```
+cargo test --workspace                                 # expect 1570 passing, 0 failed
+cargo clippy --workspace --all-targets -- -D warnings   # clean
+```
+
+If the count differs on arrival, reconcile that **before** starting new work —
+the mutation discipline above depends on a known-green baseline.
+
+## One live constraint
+
+Until **P13-S27** lands, **no bundle anywhere may carry a canonical base** — not
+in production, tests, or the conformance suite. Base-bearing fixtures must be
+hand-built images (see `craft_image` in `epiphany-bundle/src/bundle.rs`).
+Refusals you hit there are the design, not a bug. See handoff §1.2.

spec/HANDOFF_2026-08-07.md

@@ -14,6 +14,24 @@ tree or the documents; where a claim is second-hand, it says so.
 
 ---
 
+## §0a. If you are an agent picking this up cold
+
+Read **`CLAUDE.md` at the repo root first** — it carries the standing rules
+(contract discipline, mutation-first, the git and `cargo fmt` constraints, the
+green baseline, the one live constraint). This document is the *state*; that one
+is the *method*.
+
+Then: §4 for what to do, §1 or §2 for whichever track you are on, §3 only if the
+environment is not already working.
+
+**Two things that do not arrive via `git clone`** and that change how much you
+know: the agent memory directory (§0.3 — it holds the accumulated track notes and
+method lessons) and this session's conversation. If the memory directory was not
+restored, treat `CLAUDE.md` and this file as the whole inheritance and say so
+rather than guessing at intent.
+
+---
+
 ## §0. Transfer manifest — what `git clone` does NOT carry
 
 **The good news first, because it is most of the risk retired.** `spikes/` is