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