diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..10f63da --- /dev/null +++ b/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 `. + 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 .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. diff --git a/spec/HANDOFF_2026-08-07.md b/spec/HANDOFF_2026-08-07.md index 1a8cd9f..48c1190 100644 --- a/spec/HANDOFF_2026-08-07.md +++ b/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