<?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-10-01-3-decision-ledger-primary-partition/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-01-3-decision-ledger-primary-partition/</id>
  <title>ADR: the decision ledger is a PRIMARY-partition kind (reverses the #3928 COORD intent)</title>
  <updated>2026-10-02T00: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-10-01-3-decision-ledger-primary-partition/"/>
  <summary>DECISION_LEDGER is classified PRIMARY for every topology; decision events stay COORD; the index gets a union merge driver and a doctor repair.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-01&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner), through the operator ruling
&lt;code dir=&quot;auto&quot;&gt;decision-ledger-partition&lt;/code&gt; (Decision Moment &lt;code dir=&quot;auto&quot;&gt;DM-01M3V4BXG1EP7JX83TM5K6WSJ8&lt;/code&gt;) and the
sibling ruling &lt;code dir=&quot;auto&quot;&gt;legacy-ledger&lt;/code&gt; of Mission &lt;code dir=&quot;auto&quot;&gt;coord-artifact-single-home-01M3V4BE&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5023&quot;&gt;#5023&lt;/a&gt;, Mission
&lt;code dir=&quot;auto&quot;&gt;coord-artifact-single-home-01M3V4BE&lt;/code&gt; (FR-009, FR-009a, FR-009b, FR-009c). Reverses the
classification chosen under &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3928&quot;&gt;#3928&lt;/a&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The Decision Moment ledger is the pair &lt;code dir=&quot;auto&quot;&gt;decisions/index.json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;decisions/DM-&amp;#x3C;ulid&gt;.md&lt;/code&gt;
under a Mission’s directory (&lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind.DECISION_LEDGER&lt;/code&gt;). Two facts disagreed:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The taxonomy said COORD.&lt;/strong&gt; #3928 classified the kind as COORD-partition,
“single-writer coordination bookkeeping”, on the theory that the ledger’s writer resolved
its directory through the coordination status surface. No ADR recorded that intent; it
lived in code comments.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The code said PRIMARY.&lt;/strong&gt; #4966 (AC-D2) had already moved the ledger’s own reads and
writes onto the PRIMARY partition: &lt;code dir=&quot;auto&quot;&gt;decisions/service.py::_ledger_dir&lt;/code&gt; resolves
&lt;code dir=&quot;auto&quot;&gt;PRIMARY_METADATA&lt;/code&gt; through &lt;code dir=&quot;auto&quot;&gt;placement_seam(...).read_dir(...)&lt;/code&gt;. Only the decision
&lt;strong&gt;events&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt;) were written to the
coordination surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The disagreement is what #5023 reported. &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt; classifies by the taxonomy, so it
routed the ledger’s files onto the coordination branch, while the writer kept producing
them on the PRIMARY partition. The ledger then forked from the Mission’s own history, and a
coordination teardown could destroy the only committed copy.&lt;/p&gt;
&lt;p&gt;This ADR is the durable record the #3928 intent never had. It is narrower than, and
separate from, &lt;a href=&quot;/adr/3.x/2026-06-19-1-coord-empty-surface-fallback/&quot;&gt;ADR 2026-06-19-1&lt;/a&gt;: that
ADR governs the empty coordination surface, and its 2026-10-01 amendment links here instead
of hosting the reversal.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The taxonomy must describe the write side that already exists, not the reverse
(read/write symmetry, &lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;ADR 2026-06-24-1&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;A committed ledger must travel with its Mission’s branches and survive coordination
teardown.&lt;/li&gt;
&lt;li&gt;No automatic log merge (C-003), and no silent loss of an index entry (FR-011).&lt;/li&gt;
&lt;li&gt;Fix forward (C-004): Missions created before this change must be repairable.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Classify the ledger PRIMARY (chosen).&lt;/strong&gt; The taxonomy moves to match where the ledger is
read and written today.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Move the ledger’s reads and writes to the coordination surface.&lt;/strong&gt; The code would move
to match the #3928 classification.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These are the two options the operator ruling weighed (Decision Moment
&lt;code dir=&quot;auto&quot;&gt;DM-01M3V4BXG1EP7JX83TM5K6WSJ8&lt;/code&gt;); its &lt;code dir=&quot;auto&quot;&gt;Other&lt;/code&gt; slot was not used.&lt;/p&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;Chosen option 1, because it is the only option that changes the taxonomy rather than the
writer. The writer and every reader of the ledger content were already PRIMARY (#4966);
option 2 would have reversed that work and put the ledger on a branch that lanes do not
carry and that consolidation tears down.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Partition.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt; is in &lt;code dir=&quot;auto&quot;&gt;_PRIMARY_ARTIFACT_KINDS&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;_COORD_RESIDUE_DIRS[&quot;decisions&quot;]&lt;/code&gt; still maps the
directory to the same kind; only the partition membership moved. &lt;code dir=&quot;auto&quot;&gt;kind_is_coordination_residue&lt;/code&gt;
is therefore false for it, so &lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt; is never reset as coordination residue.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Events stay COORD.&lt;/strong&gt; Decision events in &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;decisions.events.jsonl&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;DECISION_LOG&lt;/code&gt;) are unchanged. &lt;code dir=&quot;auto&quot;&gt;doctor decisions&lt;/code&gt; joins the two
surfaces; the ledger content is PRIMARY and the event log is COORD.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Committers.&lt;/strong&gt; The ledger is committed by &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; only. The commit
router routes the ledger to the target branch. &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; classifies the current Mission’s
uncommitted ledger files through the artifact taxonomy
(&lt;code dir=&quot;auto&quot;&gt;acceptance/ledger_dirt.py::mission_decision_ledger_files&lt;/code&gt;), commits them, and still
fails closed on any other dirt, including another Mission’s ledger. The consolidation
dirty gate now refuses uncommitted ledger files instead of resetting them as residue;
its message names &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Index merge driver.&lt;/strong&gt; The index travels with lane branches, so concurrent additions
conflict on &lt;code dir=&quot;auto&quot;&gt;decisions/index.json&lt;/code&gt;. A &lt;code dir=&quot;auto&quot;&gt;spec-kitty-decision-index&lt;/code&gt; driver
(&lt;code dir=&quot;auto&quot;&gt;consolidation/drivers.py::union_decision_index&lt;/code&gt;, run by &lt;code dir=&quot;auto&quot;&gt;run_decision_index_driver&lt;/code&gt;,
command &lt;code dir=&quot;auto&quot;&gt;spec-kitty merge-driver-decision-index&lt;/code&gt;) takes the keyed union of &lt;code dir=&quot;auto&quot;&gt;entries&lt;/code&gt; by
&lt;code dir=&quot;auto&quot;&gt;decision_id&lt;/code&gt;; a same-id collision resolves with the fold precedence in
&lt;code dir=&quot;auto&quot;&gt;decisions/index_fold.py&lt;/code&gt;, so a terminal status beats &lt;code dir=&quot;auto&quot;&gt;open&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;DM-*.md&lt;/code&gt; needs no driver:
each file is ULID-named and written once. The registration surfaces are &lt;code dir=&quot;auto&quot;&gt;.gitattributes&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;kitty-specs/**/decisions/index.json merge=spec-kitty-decision-index&lt;/code&gt;), the &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; seed,
and the migration &lt;code dir=&quot;auto&quot;&gt;m_4_0_0rc5_decision_index_merge_driver&lt;/code&gt; for already-initialised
clones. The planning-recency resolver skips driver-covered paths so it cannot overwrite
the union result. The &lt;code dir=&quot;auto&quot;&gt;test_merge_reconciliation_class_guard.py&lt;/code&gt; single-writer ruling for
&lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt; was amended to say so.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix-forward for pre-fix Missions.&lt;/strong&gt; A Mission whose ledger was committed only on the
coordination branch is reported by &lt;code dir=&quot;auto&quot;&gt;doctor decisions&lt;/code&gt; as
&lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER_ONLY_ON_COORDINATION&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;doctor decisions --repair&lt;/code&gt; copies the missing
&lt;code dir=&quot;auto&quot;&gt;DM-*.md&lt;/code&gt; files and merges the index entries into the PRIMARY ledger additively (same
&lt;code dir=&quot;auto&quot;&gt;union_decision_index&lt;/code&gt;, under the ledger’s lock), and creates &lt;strong&gt;no&lt;/strong&gt; commit; the operator
commits with &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Teardown refusal.&lt;/strong&gt; The bookkeeping projection excludes PRIMARY kinds, so a
coordination-only ledger would be destroyed with the coordination triple. Both
&lt;code dir=&quot;auto&quot;&gt;coordination/teardown.py::teardown_coordination_topology&lt;/code&gt; and the consolidation
preflight (&lt;code dir=&quot;auto&quot;&gt;consolidation/executor.py::_pre_mutation_safety_preflight&lt;/code&gt;) therefore refuse
with &lt;code dir=&quot;auto&quot;&gt;COORDINATION_LEDGER_UNREPAIRED&lt;/code&gt; until the ledger is repaired. Nothing is mutated on
refusal.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fork posture.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;doctor decisions&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent decision verify&lt;/code&gt; detect a forked decision
event stream (&lt;code dir=&quot;auto&quot;&gt;DECISION_LOG_FORKED&lt;/code&gt;) from refs and worktrees through one detector,
&lt;code dir=&quot;auto&quot;&gt;decisions/fork.py::detect_decision_forks&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;--repair&lt;/code&gt; never drops an entry whose events
exist on either surface and never re-sequences a forked log (C-003); on a fork it prints
the reconcile steps and exits 1.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The taxonomy, the writer and the committers agree; &lt;code dir=&quot;auto&quot;&gt;spec-commit&lt;/code&gt; no longer forks the
ledger onto the coordination branch.&lt;/li&gt;
&lt;li&gt;A committed ledger lands on the target branch and survives coordination teardown.&lt;/li&gt;
&lt;li&gt;Concurrent lane additions to the index merge without losing an entry.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Behaviour change for coordination-routed Missions: an uncommitted ledger now blocks the
consolidation dirty gate instead of being reset. That is intended; the message names the
committers.&lt;/li&gt;
&lt;li&gt;Every reader that classified &lt;code dir=&quot;auto&quot;&gt;decisions/&lt;/code&gt; as residue flipped (commit router grouping,
accept gate, retrospect, record-analysis, implement, move-task, auto-rebase, rollback,
ordering, workspace teardown, bulk-edit diff check, and others). Non-coordination
topologies (&lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;) keep today’s verdicts (C-008).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Decision events and the status log are untouched; the single-writer posture still holds
for them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Focused reader tests for each flipped site, the red-first characterisation for the
non-coordination topologies, and the merge-driver round-trip test.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/integration/test_coord_single_home_workflow.py&lt;/code&gt;, whose accept leg lands an
uncommitted ledger on the target branch tip.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_merge_reconciliation_class_guard.py&lt;/code&gt; and the write-surface
placement guard, both updated in the same Mission.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;supersession&quot;&gt;Supersession&lt;/h2&gt;
&lt;p&gt;This ADR &lt;strong&gt;reverses the classification half of #3928&lt;/strong&gt; for &lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt; only. #3928’s
other classifications stand. It does not supersede
&lt;a href=&quot;/adr/3.x/2026-09-24-2-coord-read-fail-closed/&quot;&gt;ADR 2026-09-24-2&lt;/a&gt;, whose list of
coord-partition kinds carries a dated pointer to this ADR.&lt;/p&gt;
&lt;h2 id=&quot;links&quot;&gt;Links&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Related: &lt;a href=&quot;/adr/3.x/2026-06-19-1-coord-empty-surface-fallback/&quot;&gt;ADR 2026-06-19-1&lt;/a&gt;, its
2026-10-01 amendment (the single-home write rule).&lt;/li&gt;
&lt;li&gt;Seam page: &lt;a href=&quot;/architecture/artifact-placement-seam/&quot;&gt;The Artifact Placement Seam&lt;/a&gt;,
“Worked example: &lt;code dir=&quot;auto&quot;&gt;DECISION_LEDGER&lt;/code&gt; moved COORD to PRIMARY (2026-10-01)”.&lt;/li&gt;
&lt;li&gt;Research: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/coord-artifact-single-home-01M3V4BE/research.md&lt;/code&gt; (D12 to D15).&lt;/li&gt;
&lt;li&gt;Contract: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/coord-artifact-single-home-01M3V4BE/contracts/doctor-decisions-fork-report.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
