ADR: dossier commit SHAs are branch-relative provenance
Dossier commit SHAs are branch-relative provenance
Status: Proposed (2026-11-07). The operator accepts or amends it on the pull request.
Date: 2026-11-07
Deciders: Stijn Dejongh (operator).
Technical Story:
- #7322: Mission dossiers freeze commit SHAs that a rebase merge invalidates.
- #7313: closing out a Mission after its files reach
mainneeds a freeze exception (related; its own record gaps are out of scope here). - #7163: keep accepted issue evidence resolvable after Mission history compaction (related).
- #7203 / PR #7314: the most recent operator-sanctioned freeze exception for stale SHAs, drained the same day.
- Operator ruling 2026-11-07: pull requests keep landing by rebase merge.
Reader: a maintainer who lands pull requests or reviews a Mission dossier, and an agent doing either. It assumes you know what a dossier and the archive freeze are.
Context
A Mission dossier under kitty-specs/<mission>/ records git commit SHAs as evidence:
meta.json:merged_commit,baseline_merge_commit,accept_commit,accepted_from_commit,acceptance_history[],mission_base_sha(the commit the Mission branch was cut from, written once at create, #7560), and, on the pull-request route,pr_merge_commit;lanes.json:planning_commit_sha;status.events.jsonl:policy_metadata.lane_headon every lifecycle transition, andpolicy_metadata.pre_review_gate.evidence_tree.headon afor_reviewtransition whose pre-review gate ran tests (the HEAD of the lane or write checkout the verdict was produced in, #7547);tasks/WP*/baseline-tests.json:base_commit;acceptance-matrix.json:negative_invariants[].verified_ref;- hand-authored evidence:
issue-matrix.jsonevidence_ref, review evidence, research notes.
Almost all of them are written before the pull request exists: by consolidate (local HEAD, and
the target tip before consolidation), by accept, by the status pipeline (lane tips), by lane
allocation and by the review baseline. Pull requests then land on main by rebase merge, which
rewrites every commit, and landing passes rebase or compact the branch before that. The recorded
SHAs therefore name commits that are not in main’s history. On 2026-11-07, of the dossiers whose
meta.json changed since 2026-10-25, 0 of 143 accept_commit values, 2 of 136 merged_commit
values and 11 of 136 baseline_merge_commit values were ancestors of main. Most resolve only
through refs/pull/<n>/head, and a commit from an earlier rebase of the same branch not even there.
The archive freeze (tests/architectural/test_archive_root_byte_identical.py) byte-freezes every
dossier file once it is on main. Landers treated the unreachable SHAs as defects: they repointed
them at “the rebased equivalent” before merge (the values went stale again on merge), and after
merge corrected them only through an operator-sanctioned freeze exception, which was then drained
(#7203 and PR #7314). Some fields had no rebased equivalent and were nulled or approximated.
The real problem is what these values were taken to mean, not the freeze. status.events.jsonl is
append-only and its prefix is frozen, so lane_head cannot be corrected by any mechanism.
GitHub’s rebase merge has no post-merge hook, and CI on main cannot push, so a “reconciliation
write” would itself be a follow-up landing pass. Changing what the writers record (a patch-id, the
pull request number) crosses the consolidation and approval-bound gates that read these SHAs before
landing (ADR 2026-10-04-5, ADR 2026-09-29-1), where the raw branch SHA is exactly what they need.
Decision
- A commit SHA a dossier records is branch-relative provenance unless it is classified
LANDED. It names a commit on the branch the Mission was built on, as that branch stood when the value was written. After a rebase merge it may resolve only through the pull request’s head ref, or not at all. That is its defined meaning, not a defect. - Branch-relative values are never repointed. No landing pass, before or after merge, rewrites one to “the rebased equivalent”, nulls it, or approximates it. The value as written is correct.
- One registry classifies every SHA field of a tool-written dossier file. It is
DOSSIER_SHA_FIELDSintests/architectural/test_dossier_sha_provenance.py, coveringmeta.json,lanes.json,status.json,status.events.jsonl,tasks/WP*/baseline-tests.jsonandacceptance-matrix.json. The gate there fails when one of those files records a full SHA under an unclassified key path, so a writer that starts recording a new SHA field classifies it in the same change. Today every entry isBRANCH_RELATIVEexceptpr_merge_commit, which isLANDED.baseline_merge_commitis mixed provenance (on the pull request route it is the landing commit’s first parent, on the target), so it staysBRANCH_RELATIVE, the class that promises nothing. LANDEDis the only class that promises ancestry of the target. ALANDEDfield is written only after landing, by a writer that verifies the commit is on the target branch before it records it (verify_pr_merge_evidenceforpr_merge_commit, reached throughspec-kitty accept --mode pr --merge-commitandspec-kitty migrate backfill-merge-commit). A field moves toLANDEDonly together with such a writer.- SHAs in hand-authored evidence are branch-relative by rule. This covers
issue-matrix.jsonevidence_refprose, review evidence, research notes and the hand-addedevidence_provenanceblock of olderacceptance-matrix.jsonfiles. They are not in the registry, and a lander never edits them to repoint a cited commit. - The archive freeze stays byte-strict. No SHA-field mask, no key-level exemption, and no
freeze exception for a branch-relative SHA a rebase merge left unreachable: such a value is
neither corrupt nor stale.
_OPERATOR_SANCTIONED_CORRECTIONSremains for genuinely corrupt files. - The decision applies to every dossier already on
main. The dossiers landed on 2026-11-07 (#7273, #7101, #7287, #7317, #6883, #7094) and every earlier one are reconciled by this definition: their SHAs keep their recorded values, and none is edited. Pull requests still open (#7231, #7234) drop any repointing commits rather than land them.
Consequences
- No landing pass hand-repoints dossier SHAs, and stale-SHA freeze exceptions stop.
- A reader cannot use
merged_commit,accept_commitorlane_headto find the landed code onmain. To find it, usepr_merge_commitwhere it was recorded, the pull request’s own history, or the(#<n>)pull request number in the landed commit’s subject. - The post-merge review dead-code scan diffs from
baseline_merge_commit(review/_dead_code.py); when that commit is not onmain, the scan cannot run. Recordingpr_merge_commitafter landing is the supported route. It writes a frozenmeta.json, so it meets the same freeze boundary as #7313; deciding that boundary is #7313’s scope. - The gate does not prove that a branch-relative SHA ever existed: that evidence goes when GitHub prunes a pull request’s refs.
- The gate checks that a key is classified, not that its class is honest: moving a field to
LANDEDstays green without an ancestry-checking writer, so review owns that rule (Decision 4). It also sees only full 40-hex values (a SHA inside a composite value such asreview:WP06:<sha>is not matched) and runs onkitty-specs/**changes, so a new writer field is caught when the first dossier carrying it lands, not when the writer changes. - Abbreviated SHAs are not scanned (short hex runs collide with ordinary values); every tool writer records the full id.
Alternatives considered
- Repoint patch-equivalent SHAs after merge through a freeze tolerance. Rejected: it keeps the
landing passes the issue removes, needs a follow-up pull request per Mission, and cannot reach
lane_headin the append-only event log. - One post-merge reconciliation write per Mission. Rejected for branch-relative fields for the same
reasons. For a
LANDEDfield such aspr_merge_commitit remains the right shape; the freeze boundary for it is #7313’s decision. - Exempt SHA-bearing keys from the byte freeze. Rejected: values behind the exemption could then change freely, and it widens an allowlist where the charter prefers an empty one.
- Record a patch-id or the pull request number instead of the SHA. Deferred: the pre-landing readers need the raw branch SHA, and a read-side mapping from a branch SHA to its landed commit can be added later without a write.