<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-11-07-1-dossier-commit-shas-are-branch-relative-provenance/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-11-07-1-dossier-commit-shas-are-branch-relative-provenance/</id>
  <title>ADR: dossier commit SHAs are branch-relative provenance</title>
  <updated>2026-11-13T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-11-07-1-dossier-commit-shas-are-branch-relative-provenance/"/>
  <summary>A commit SHA a Mission dossier records names a commit on the branch the work was built on; after a rebase merge it is never repointed, and the archive freeze stays byte-strict.</summary>
  <content type="html">&lt;h2 id=&quot;dossier-commit-shas-are-branch-relative-provenance&quot;&gt;Dossier commit SHAs are branch-relative provenance&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Proposed (2026-11-07). The operator accepts or amends it on the pull request.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-11-07&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;#7322: Mission dossiers freeze commit SHAs that a rebase merge invalidates.&lt;/li&gt;
&lt;li&gt;#7313: closing out a Mission after its files reach &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; needs a freeze exception (related; its
own record gaps are out of scope here).&lt;/li&gt;
&lt;li&gt;#7163: keep accepted issue evidence resolvable after Mission history compaction (related).&lt;/li&gt;
&lt;li&gt;#7203 / PR #7314: the most recent operator-sanctioned freeze exception for stale SHAs, drained the
same day.&lt;/li&gt;
&lt;li&gt;Operator ruling 2026-11-07: pull requests keep landing by rebase merge.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; 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.&lt;/p&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;A Mission dossier under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;mission&gt;/&lt;/code&gt; records git commit SHAs as evidence:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;merged_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;baseline_merge_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;accept_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;accepted_from_commit&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;acceptance_history[]&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission_base_sha&lt;/code&gt; (the commit the Mission branch was cut from, written
once at create, #7560), and, on the pull-request route, &lt;code dir=&quot;auto&quot;&gt;pr_merge_commit&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;planning_commit_sha&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;policy_metadata.lane_head&lt;/code&gt; on every lifecycle transition, and
&lt;code dir=&quot;auto&quot;&gt;policy_metadata.pre_review_gate.evidence_tree.head&lt;/code&gt; on a &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; transition whose
pre-review gate ran tests (the HEAD of the lane or write checkout the verdict was produced in,
#7547);&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tasks/WP*/baseline-tests.json&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;base_commit&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;negative_invariants[].verified_ref&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;hand-authored evidence: &lt;code dir=&quot;auto&quot;&gt;issue-matrix.json&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;evidence_ref&lt;/code&gt;, review evidence, research notes.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Almost all of them are written before the pull request exists: by &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; (local &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt;, and
the target tip before consolidation), by &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;, by the status pipeline (lane tips), by lane
allocation and by the review baseline. Pull requests then land on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;’s history. On 2026-11-07, of the dossiers whose
&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; changed since 2026-10-25, 0 of 143 &lt;code dir=&quot;auto&quot;&gt;accept_commit&lt;/code&gt; values, 2 of 136 &lt;code dir=&quot;auto&quot;&gt;merged_commit&lt;/code&gt;
values and 11 of 136 &lt;code dir=&quot;auto&quot;&gt;baseline_merge_commit&lt;/code&gt; values were ancestors of &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. Most resolve only
through &lt;code dir=&quot;auto&quot;&gt;refs/pull/&amp;#x3C;n&gt;/head&lt;/code&gt;, and a commit from an earlier rebase of the same branch not even there.&lt;/p&gt;
&lt;p&gt;The archive freeze (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_archive_root_byte_identical.py&lt;/code&gt;) byte-freezes every
dossier file once it is on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. 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.&lt;/p&gt;
&lt;p&gt;The real problem is what these values were taken to mean, not the freeze. &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; is
append-only and its prefix is frozen, so &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; cannot be corrected by any mechanism.
GitHub’s rebase merge has no post-merge hook, and CI on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;2026-10-04-5&lt;/code&gt;, ADR &lt;code dir=&quot;auto&quot;&gt;2026-09-29-1&lt;/code&gt;), where the raw branch SHA is exactly what they need.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;A commit SHA a dossier records is branch-relative provenance unless it is classified
&lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt;.&lt;/strong&gt; 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Branch-relative values are never repointed.&lt;/strong&gt; No landing pass, before or after merge, rewrites
one to “the rebased equivalent”, nulls it, or approximates it. The value as written is correct.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One registry classifies every SHA field of a tool-written dossier file.&lt;/strong&gt; It is
&lt;code dir=&quot;auto&quot;&gt;DOSSIER_SHA_FIELDS&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_dossier_sha_provenance.py&lt;/code&gt;, covering
&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks/WP*/baseline-tests.json&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt;.
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
is &lt;code dir=&quot;auto&quot;&gt;BRANCH_RELATIVE&lt;/code&gt; except &lt;code dir=&quot;auto&quot;&gt;pr_merge_commit&lt;/code&gt;, which is &lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;baseline_merge_commit&lt;/code&gt; is mixed
provenance (on the pull request route it is the landing commit’s first parent, on the target), so it
stays &lt;code dir=&quot;auto&quot;&gt;BRANCH_RELATIVE&lt;/code&gt;, the class that promises nothing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt; is the only class that promises ancestry of the target.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt; field is written
only after landing, by a writer that verifies the commit is on the target branch before it records
it (&lt;code dir=&quot;auto&quot;&gt;verify_pr_merge_evidence&lt;/code&gt; for &lt;code dir=&quot;auto&quot;&gt;pr_merge_commit&lt;/code&gt;, reached through
&lt;code dir=&quot;auto&quot;&gt;spec-kitty accept --mode pr --merge-commit&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-merge-commit&lt;/code&gt;). A
field moves to &lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt; only together with such a writer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;SHAs in hand-authored evidence are branch-relative by rule.&lt;/strong&gt; This covers &lt;code dir=&quot;auto&quot;&gt;issue-matrix.json&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;evidence_ref&lt;/code&gt; prose, review evidence, research notes and the hand-added &lt;code dir=&quot;auto&quot;&gt;evidence_provenance&lt;/code&gt;
block of older &lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt; files. They are not in the registry, and a lander never
edits them to repoint a cited commit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The archive freeze stays byte-strict.&lt;/strong&gt; 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. &lt;code dir=&quot;auto&quot;&gt;_OPERATOR_SANCTIONED_CORRECTIONS&lt;/code&gt; remains for genuinely corrupt files.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The decision applies to every dossier already on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/strong&gt; 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.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;No landing pass hand-repoints dossier SHAs, and stale-SHA freeze exceptions stop.&lt;/li&gt;
&lt;li&gt;A reader cannot use &lt;code dir=&quot;auto&quot;&gt;merged_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;accept_commit&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; to find the landed code on
&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. To find it, use &lt;code dir=&quot;auto&quot;&gt;pr_merge_commit&lt;/code&gt; where it was recorded, the pull request’s own history,
or the &lt;code dir=&quot;auto&quot;&gt;(#&amp;#x3C;n&gt;)&lt;/code&gt; pull request number in the landed commit’s subject.&lt;/li&gt;
&lt;li&gt;The post-merge review dead-code scan diffs from &lt;code dir=&quot;auto&quot;&gt;baseline_merge_commit&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;review/_dead_code.py&lt;/code&gt;); when that commit is not on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, the scan cannot run. Recording
&lt;code dir=&quot;auto&quot;&gt;pr_merge_commit&lt;/code&gt; after landing is the supported route. It writes a frozen &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, so it meets
the same freeze boundary as #7313; deciding that boundary is #7313’s scope.&lt;/li&gt;
&lt;li&gt;The gate does not prove that a branch-relative SHA ever existed: that evidence goes when GitHub
prunes a pull request’s refs.&lt;/li&gt;
&lt;li&gt;The gate checks that a key is classified, not that its class is honest: moving a field to &lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt;
stays 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 as &lt;code dir=&quot;auto&quot;&gt;review:WP06:&amp;#x3C;sha&gt;&lt;/code&gt; is not
matched) and runs on &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; changes, so a new writer field is caught when the first
dossier carrying it lands, not when the writer changes.&lt;/li&gt;
&lt;li&gt;Abbreviated SHAs are not scanned (short hex runs collide with ordinary values); every tool writer
records the full id.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Repoint patch-equivalent SHAs after merge through a freeze tolerance.&lt;/strong&gt; Rejected: it keeps the
landing passes the issue removes, needs a follow-up pull request per Mission, and cannot reach
&lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; in the append-only event log.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One post-merge reconciliation write per Mission.&lt;/strong&gt; Rejected for branch-relative fields for the same
reasons. For a &lt;code dir=&quot;auto&quot;&gt;LANDED&lt;/code&gt; field such as &lt;code dir=&quot;auto&quot;&gt;pr_merge_commit&lt;/code&gt; it remains the right shape; the freeze
boundary for it is #7313’s decision.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Exempt SHA-bearing keys from the byte freeze.&lt;/strong&gt; Rejected: values behind the exemption could then
change freely, and it widens an allowlist where the charter prefers an empty one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Record a patch-id or the pull request number instead of the SHA.&lt;/strong&gt; 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.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
