<?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-08-12-1-checkout-ownership-for-mission-create-and-next/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-12-1-checkout-ownership-for-mission-create-and-next/</id>
  <title>ADR: Explicit Checkout Ownership for Mission Create and Next</title>
  <updated>2026-08-12T00: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-08-12-1-checkout-ownership-for-mission-create-and-next/"/>
  <summary>Introduces a fail-closed, Git-topology-validated ownership claim so mission create and next can use an exact linked-checkout root without ambient primary fallback.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission create&lt;/code&gt; historically refuses invocation from a linked
worktree. &lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt; either refuses paths recognized by its &lt;code dir=&quot;auto&quot;&gt;.worktrees&lt;/code&gt;
guard or collapses a generic linked worktree to the repository-root checkout.
Removing those guards would not make worktree operation safe: ambient project-root
discovery would still let mission content, refs, or runtime state cross into the
repository-root checkout.&lt;/p&gt;
&lt;p&gt;This is the narrow mitigation identified by &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3129&quot;&gt;#3129&lt;/a&gt;: commands need an explicit
write boundary before the broader scoped-shadow-workspace design is attempted.
It also supplies a prerequisite for &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3128&quot;&gt;#3128&lt;/a&gt;. This decision establishes an owned
checkout before or while mission identity is becoming readable; #3128 remains
responsible for making later mission-mutating commands compare their caller with
the workspace already declared by a mission.&lt;/p&gt;
&lt;p&gt;The detailed domain vocabulary and observable CLI contract remain canonical in
the mission’s &lt;a href=&quot;../../../kitty-specs/worktree-owned-root-3328-01KZRG01/data-model.md&quot;&gt;data model&lt;/a&gt; and &lt;a href=&quot;../../../kitty-specs/worktree-owned-root-3328-01KZRG01/contracts/checkout-ownership-cli-contract.md&quot;&gt;checkout-ownership CLI contract&lt;/a&gt;. This ADR records
why the boundary exists and which authority is allowed to establish it.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Preserve the fail-closed behavior of every caller that does not opt in.&lt;/li&gt;
&lt;li&gt;Accept only an exact Git checkout root belonging to the expected common
repository; a checkout subdirectory must never self-certify.&lt;/li&gt;
&lt;li&gt;Keep the owned root explicit through mission-content, runtime-state, ref, and
commit decisions instead of rediscovering it from CWD.&lt;/li&gt;
&lt;li&gt;Recognize generic linked-worktree paths, not only a &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; convention.&lt;/li&gt;
&lt;li&gt;Keep production &lt;code dir=&quot;auto&quot;&gt;allow_worktree_context=True&lt;/code&gt; unavailable as an authorization
mechanism.&lt;/li&gt;
&lt;li&gt;Prove isolation with an immutable installed CLI artifact, not an editable
install or a mocked command.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;one-explicit-ownership-primitive&quot;&gt;One explicit ownership primitive&lt;/h3&gt;
&lt;p&gt;Adopt &lt;code dir=&quot;auto&quot;&gt;OwnershipClaim&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;OwnershipValidationResult&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;specify_cli.core.checkout_ownership&lt;/code&gt; as the single validation authority shared
by &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;An opted-in claim contains the exact claimed checkout root, an independently
resolved repository-root checkout, and one structured result: &lt;code dir=&quot;auto&quot;&gt;OWNED&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;NESTED&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;FOREIGN_OR_MISMATCHED&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;BROKEN_POINTER&lt;/code&gt;. Omitting the opt-in
produces &lt;code dir=&quot;auto&quot;&gt;UNOWNED_NO_OPT_IN&lt;/code&gt; and retains the existing command behavior.&lt;/p&gt;
&lt;p&gt;Validation reuses the fail-closed common-directory comparator used by
&lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt;, confirms that the claim is the Git toplevel rather than a
subdirectory, and consults &lt;code dir=&quot;auto&quot;&gt;git worktree list --porcelain&lt;/code&gt; for generic registry
membership and nested-root checks. Git probe failures are refusals; they do not
activate a fallback.&lt;/p&gt;
&lt;h3 id=&quot;a-narrow-cli-affordance&quot;&gt;A narrow CLI affordance&lt;/h3&gt;
&lt;p&gt;Expose &lt;code dir=&quot;auto&quot;&gt;--owned-checkout PATH&lt;/code&gt; only on:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent mission create&lt;/code&gt;; and&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty next&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The option names an exact checkout root for that invocation. It is not inferred
from CWD, environment variables, path naming, or the nearest &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt;
directory. Structured refusals distinguish nested, foreign/mismatched, broken
pointer, and no-opt-in cases.&lt;/p&gt;
&lt;p&gt;An owned &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; uses the validated checkout as its content and ref
boundary. During the short interval before mission identity is readable,
&lt;code dir=&quot;auto&quot;&gt;resolve_create_time_write_target(planning_branch)&lt;/code&gt; carries the already-derived
short planning branch into a &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt;. That pure seam performs no CWD,
environment, topology, mission-directory, or ambient-root discovery. Ordinary
post-identity writes continue through the existing placement authority.&lt;/p&gt;
&lt;p&gt;An owned &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; threads the validated effective root through command, decision,
runtime bridge, mission-context resolution, and owned-mutation persistence.
Mission content and per-checkout runtime state resolve from that same root even
when the command is launched from the repository-root checkout. No opted-in
layer may replace it with &lt;code dir=&quot;auto&quot;&gt;get_main_repo_root&lt;/code&gt; or another ambient resolver.&lt;/p&gt;
&lt;h3 id=&quot;isolation-and-contention-boundaries&quot;&gt;Isolation and contention boundaries&lt;/h3&gt;
&lt;p&gt;The owned checkout receives its mission content, per-checkout runtime state,
mission refs, and command-produced commits. The repository-root checkout and
sibling linked worktrees receive none of those writes.&lt;/p&gt;
&lt;p&gt;Git’s worktree registry remains a shared Git resource. Coordination-worktree
materialization therefore permits a bounded retry only for positive, recognized
registry-contention evidence. Permission failures and unrelated or permanent
errors re-raise unchanged; the retry does not introduce a persistent lock.
The existing shared status lock, which serializes intentionally convergent
planning writes through the common Git directory, is not reclassified as
per-checkout state.&lt;/p&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;Accidental ambient primary fallback is no longer an authorization path for
opted-in mission creation or advancement.&lt;/li&gt;
&lt;li&gt;The same structured claim and refusal taxonomy govern both CLI surfaces.&lt;/li&gt;
&lt;li&gt;Generic linked worktrees work without weakening the legacy default guards.&lt;/li&gt;
&lt;li&gt;#3128 can consume a validated ownership fact instead of inventing another Git
topology comparator.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative-and-accepted-trade-offs&quot;&gt;Negative and accepted trade-offs&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Explicit-root propagation adds parameters across the &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; decision and
runtime-bridge layers; this duplication is intentional because rediscovery
would erase the security boundary.&lt;/li&gt;
&lt;li&gt;Concurrent missions still contend briefly on Git’s shared worktree registry.
The bounded, signature-specific retry treats that Git implementation detail
without pretending the object store and refs are physically separate.&lt;/li&gt;
&lt;li&gt;This decision does not deliver the scoped-handle/shadow-workspace redesign in
#3129 and does not complete #3128’s caller-versus-declared-workspace guard.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;verification-and-ci-follow-up&quot;&gt;Verification and CI follow-up&lt;/h3&gt;
&lt;p&gt;Acceptance for #3328 is the real installed-wheel test
&lt;code dir=&quot;auto&quot;&gt;tests/e2e/test_worktree_owned_root_concurrency.py&lt;/code&gt;: an immutable wheel drives
two actual linked worktrees concurrently and proves distinct mission identity,
content roots, refs, runtime state, lock cleanup, and clean repository-root/A/B
checkouts. The reviewed local 20-iteration run is the authoritative #3328
mission proof until &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3343&quot;&gt;#3343&lt;/a&gt; lands; it does not claim CI coverage or override the
mainline release gate.&lt;/p&gt;
&lt;p&gt;#3343 owns the missing CI selection contract. Its job must positively select
this file, build and run a non-editable immutable wheel, publish source-commit
and wheel-SHA provenance plus JUnit evidence, and make trigger, timeout,
quality-gate dependency, coverage-consumer, and collection-completeness behavior
explicit. Existing broad jobs must not silently exclude the proof or duplicate
unrelated distribution suites.&lt;/p&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;reuse-or-loosen-allow_worktree_context&quot;&gt;Reuse or loosen &lt;code dir=&quot;auto&quot;&gt;allow_worktree_context&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Rejected. That parameter is a test/programmatic compatibility escape hatch, not
a Git-topology ownership claim. Promoting it to production authorization would
bypass the exact invariant this decision adds.&lt;/p&gt;
&lt;h3 id=&quot;extend-the-worktrees-literal-execution-context-guard&quot;&gt;Extend the &lt;code dir=&quot;auto&quot;&gt;.worktrees&lt;/code&gt;-literal execution-context guard&lt;/h3&gt;
&lt;p&gt;Rejected. Directory naming cannot prove common-repository membership, exact
checkout-root identity, or ownership for a generic linked worktree. It also does
not solve the separate pre-identity &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; boundary.&lt;/p&gt;
&lt;h3 id=&quot;infer-the-owned-root-from-ambient-project-discovery&quot;&gt;Infer the owned root from ambient project discovery&lt;/h3&gt;
&lt;p&gt;Rejected. Ambient discovery currently collapses linked worktrees to the
repository-root checkout. Treating that result as authority would preserve the
cross-write defect while making it harder to observe.&lt;/p&gt;
&lt;h3 id=&quot;adopt-scoped-shadow-workspaces-now&quot;&gt;Adopt scoped shadow workspaces now&lt;/h3&gt;
&lt;p&gt;Deferred to #3129. A capability-scoped handle is the stronger structural end
state, but it is a broader execution-model decision. Explicit validated
ownership is the independently useful, fail-closed prerequisite.&lt;/p&gt;
&lt;h2 id=&quot;amendments&quot;&gt;Amendments&lt;/h2&gt;
&lt;h3 id=&quot;2026-09-28--validator-routed-next-and-validated-flagless-adoption&quot;&gt;2026-09-28 — Validator-routed &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and validated flagless adoption&lt;/h3&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;owned-checkout-lifecycle-authority-01M3M2ZB&lt;/code&gt;; extended by &lt;a href=&quot;/adr/3.x/2026-09-03-1-explicit-owned-checkout-single-branch-lifecycle/&quot;&gt;ADR 2026-09-03-1&lt;/a&gt; (Amendments).&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The claim primitive has one caller.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;resolve_ownership_claim&lt;/code&gt; remains the primitive this ADR introduced. Its only caller is now the canonical validator in &lt;code dir=&quot;auto&quot;&gt;specify_cli.core.owned_mission&lt;/code&gt; (gate G1). &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; previously called the primitive directly (&lt;code dir=&quot;auto&quot;&gt;next_cmd.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;core/mission_creation.py&lt;/code&gt;); &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; now goes through &lt;code dir=&quot;auto&quot;&gt;resolve_owned_mission(..., allowed_topologies=NEXT_OWNED_TOPOLOGIES)&lt;/code&gt; and create through &lt;code dir=&quot;auto&quot;&gt;resolve_owned_create_root&lt;/code&gt;. Consequence: &lt;code dir=&quot;auto&quot;&gt;next --owned-checkout&lt;/code&gt; now also enforces the branch-equals-target and protected-destination checks that every other owned command applies (FR-002; spec observation O9).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The repository root checkout is refused as an owned checkout.&lt;/strong&gt; The primitive still classifies the repository root checkout as &lt;code dir=&quot;auto&quot;&gt;OWNED&lt;/code&gt; (its self-ownership semantics are unchanged, and pinned by tests). The minter refuses it with &lt;code dir=&quot;auto&quot;&gt;OWNED_CHECKOUT_IS_REPOSITORY_ROOT&lt;/code&gt; (FR-020, research R-14).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Validated flagless adoption&lt;/strong&gt; (qualifies “It is not inferred from CWD, environment variables, path naming, or the nearest &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt; directory”, A narrow CLI affordance). The explicit flag is still never inferred. Separately, a flagless owned-capable command run from &lt;strong&gt;inside a linked checkout&lt;/strong&gt; adopts that checkout &lt;strong&gt;only&lt;/strong&gt; if the canonical validator accepts it (decision &lt;code dir=&quot;auto&quot;&gt;01M3M4GT…&lt;/code&gt;, FR-021). Five cases keep today’s repository-root behaviour instead of adopting: the repository root checkout itself, a lane worktree (identified by &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt; membership), a coordination worktree (&lt;code dir=&quot;auto&quot;&gt;classify_worktree_topology&lt;/code&gt;), a checkout of another repository, and any checkout the validator rejects for any other reason. The same-selector-different-mission-id conflict this ADR did not anticipate is refused as a mission-context conflict, the same refusal a repository-root run already uses. The retirement: &lt;code dir=&quot;auto&quot;&gt;missions/operation_context.py&lt;/code&gt;, which adopted the CWD as owned without going through the canonical validator, is deleted (research R-09).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Create-time governance reads follow the owned checkout; charter authoring stays at the repository root.&lt;/strong&gt; Charter activation, mission-type context and the spec template are read from the owned checkout for an owned &lt;code dir=&quot;auto&quot;&gt;agent mission create&lt;/code&gt; (FR-016, C-004). Charter &lt;strong&gt;authoring&lt;/strong&gt; stays repository-root-only (#4785, FR-017), unchanged by this mission. Invoking charter commands from an owned checkout is out of scope here and belongs to #4250.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Coordination-workspace probe failure is typed.&lt;/strong&gt; Owned &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; against a coordination topology is still supported. A failing coordination-workspace probe (the #4867 zero-byte &lt;code dir=&quot;auto&quot;&gt;commondir&lt;/code&gt; case) now yields a &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; decision with &lt;code dir=&quot;auto&quot;&gt;OWNED_COORDINATION_WORKSPACE_UNAVAILABLE&lt;/code&gt; instead of an uncaught git fatal. The bounded transient-lock retry described in “Isolation and contention boundaries” is unchanged (FR-012).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Supersedes the “explicit-root propagation” trade-off&lt;/strong&gt; (Consequences, Negative and accepted trade-offs: “Explicit-root propagation adds parameters across the &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; decision and runtime-bridge layers”). That per-call-site threading is replaced by one immutable &lt;code dir=&quot;auto&quot;&gt;OwnedCheckout&lt;/code&gt; fact carried on &lt;code dir=&quot;auto&quot;&gt;DecideNextContext&lt;/code&gt; and the prompt builder.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Verification.&lt;/strong&gt; The per-PR proof for coordination-topology owned &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt; is an in-process CLI twin — &lt;code dir=&quot;auto&quot;&gt;tests/integration/test_owned_lifecycle_acceptance_next.py&lt;/code&gt; (FR-022) — run on every PR. The nightly-only real-worktree e2e proof, &lt;code dir=&quot;auto&quot;&gt;tests/e2e/test_worktree_owned_root_concurrency.py&lt;/code&gt;, is unchanged and still runs only in the nightly job; this mission adds no per-PR real-worktree coverage beyond the in-process twin.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Core issue: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3328&quot;&gt;#3328&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Caller/workspace mismatch follow-up: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3128&quot;&gt;#3128&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Scoped shadow-workspace design: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3129&quot;&gt;#3129&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Immutable-install and stale-worktree hazard: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1907&quot;&gt;#1907&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;CI selection follow-up: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3343&quot;&gt;#3343&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Related decision: &lt;a href=&quot;/adr/3.x/2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches/&quot;&gt;Execution Lanes Own Worktrees and Mission Branches&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Related decision: &lt;a href=&quot;/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; Owner and &lt;code dir=&quot;auto&quot;&gt;CommitTarget&lt;/code&gt; Atomicity&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Owned-checkout lifecycle authority mission: &lt;a href=&quot;../../../kitty-specs/owned-checkout-lifecycle-authority-01M3M2ZB/spec.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/owned-checkout-lifecycle-authority-01M3M2ZB/spec.md&lt;/code&gt;&lt;/a&gt;, &lt;a href=&quot;../../../kitty-specs/owned-checkout-lifecycle-authority-01M3M2ZB/plan.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
