docs(adr): propose ADR-0033 — song-id curation workflow - #172
Merged
Conversation
Docs-only. Extracts the durable decisions from the (merged, thrice-reviewed) song-id curation workflow proposal into a Nygard ADR; no new architecture. Status: Proposed — binds nothing until Accepted, and even acceptance does not authorize corpus labeling (gated on the controlled pilot). Records: standalone isolated song-curation/ ownership; sha256 source unit; human authority with non-authoritative metadata-only suggestions; append-only batched CurationStoreV1-style ledger with six first-class actions (three authorized replacements); plan-embeds-batch with replay/derive/compare Apply; transactional fresh-output application chain + append-only application index; opaque monotonic SongId and four canonical digest contracts; hard distinct-path manifest guard; fail-closed validation via core song_holdout_preflight; and a four-slice gated implementation with corpus labeling prohibited until the pilot. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi
📝 WalkthroughWalkthroughAdds ADR-0033 for an offline, human-confirmed, transactional song-id curation workflow and registers it in the ADR index as proposed. ChangesSong ID curation workflow
Estimated code review effort: 1 (Trivial) | ~3 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d8663faf78
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Correct two governance/semantics distortions introduced compressing the proposal; docs-only, Status stays Proposed. - Decision 10 + final paragraph: acceptance authorizes slice 1 only; each later slice needs separate acceptance; the controlled pilot (after slices 1-3) may write human-confirmed song_id ONLY to its small copied subset; only production/real-corpus/full-corpus labeling stays prohibited until the pilot is independently accepted. (The prior text forbade the labeling the pilot itself requires.) - Decision 6: Apply is not a generally-idempotent command — already-correct assignments are unchanged, but reuse of the same batch_id typed-refuses via the application index. No longer promises both "reuse is safe" and "reuse is refused". - Decision 3: "No default action counts as acceptance" (unambiguous). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi
Fulfil the AGENTS.md prior-art-first rule for the non-trivial ledger -> plan -> apply -> report -> application-index pipeline. Adds a "Prior art considered" section surveying four workflow categories — human-confirmed reconciliation (OpenRefine, MusicBrainz edits), append-only event sourcing (Fowler/git/CurationStoreV1), plan-before-apply with drift detection (Terraform, k8s dry-run), applied-once migrations (Flyway/Alembic/ Diesel), and content-addressed dataset versioning (DVC/lakeFS/Delta Lake) — each with reuse/reject/decision, concluding: reuse the patterns and invariants, implement natively because no external system fits Griff's source-level SongId, corpus fingerprint, dependency/MSRV posture, or fail-closed requirement. The identity-ontology prior art (FRBR/MusicBrainz) stays in ADR-0031; this covers the workflow it does not. No change to Decisions 1-10, README row, status (Proposed), or scope. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi
One-row factual fix in the Prior art section: the DVC / lakeFS / Delta Lake row conflated three materially different mechanisms and mis-described Griff's corpus as single-file. Now attributes each precisely (DVC: hash-addressed data via Git-versioned metadata; lakeFS: Git-like branching/commits; Delta Lake: ACID transaction-log commits + lineage), rejects them on storage-engine / service / table-model / dependency footprint against Griff's isolated file-based corpus tool, and reuses content identity / version lineage / transactional publication as separate patterns implemented natively. No change to Decisions 1-10, status, README, governance, gates, or the native-composition conclusion. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi
This was referenced Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Docs-only ADR-0033 (Proposed) extracting the durable decisions from the merged song-id curation workflow proposal. No new architecture — the proposal remains the detailed spec.
Files: the ADR + its
docs/adr/README.mdrow. Status: Proposed. Exact head:536be8aa6df36a0350f9027fa7e8be0669a922d5.The ten binding decisions
Standalone isolated
song-curation/ownership;sha256source unit; human authority with metadata-only non-authoritative suggestions; append-only batchedCurationStoreV1-style ledger with six first-class actions (three authorized replacements); plan embeds the batch, Apply replays→derives→compares; transactional fresh-output application chain + append-only application index (batch_id reuse typed-refuses — Apply is not generally idempotent); opaque monotonicSongId+ four canonical digest contracts; hard distinct-path manifest guard; fail-closed validation via coresong_holdout_preflight; and a four-slice separately-gated implementation.Prior art considered (AGENTS.md prior-art-first)
A recorded survey across four workflow categories — human-confirmed reconciliation (OpenRefine, MusicBrainz edits), append-only event sourcing (Fowler/git/
CurationStoreV1), plan-before-apply with drift detection (Terraform, k8s dry-run), and versioned transactional history (Flyway/Alembic/Diesel migrations table ≈ the application index; DVC/lakeFS/Delta Lake content-addressed versioning) — with reuse/reject/decision each. Conclusion: reuse the patterns and invariants, implement natively (no external system fits Griff's source-levelSongId, corpus fingerprint, dependency/MSRV posture, or fail-closed requirement); the novelty is only the composition. The identity-ontology prior art (FRBR/MusicBrainz) remains in ADR-0031, which this complements.Gating
song_idonly to its small copied subset.🤖 Generated with Claude Code
https://claude.ai/code/session_012T7SRMiXmZe5v1imtrKMPi