[Spec] Per-arrangement difficulty rating on arrangements[] (1.13.0, additive)

[topkoa]

Split from #36 §1. The keystone library gap: no per-song/per-arrangement difficulty a user can sort, filter, or see before opening the chart. The only existing difficulty signal is the phrase-level max_difficulty ladder (§6.7), which lives inside the chart and only in phrase-aware packs.

Proposal

Add an OPTIONAL difficulty field to each arrangements[] entry in manifest.yaml (§5.2).

arrangements:
  - id: lead
    name: Lead
    file: arrangements/lead.json
    difficulty: 6        # OPTIONAL

Why the manifest, not the arrangement JSON (§6): the manifest is the index (§2.2). Library sort/filter must work without parsing every chart file. Per-arrangement placement also gives cross-instrument parity for free — bass / lead / rhythm keep distinct ratings.

Why spec, not just app: difficulty travels with the pack so every host/importer agrees and it survives re-scan. It's metadata about the chart, not the user (passes §9.5).

Mechanics

• Additive OPTIONAL key → MINOR bump → feedpak_version 1.12.0. Older Readers ignore it (§4.2, §9.4).
• Schema: add difficulty to the arrangementEntry def in manifest.schema.json (additionalProperties: true already keeps old packs valid; add an explicit constraint).
• Distinct from phrase max_difficulty (§6.7): that stays the in-chart ladder; this is a single library-facing whole-chart scalar. Document the two as orthogonal.

Open questions (need direction)

1. Scale. Recommend integer 1–10 (absolute, sortable, derivable, parity with the integer max_difficulty). Alternative: coarse beginner/intermediate/advanced enum (simpler, weaker sequencing). Pick one — drives the schema constraint.
2. Authored vs derived vs both. A Writer could derive it from note density + tempo (§6.10) + phrase-ladder span (§6.7) + tuning distance. Recommend: store the resolved integer; allow an authored value to override a derived one. If provenance matters, reuse the existing {engine, model, version} pattern (optional difficulty_source), not a new shape.
3. Relationship to max_difficulty — confirm orthogonal (above).

Blocks: nothing additive. The scale decision (Q1) is the only thing gating the spec PR.

[ChrisBeWithYou]

Distilling the decision on the three Open Qs. First a naming fix, because it's the thing that kept tripping us up — and it matters for who reads this.

Naming (for both spec-readers and non-technical charters/players). "Difficulty" was quietly doing three jobs at once: (1) the in-chart note-thinning ladder, (2) the library "how hard is this song" number, and (3) who set that number. When concepts that rub against each other share one word, it's confusing for everyone — and worse for the charters and players who meet these words in the UI, not the spec. So each gets a plain, distinct word:

• Difficulty rating — the library number (this issue's field). What people already mean by "how hard is this song."
• Practice ladder — the in-chart max_difficulty/levels (§6.7). It's a learning aid that thins the chart down so you can build up to the full part — not a rating. (We keep the field name max_difficulty; we just describe it as the practice ladder so it stops competing for the word "difficulty.")
• Author-set vs estimated — where the rating came from: a charter set it, or the app estimated it.

Simple, distinct words stay accessible to a kid learning their first song and unambiguous in the spec. The field name reflects it: difficulty_rating (not bare difficulty), so it never reads as a synonym for max_difficulty.

Q1 — Scale: store an anchored integer 1–10, display it as coarse bands. Not a 3-bucket enum: you can always derive a Beginner/Intermediate/Advanced band from a 1–10 for browse, but you can never recover granularity from a stored enum — and the fine number is what powers "order within a level" and "next step up." Anchoring matters more than the bucket count (an unanchored 1–10 drifts and stops being comparable across authors), so define anchors in the spec, read per-instrument (a bass 6 and a guitar 6 are each "6 on their own instrument," not equal physical demand — the per-arrangement placement gives us this):

• 1 — first-week player: a few open chords / single notes, slow, no shifts.
• 5 — comfortable hobbyist: moderate tempo, full chord vocabulary, some shifts, one non-exotic technique.
• 10 — virtuosic ceiling: fast, dense, full-neck, advanced technique and/or real stamina.

Guidance: rate by the hardest part (documented exception for a short hard passage in an otherwise easy song), half-points allowed, and don't derive it from accuracy/recognition scores (a short brutal section drowns in a long easy song's high accuracy). The host shows bands; it never shows the raw integer as a chased "grade." (This mirrors what the closest comparable custom-chart community ended up hand-building — an anchored 1–10 in named bands, rated by the hardest part — because their catalog otherwise had no sortable difficulty signal.)

