Development record · living research interface
The Shape Note Atlas
A source-faithful reader for Sacred Harp music, developed through a sequence of corpus, notation, review, and publication decisions. The current surface keeps tune lookup, source pages, playback, transposition, and review status in view.
Development record
Source fidelity accumulated in commits
The repository history moves from corpus packaging and semantic parsing through edition reconciliation, retained evidence, review publication, playback, and hosted documentation.
- Source parsing and browser smoke checks
- Edition, witness, and review semantics
- Reproducible evidence, practice controls, and docs
Context
Sacred Harp material is spread across editions, scans, indexes, recordings, and partial structured sources. A reader can find a song while still missing the evidence needed to know which edition it belongs to, whether the notation is exact, or whether a playable score is only a reference witness.
The problem was not only search
A conventional catalog makes every result look equally settled. That is dangerous for a source-sensitive repertoire: a page scan, an exact edition score, a reference witness, and a review draft may all be useful, but they are not interchangeable.
The requirement became a research tool that could be useful before the corpus was complete. Uncertainty had to remain visible in the interface instead of disappearing into a maintenance note.
The design question
How do you make a reader more useful without making it more confident than its sources justify?
The answer became a boundary-first product model. Source links and scans stay authoritative for what they actually show. Structured scores can drive playback only when their status supports it. Review drafts can be inspected and practiced in the right context, but they do not silently become the edition engraving.
Project timeline
Selected checkpoints from the public Shape Note Atlas repository. The commit trail is compressed into the work it represents; it is not an exhaustive log.
-
Make the corpus inspectable
Source-semantic parsing, source-health audit tooling, and browser smoke discovery established the first inspectable workflow around the packaged corpus.
Result: data behavior and verification became part of the build rather than a final manual check.
-
Separate editions from witnesses
Edition reconciliation, witness provenance, and bounded startup checks made it possible to distinguish what a source proves from what another witness merely suggests.
Result: the interface could preserve source meaning instead of flattening records into a single status.
-
Make evidence reproducible
Validation prerequisites, retained evidence bundles, and OCR/PDF checks moved source review from one-off work into tools that could be run and restored.
Result: a passing build carried a more useful receipt than “it rendered.”
-
Publish reviewable notation
Correctable SH2025, New Salem, and Something New drafts entered the surface with their review status intact instead of being presented as final engraving.
Result: partial progress became publishable without pretending that review was complete.
-
Extend identity and practice
Social Harp page identities, corrected Afton alignment, and repeat-aware cancellable playback extended the corpus while keeping review and practice separate.
Result: the reader became more useful without making the evidence model less strict.
-
Document the system around the surface
A hosted documentation route, topical guide pages, and a bundled overview screenshot made the operating model easier to inspect beyond the application itself.
Current state: the Atlas remains a living research interface, with source coverage and review work still in progress.
System
A source model with explicit evidence classes
- Searchable tune and page lookup across the local corpus.
- Source-linked notation and page-image evidence.
- Available-part playback when a structured score is available.
- Key-aware transposition with an explicit source-key path when the source does not encode one.
- Separate coverage, source, transcription, and human-review ledgers.
- A packaged macOS reader sharing the browser dashboard's source of truth.
The application is a Vite/React surface backed by a checked-in corpus index and lazy score assets. The source-health and review ledgers give the interface a way to say why a record is usable, incomplete, blocked, or still waiting for a person.
Bounded agent work
This project is developed through work packets split by evidence and behavior: source acquisition, edition and key reconciliation, review semantics, score fidelity, four-shape verification, browser audio, startup and deployment, and reproducible validation each have a defined boundary.
The shared rules matter as much as the division of labor. Source scans and provenance manifests are evidence. Review-only outputs cannot promote themselves into canonical notation. A blocked result carries a specific reason. Each worker returns focused checks, files, counts, and remaining uncertainty so progress can be combined without flattening the distinctions the reader is meant to preserve.
How the boundary emerged
- A missing score remains missing instead of being replaced with a different edition.
- A reference witness stays labeled as a reference witness.
- A review draft can be useful without being called verified.
- A passing render does not establish source identity or edition fidelity.
Current state
A research instrument with visible limits
The Atlas brings lookup, source context, notation availability, playback, transposition, and review status into one workflow without collapsing them into a single confidence label. That makes it possible to use the tool while the corpus is still growing and to see where human attention is actually needed.
The larger lesson is that provenance is not only documentation. In this system, provenance changes what the interface is allowed to do.
Artifacts