99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 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.
|