<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-06-24-2-write-branch-resolution-primary-anchor/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-24-2-write-branch-resolution-primary-anchor/</id>
  <title>ADR: Write-Branch Resolution Anchors `meta.json` on the PRIMARY Surface (Write-Surface Twin)</title>
  <updated>2026-06-24T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-06-24-2-write-branch-resolution-primary-anchor/"/>
  <summary>Write-branch resolvers read `meta.json` from the repository-root checkout under every topology, so commits land on the mission Target Ref, not the protected Primary Branch.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;A coordination-topology mission keeps two on-disk copies of its feature directory:
the &lt;strong&gt;repository-root checkout&lt;/strong&gt; (the &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; &lt;strong&gt;Sense C&lt;/strong&gt; surface — &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;slug&gt;/&lt;/code&gt;)
and the &lt;strong&gt;coordination worktree&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;.worktrees/&amp;#x3C;slug&gt;-&amp;#x3C;mid8&gt;-coord/kitty-specs/&amp;#x3C;slug&gt;/&lt;/code&gt;).
(The four &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; senses — PRIMARY partition / Primary Branch / repository-root
checkout / Target Ref — are catalogued in &lt;code dir=&quot;auto&quot;&gt;docs/context/orchestration.md&lt;/code&gt;; each use
below is qualified to exactly one.)&lt;/p&gt;
&lt;p&gt;The predecessor ADR ([2026-06-24-1]) made artifact &lt;strong&gt;placement&lt;/strong&gt; kind-aware: planning +
identity kinds (&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;) are PRIMARY-partition kinds that author, read,
and commit on the primary &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; for &lt;strong&gt;every&lt;/strong&gt; topology; status/verification
kinds stay on the coordination branch under coordination topology. The read side adopted
the per-kind seam &lt;code dir=&quot;auto&quot;&gt;resolve_planning_read_dir(repo_root, slug, *, kind)&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Two residual seams survived that re-partition, both on the &lt;strong&gt;write&lt;/strong&gt; path, and both share
one root failure mode. A write-branch resolver that needs a mission’s &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;
reads it from &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;PRIMARY_METADATA&lt;/code&gt; — it &lt;strong&gt;only&lt;/strong&gt; ever lives on
the primary checkout. The pre-fix resolvers anchored that &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; read on the
&lt;strong&gt;topology-aware candidate&lt;/strong&gt; dir (&lt;code dir=&quot;auto&quot;&gt;candidate_feature_dir_for_mission&lt;/code&gt;):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The write-branch resolvers&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;get_feature_target_branch&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;core/paths.py&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;resolve_target_branch&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;core/git_ops.py&lt;/code&gt;), and the &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; commit-branch
resolution (&lt;code dir=&quot;auto&quot;&gt;mission.py&lt;/code&gt;). Under coordination topology the candidate resolver returns
the materialized &lt;code dir=&quot;auto&quot;&gt;-coord&lt;/code&gt; worktree, whose mission dir has &lt;strong&gt;no&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;. The read
found nothing and silently fell back to &lt;code dir=&quot;auto&quot;&gt;resolve_primary_branch&lt;/code&gt; = the protected
repository’s &lt;strong&gt;Primary Branch&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; &lt;strong&gt;Sense B&lt;/strong&gt;, normally &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;). So the
planning-artifact commit/branch resolved to that Primary Branch instead of the mission’s
&lt;strong&gt;Target Ref&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; &lt;strong&gt;Sense D&lt;/strong&gt;) — the implement-loop /
&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; “refusal-to-main” defect. The root confusion is reading a
PRIMARY-partition (&lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; &lt;strong&gt;Sense A&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; is a PRIMARY-partition kind)
fact as a Primary-Branch (Sense B) instruction.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt; (Phase 0) command&lt;/strong&gt; (the &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2107&quot;&gt;#2107&lt;/a&gt;
driver’s read+write twin, found at closeout). It bound &lt;code dir=&quot;auto&quot;&gt;feature_dir = resolve_feature_dir_for_slug&lt;/code&gt; (coord-aware), then validated &lt;code dir=&quot;auto&quot;&gt;coord/plan.md&lt;/code&gt; (absent on
the husk since the predecessor mission moved plan.md to primary) and &lt;strong&gt;scaffolded&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt; / the research CSV stubs onto the coord husk —
re-introducing the very primary↔coord split the placement ADR eliminated.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Both are instances of one shape: &lt;strong&gt;a topology-routed &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; binding followed by a
planning-kind read/write.&lt;/strong&gt; The recurrence is the tell — the pre-plan squad found
&lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt;, the post-tasks squad found &lt;code dir=&quot;auto&quot;&gt;finalize-tasks-commit&lt;/code&gt;, the closeout
squad found &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt;; each enumeration undersized the set by one. The missing boundary
is not a name to add but a &lt;em&gt;shape&lt;/em&gt; to fence.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;The mission’s write-branch / planning-write resolution anchors on the &lt;strong&gt;primary&lt;/strong&gt; surface
for &lt;strong&gt;all&lt;/strong&gt; topologies, and the boundary is enforced by a coverage-derived (default-deny)
ratchet so the recurring N+1 cannot return silently.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Write-branch resolution reads &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; from the repository-root-checkout anchor.&lt;/strong&gt;
Every write-branch resolver (&lt;code dir=&quot;auto&quot;&gt;get_feature_target_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resolve_target_branch&lt;/code&gt;, the
&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; commit-branch resolution) reads &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;
under &lt;code dir=&quot;auto&quot;&gt;primary_feature_dir_for_mission&lt;/code&gt; (the topology-blind repository-root-checkout
constructor — &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; &lt;strong&gt;Sense C&lt;/strong&gt;), mirroring the already-proven
&lt;code dir=&quot;auto&quot;&gt;resolve_merge_target_branch&lt;/code&gt;. It is &lt;strong&gt;never&lt;/strong&gt; anchored on
&lt;code dir=&quot;auto&quot;&gt;candidate_feature_dir_for_mission&lt;/code&gt; (which selects coord, then falls back to the
protected &lt;strong&gt;Primary Branch&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; &lt;strong&gt;Sense B&lt;/strong&gt;, &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;). For ALL topologies the
resolved commit/branch is the mission’s &lt;strong&gt;Target Ref&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt;
&lt;strong&gt;Sense D&lt;/strong&gt;) (G-6).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Planning reads and the scaffold writes resolve via the kind-aware seam.&lt;/strong&gt; A gate
command that reads OR scaffolds a planning artifact resolves the dir through
&lt;code dir=&quot;auto&quot;&gt;resolve_planning_read_dir(..., kind=...)&lt;/code&gt; (PRIMARY-partition → primary for all
topologies). The &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt; command’s &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; read uses
&lt;code dir=&quot;auto&quot;&gt;kind=FINALIZED_EXECUTION_PLAN&lt;/code&gt; and its &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt; / CSV scaffold
writes use &lt;code dir=&quot;auto&quot;&gt;kind=RESEARCH&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;DATA_MODEL&lt;/code&gt; — all primary-partition kinds, so both legs
converge on the primary &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; dir. The STATUS-namespace dossier sync keeps
its existing coord-aware &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; surface, untouched.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Status destinations are unchanged.&lt;/strong&gt; The status/coord commit destinations
(&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;analysis-report.md&lt;/code&gt;) still route to
the coordination branch under coordination topology. This decision touches ONLY the
&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;) read and the planning scaffold surface — not where any
status-class write lands (C-002 status leniency preserved).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The boundary is a default-deny ratchet, not a manual denylist.&lt;/strong&gt; The FR-010
architectural ratchet support (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/_gate_read_callshape.py&lt;/code&gt;) keeps its
pinned, contract-cited surface set AND adds a &lt;strong&gt;coverage-derived&lt;/strong&gt; read arm that walks
every function in the CLI command packages and flags ANY topology-routed
planning-artifact join — so a NEW planning-lifecycle command that re-reads
&lt;code dir=&quot;auto&quot;&gt;coord/&amp;#x3C;artifact&gt;.md&lt;/code&gt; FAILS the gate even if nobody adds it to the pinned set. The
topology-routed resolver set is broadened to include &lt;code dir=&quot;auto&quot;&gt;resolve_feature_dir_for_slug&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;candidate_feature_dir_for_mission&lt;/code&gt;. A runnable synthetic-AST self-test proves the
default-deny arm flags an un-listed command in the exact &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt; shape. The write
arm is symmetric: it flags a &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; read anchored on the candidate dir.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The refusal-to-main / planning-write-to-coord defect class is closed at the root.&lt;/strong&gt;
A coordination-topology mission whose &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; is a feature branch resolves its
planning commit/branch to that branch, and authors its Phase-0 artifacts on it — the
command that authors and the command that validates agree on the surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The recurring N+1 is fenced at the shape, not the name.&lt;/strong&gt; The default-deny ratchet
catches the next un-listed command automatically; a future author cannot silently
re-introduce a &lt;code dir=&quot;auto&quot;&gt;coord/&amp;#x3C;artifact&gt;.md&lt;/code&gt; read.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Behavior-neutral for flattened / single-branch missions&lt;/strong&gt; (NFR-001): with no
coordination branch the candidate and primary anchors coincide, and the seam returns
&lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; — identical to pre-mission behavior.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--risks&quot;&gt;Negative / risks&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Forward-only.&lt;/strong&gt; A mission already split (planning scaffolded on coordination) is not
reconciled; the flatten / manual-recovery flow remains the remedy for legacy splits.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The default-deny scan is scoped to the CLI command packages.&lt;/strong&gt; A planning-kind read
introduced outside &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/&lt;/code&gt; is not covered by the discovery arm
(it would still need an enumerated pin). This is the deliberate precision/coverage
trade-off — the command packages are the planning-lifecycle gate surface.&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;Anchor write-branch resolution on the topology candidate (status quo).&lt;/strong&gt; Rejected:
that &lt;em&gt;is&lt;/em&gt; the bug — under coordination topology the candidate lacks &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and the
read falls back to protected &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep the manual denylist and just add &lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt;.&lt;/strong&gt; Rejected: the set undersized
three times running. Fencing the shape (default-deny) is the only durable fix; the
pinned set is retained for its contract citations, not as the sole coverage mechanism.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Transit the coordination worktree to find &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;.&lt;/strong&gt; Rejected (mirrors the
predecessor ADR’s D-3): &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; is a primary-only kind; the primary anchor is a
cleaner guarantee with no special-case transit.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Driver: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2107&quot;&gt;#2107&lt;/a&gt; (setup-plan + accept gate reads, and the research read/write twin, on protected-primary/coord topology)&lt;/li&gt;
&lt;li&gt;Bundled: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2085&quot;&gt;#2085&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2102&quot;&gt;#2102&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2088&quot;&gt;#2088&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2091&quot;&gt;#2091&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Predecessor (write-placement): &lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;ADR 2026-06-24-1 — Kind- and Topology-Aware Artifact Placement&lt;/a&gt; / mission &lt;code dir=&quot;auto&quot;&gt;write-surface-coherence-01KVTVZS&lt;/code&gt; (&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/2106&quot;&gt;#2106&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Predecessor (topology SSOT): &lt;a href=&quot;/adr/3.x/2026-06-22-1-mission-topology-ssot/&quot;&gt;ADR 2026-06-22-1 — MissionTopology SSOT&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Epics: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1716&quot;&gt;#1716&lt;/a&gt; (single surface authority), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1868&quot;&gt;#1868&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1878&quot;&gt;#1878&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/gate-read-surface-completion-01KVW9B0/spec.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Seam + ratchet contract: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/gate-read-surface-completion-01KVW9B0/contracts/gate-read-seam.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Canonical seams: &lt;a href=&quot;../../../src/specify_cli/missions/_read_path_resolver.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/_read_path_resolver.py&lt;/code&gt;&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;primary_feature_dir_for_mission&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resolve_planning_read_dir&lt;/code&gt;), &lt;a href=&quot;../../../src/specify_cli/core/paths.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/paths.py&lt;/code&gt;&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;get_feature_target_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resolve_merge_target_branch&lt;/code&gt;), &lt;a href=&quot;../../../src/specify_cli/core/git_ops.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/git_ops.py&lt;/code&gt;&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;resolve_target_branch&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Ratchet support (default-deny enforcement): &lt;a href=&quot;../../../tests/architectural/_gate_read_callshape.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/_gate_read_callshape.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
