Write-back contract (§7) amendment: explicit per-field overwrite of author-set values

[ChrisBeWithYou]

@topkoa — following up on the write-back contract we settled in the alignment discussion (and that shipped as agreed: gap-fill in got-feedBack/feedBack#724 adds absent keys only, never replaces).

§7 today covers gap-fill — and it's behaving exactly as agreed in production. Users are now asking for the next step: replacing a WRONG author-set value with the confirmed-match value (a typo'd artist, a wrong year), which §7 deliberately excluded pending this conversation.

Proposed amendment, keeping every §7 principle:

1. Still user-initiated + single-song — never background, never batch (batch stays parked as before).
2. Per-field explicit checkboxes, default OFF, showing old → new before anything writes — a field is only ever replaced by a deliberate individual tick.
3. Eligibility only from a match the user explicitly confirmed (pinned/manual) — an automatic match can display, but cannot authorize destroying author bytes.
4. Provenance recorded — locally for now (a write log: old/new/source/score/timestamp per field), migrating into the pack once the provenance/extra FEP gives an in-file shape. Nothing is written that can't be traced.
5. Atomic writer + backup: the FIRST backup is the pristine author original and is never clobbered by later writes; a visible one-click Revert restores it.
6. Hard never-overwrite list: all chart/practice data (tuning, arrangements, duration, capo, offsets, stems, timeline), and identity keys (mbid/isrc) except via an explicit manual re-match.

Effectively: gap-fill fills gaps; overwrite fixes errors — one field at a time, with receipts and an undo.

The host-side implementation is being prepared as a draft PR and stays draft until you're comfortable amending §7. Happy to adjust any of the six points — the eligibility bar (point 3) and the provenance shape (point 4) are the ones where your judgment matters most.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Nm7tHs1Yvjjtnnu4nzJgdN

[topkoa]

Thanks Chris — proposal's tight and the six guardrails are the right shape. One blocker before you cut the PR, and it's a numbering/base-text mismatch rather than anything in the proposal itself:

§7 in feedpak-spec (v1.13.0) is "Side-files" — there's no write-back contract in the spec to amend. I searched the whole document (and history): it has no write-back, gap-fill, provenance-log, backup/revert, protected-field, or mbid/isrc concepts at all. Gap-fill shipped in the app (feedBack#724) and is behaving as agreed — but that contract was only ever settled in the alignment discussion, never written into the spec.

So there's nothing at §7 to extend yet. Two ways forward — can you confirm which you mean?

1. "§7" = the alignment doc, not feedpak-spec. Then this FEP is filed against the wrong repo; let's reconcile the section numbers against the spec's actual structure (write semantics live in §8 "Reading and writing", informative).
2. This is meant for feedpak-spec. Then we need it in two steps: first a PR that adds the write-back contract documenting the current gap-fill baseline, then your overwrite rules layer on top. Happy to draft step one so your draft PR has a real base to extend.

When it does land: per-field overwrite changes existing write semantics, so it's a MAJOR bump unless we frame it as a purely-optional opt-in (older writers ignore) — then MINOR. Per CONTRIBUTING it's one PR touching spec + schema + an examples/ pack that validates + [Unreleased] CHANGELOG, DCO sign-off. The provenance write-log should mirror the existing {engine, model, version} provenance-object pattern (§5.3.1 / §7.1.1) for consistency.

Nail down which doc §7 points at and I'll unblock the base text.