# Song Lab research contract

Inspired by [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
Raw evidence → linked, evolving synthesis → experiments and decisions.

- `raw/`: immutable dated source inventory, original artifact hashes, branch/head/dirty state,
  exact provider/task/audio identifiers and failures. New ingestion adds a new snapshot.
- `references/`: one page per liked song; measurements, time anchors, auditory evidence and limits.
- `concepts/`: parameter definitions, mechanisms, competing explanations and contradictions.
- `experiments/`: versioned hypotheses, frozen inputs/gates/budgets, outcomes and next decisions.
- `index.md`: navigation and open questions. `log.md`: append-only research decisions.
- `research.json`: authored, linked synthesis. `analysis.json`: reproducible diagnostic results.

Every claim has an evidence class: **measured**, **reported listening**, **owner preference**,
**hypothesis**, **unresolved**, or **provider failure**. No invented probabilities or 10/10
scores. Historical acceptance is never changed by a new diagnostic. Missing evidence is unknown.
Repeated receipts for the same task/take are not independent samples. Worktree copies are deduplicated.

## Experiment rules

Freeze hypothesis, manipulated parameter, actual provider field, range/levels, invariant inputs,
measurement, listening task, decision rule, budget and stop conditions before spending. Archive both
returned takes. Lack of a documented seed means generations are stochastic; one pair is exploratory.
Use neutral randomized A/B, identical playback gain treatment, repeated judgments, and owner preference
as the taste label. The five liked references are positives, not a causal training set.

At three occurrences of the same criterion in one experiment family, flag a review. At four,
require an explicit diagnosis before the next batch: bad audio, wrong prompt control, evaluator defect,
or overly narrow prospective criterion. A plateau alert does not loosen the active contract.
Change a rule only in a new version with a reason and a rerun of the liked-reference checks.

## Audio mode and authority

Audio mode: song; singing-cartoon-vsl blueprint and Music DNA plus all three references applied.
This lab researches music; it commissions no pictures. Historical product claims remain quoted ad
content, not reusable facts. Generation proposals preserve approved product text and references.
New paid experiments have a separate frozen spending ceiling; a pending ceiling permits only local
analysis. Never adopt another session's generation or spending authority as this lab's authority.