muse-attributes.md
markdown
| 1 | # .museattributes Reference |
| 2 | |
| 3 | `.museattributes` is a per-repository configuration file that declares merge strategies for specific track patterns and musical dimensions. It lives in the repository root, next to `.muse/`. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Purpose |
| 8 | |
| 9 | Without `.museattributes`, every musical dimension conflict requires manual resolution, even when the resolution is obvious — for example, the drum tracks are always authoritative and should never be overwritten by a collaborator's edits. |
| 10 | |
| 11 | `.museattributes` lets you encode that domain knowledge once, so `muse merge` can skip conflict detection and take the correct side automatically. |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## File Format |
| 16 | |
| 17 | One rule per line: |
| 18 | |
| 19 | ``` |
| 20 | <track-pattern> <dimension> <strategy> |
| 21 | ``` |
| 22 | |
| 23 | - **`track-pattern`** — An [`fnmatch`](https://docs.python.org/3/library/fnmatch.html) glob matched against the track name (e.g. `drums/*`, `bass/electric`, `*`). |
| 24 | - **`dimension`** — A musical dimension name or `*` (all dimensions). Valid dimension names: `harmonic`, `rhythmic`, `melodic`, `structural`, `dynamic`. |
| 25 | - **`strategy`** — How to resolve conflicts for matching track + dimension pairs (see table below). |
| 26 | |
| 27 | Lines starting with `#` and blank lines are ignored. Tokens are separated by any whitespace. The **first matching rule wins** — order matters. |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ## Strategies |
| 32 | |
| 33 | | Strategy | Meaning | |
| 34 | |----------|---------| |
| 35 | | `ours` | Take the current branch's version. Skip conflict detection. | |
| 36 | | `theirs` | Take the incoming branch's version. Skip conflict detection. | |
| 37 | | `union` | Attempt to include both sides (falls through to three-way merge). | |
| 38 | | `auto` | Let the merge engine decide (default when no rule matches). | |
| 39 | | `manual` | Flag this dimension for mandatory manual resolution. Falls through to three-way merge. | |
| 40 | |
| 41 | > **Note:** `ours` and `theirs` are the only strategies that bypass conflict detection. All others participate in the normal three-way merge. |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## Examples |
| 46 | |
| 47 | ### Drums are always authoritative |
| 48 | |
| 49 | ``` |
| 50 | # Drums are owned by the arranger — always keep ours. |
| 51 | drums/* * ours |
| 52 | ``` |
| 53 | |
| 54 | ### Accept collaborator's harmonic changes wholesale |
| 55 | |
| 56 | ``` |
| 57 | # Incoming harmonic edits from the collaborator win. |
| 58 | keys/* harmonic theirs |
| 59 | bass/* harmonic theirs |
| 60 | ``` |
| 61 | |
| 62 | ### Explicit per-dimension rules with fallback |
| 63 | |
| 64 | ``` |
| 65 | # Drums: our rhythmic pattern is never overwritten. |
| 66 | drums/* rhythmic ours |
| 67 | |
| 68 | # Melodic content from the collaborator is accepted. |
| 69 | * melodic theirs |
| 70 | |
| 71 | # Everything else: normal automatic merge. |
| 72 | * * auto |
| 73 | ``` |
| 74 | |
| 75 | ### Full example |
| 76 | |
| 77 | ``` |
| 78 | # Percussion is always ours. |
| 79 | drums/* * ours |
| 80 | percussion * ours |
| 81 | |
| 82 | # Harmonic collaborations from the feature branch are accepted. |
| 83 | keys/* harmonic theirs |
| 84 | strings/* harmonic theirs |
| 85 | |
| 86 | # Structural sections require manual sign-off. |
| 87 | * structural manual |
| 88 | |
| 89 | # Fall through to automatic merge for everything else. |
| 90 | * * auto |
| 91 | ``` |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## CLI |
| 96 | |
| 97 | ``` |
| 98 | muse attributes [--json] |
| 99 | ``` |
| 100 | |
| 101 | Reads and displays the `.museattributes` rules from the current repository. |
| 102 | |
| 103 | **Example output:** |
| 104 | |
| 105 | ``` |
| 106 | .museattributes — 3 rule(s) |
| 107 | |
| 108 | Track Pattern Dimension Strategy |
| 109 | ------------- --------- -------- |
| 110 | drums/* * ours |
| 111 | keys/* harmonic theirs |
| 112 | * * auto |
| 113 | ``` |
| 114 | |
| 115 | Use `--json` for machine-readable output: |
| 116 | |
| 117 | ```json |
| 118 | [ |
| 119 | {"track_pattern": "drums/*", "dimension": "*", "strategy": "ours"}, |
| 120 | {"track_pattern": "keys/*", "dimension": "harmonic", "strategy": "theirs"}, |
| 121 | {"track_pattern": "*", "dimension": "*", "strategy": "auto"} |
| 122 | ] |
| 123 | ``` |
| 124 | |
| 125 | --- |
| 126 | |
| 127 | ## Dimension Implementation Status |
| 128 | |
| 129 | The five dimension names are all valid in `.museattributes` and are parsed correctly. However, not all dimensions are currently wired into `build_merge_result`. The table below shows the current state: |
| 130 | |
| 131 | | Dimension | Status | Planned event-type mapping | |
| 132 | |-----------|--------|---------------------------| |
| 133 | | `melodic` | **Reserved — future** | Note pitch / pitch-class resolution | |
| 134 | | `rhythmic` | **Reserved — future** | Note start-beat / duration resolution | |
| 135 | | `harmonic` | **Reserved — future** | Pitch-bend event resolution | |
| 136 | | `dynamic` | **Reserved — future** | CC and aftertouch event resolution | |
| 137 | | `structural` | **Reserved — future** | Section / region-level merge | |
| 138 | |
| 139 | > **Current behaviour:** `build_merge_result` performs a pure three-way merge for all event |
| 140 | > types (notes, CC, pitch bends, aftertouch) regardless of any `.museattributes` rules. |
| 141 | > A rule such as `drums/* rhythmic ours` is parsed and stored correctly but has **no |
| 142 | > effect on the merge outcome today**. All five dimensions are reserved for a future |
| 143 | > implementation that will wire each event type to its corresponding dimension strategy. |
| 144 | > |
| 145 | > Writing dimension-specific rules is safe — they will take effect automatically once |
| 146 | > the merge engine is updated. |
| 147 | |
| 148 | --- |
| 149 | |
| 150 | ## Behaviour During `muse merge` |
| 151 | |
| 152 | 1. `muse merge` calls `load_attributes(repo_path)` to read the file. |
| 153 | 2. `resolve_strategy(attributes, track, dimension)` is available for callers to query the configured strategy for any track + dimension pair. |
| 154 | 3. **Dimension strategies are not yet applied inside `build_merge_result`.** All event types currently go through the normal three-way merge regardless of the resolved strategy. |
| 155 | 4. When dimension wiring is complete: if the resolved strategy is `ours`, the left (current) snapshot will be taken without conflict detection; if `theirs`, the right (incoming) snapshot will be taken; all other strategies (`union`, `auto`, `manual`) will fall through to the three-way merge. |
| 156 | |
| 157 | --- |
| 158 | |
| 159 | ## Resolution Precedence |
| 160 | |
| 161 | Rules are evaluated top-to-bottom. The first rule whose `track-pattern` **and** `dimension` both match (using fnmatch) wins. If no rule matches, `auto` is used. |
| 162 | |
| 163 | --- |
| 164 | |
| 165 | ## Notes |
| 166 | |
| 167 | - The file is optional. If `.museattributes` does not exist, `muse merge` behaves as if all dimensions use `auto`. |
| 168 | - Track names typically follow the format `<family>/<instrument>` (e.g. `drums/kick`, `bass/electric`). The exact names depend on your project's MIDI track naming. |
| 169 | - `ours` and `theirs` in `.museattributes` are **positional**, not branch-named. `ours` = the branch you are merging **into** (left / current HEAD). `theirs` = the branch you are merging **from** (right / incoming). |