Q2 — Author-set vs estimated: support both; author-set wins; estimated fills the gap. A charter can set the difficulty rating — that's the source of truth, it travels in the pack, and an app must never auto-overwrite it. Where no one set it, the app shows an estimate computed from the chart (the practice ladder's peak + note density / tempo / tuning distance). An estimate is shown as an estimate, stays host-side and recomputable by default, and is never written back as if a human set it, and never clobbers an author-set value. Mechanically that's the spec's existing {engine, model, version} provenance stamp + the "fill-don't-clobber, author wins" rule (sd/fn) — one shape across difficulty/genre/enrichment (see #38), not three bespoke ones. (Why an estimate can't be the truth: note-density + tempo can't see a one-hard-bar song, stamina, or an awkward stretch, so a confident-but-wrong number mis-sequences a learner — the one thing a practice app can't afford. Estimate to fill gaps; a human's call wins.)

Q3 — Difficulty rating vs the practice ladder: different things, keep both. The difficulty rating is the library shelf signal — which song to pick before you start. The practice ladder (max_difficulty, §6.7) is the in-song learning aid — how much of the part you attempt right now, climbed as you master it. Orthogonal; neither derives from the other. The difficulty_rating name (vs bare difficulty) is precisely what keeps them from reading as the same thing.

Optional, flagged for discussion (not blocking the scale decision):

• A tiny optional difficulty profile — a few named sub-dimensions (technical / tempo / stamina / rhythm / reading) so a song can say why it's hard. A slow-but-stretchy song and a fast-but-trivial song both rate ~5 yet train opposite things; the profile is what powers "what to practice next." All-optional; the single rating stays the primary sortable field.
• A "practice-scaffolded?" flag — whether the chart ships a practice ladder at all. For a beginner, "can I scale this down to learn it?" is often a more useful browse signal than "how hard is it."

Mechanics / sequencing: additive OPTIONAL difficulty_rating on arrangements[] → MINOR bump (1.12.0); additionalProperties: true keeps old packs valid, add an explicit integer 1–10 constraint; older Readers ignore + round-trip. Independent of #38; can land in parallel.

[topkoa]

Update — retarget to 1.13.0. Spec 1.12.0 is now merged (PR #40: album_artist/track/disc/genres) without a difficulty field, so this issue's "MINOR bump → 1.12.0" is stale — the next additive key lands in 1.13.0. The proposal itself (OPTIONAL integer difficulty on each arrangements[] entry, §5.2) is unchanged and its open questions (scale, authored-vs-derived, relationship to phrase max_difficulty) still need direction. Retitling 1.12.0 → 1.13.0.

[topkoa]

Decisions locked (maintainer, topkoa) — clears the way for the 1.13.0 spec PR

1. Field name → difficulty_rating (not bare difficulty), on each arrangements[] entry (§5.2). Keeps it visually distinct from the in-chart practice ladder max_difficulty (§6.7).

2. Scale → anchored 1–10, half-points allowed. Not a coarse enum. Spec defines the anchors (1 = first-week player, 5 = comfortable hobbyist, 10 = virtuosic ceiling), read per-instrument, rate by the hardest part (documented exception for a short hard passage in an otherwise-easy song), and never derive it from accuracy/recognition scores. Schema constraint: { "type": "number", "minimum": 1, "maximum": 10, "multipleOf": 0.5 }. Host displays coarse bands; never shows the raw number as a chased grade.

3. Estimates → host-side only; provenance deferred. Author-set is the source of truth and travels in the pack. Where none is set, the app shows an estimate computed from the chart (practice-ladder peak + note density / tempo / tuning distance) that stays host-side, recomputable, and is never written back into the pack. So this PR adds only difficulty_rating — no difficulty_source / provenance field yet. If/when estimates ever get written back, provenance rides the shared {engine, model, version} effort (see [Spec] Top-level tags manifest key (1.13.0, additive) — genres shipped in 1.12.0 #38/[Decision] Online metadata enrichment — go/no-go before any spec work #39), added then, not now.

4. Include the optional difficulty profile. Alongside the single scalar, add an OPTIONAL set of named sub-dimensions (technical / tempo / stamina / rhythm / reading), same anchored 1–10 scale, all optional — so a song can say why it's hard and power "what to practice next." The single difficulty_rating stays the primary sortable field. Deferred: the "practice-scaffolded?" flag → separate later issue.

Spec PR scope (1.13.0, additive)

• §5.2 arrangements[]: OPTIONAL difficulty_rating (number, 1–10, multipleOf 0.5) + OPTIONAL difficulty_profile object (same-scale optional sub-dimensions).
• §6.7: reword to describe max_difficulty as the practice ladder, and add a note that it is orthogonal to difficulty_rating.
• manifest.schema.json: add both to the arrangementEntry def with explicit constraints (keep additionalProperties: true).
• Anchor definitions + "rate by hardest part" guidance in §5.2.
• CHANGELOG [1.13.0], README + spec-header version bump to 1.13.0, tools/check_versions.py green.