<?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-10-1-scoped-shadow-workspace-write-boundary-layers-onto-the-partition/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-10-1-scoped-shadow-workspace-write-boundary-layers-onto-the-partition/</id>
  <title>ADR: a scoped workspace handle layers onto the coordination/primary partition (it does not replace it)</title>
  <updated>2026-10-10T00: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-10-1-scoped-shadow-workspace-write-boundary-layers-onto-the-partition/"/>
  <summary>The #3129 write-boundary class is one shared root cause; the fix is a capability-scoped write handle layered onto the existing partition (Option B), not a foreign shadow topology.</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-10&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner, Option B chosen 2026-10-09; ADR accepted 2026-10-10), via the governed design-spike mission &lt;code dir=&quot;auto&quot;&gt;scoped-shadow-workspace-write-boundary-01M4H5FQ&lt;/code&gt; (merged in PR &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/pull/5986&quot;&gt;#5986&lt;/a&gt;). This ADR formalises and code-grounds that decision; it does not re-open it.&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/3129&quot;&gt;#3129&lt;/a&gt; — “scoped shadow workspaces: the shared root behind the worktree/write-path issue class” (design-spike, P1). The decision record and the options analysis live in the merged mission artifacts at &lt;code dir=&quot;auto&quot;&gt;kitty-specs/scoped-shadow-workspace-write-boundary-01M4H5FQ/research.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;. The first increment of the chosen direction already landed: PR &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/pull/5986&quot;&gt;#5986&lt;/a&gt; closed &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2334&quot;&gt;#2334&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;Issue #3129 does not ask for an implementation. It asks the owner to classify a &lt;em&gt;write-boundary topology&lt;/em&gt;: across fourteen issues framed as separate bugs, is the recurring root cause real, is it still live, and does a &lt;strong&gt;scoped-shadow-workspace-handle boundary&lt;/strong&gt; — one where “the canonical tree is not merely off-limits, it is &lt;strong&gt;not reachable&lt;/strong&gt; from the handle the agent holds” — &lt;strong&gt;(A)&lt;/strong&gt; replace, &lt;strong&gt;(B)&lt;/strong&gt; layer onto, or &lt;strong&gt;(C)&lt;/strong&gt; prove incompatible with the current coordination/primary partition. ThickTicket’s &lt;code dir=&quot;auto&quot;&gt;internal/workspace/shadow.go&lt;/code&gt; is the cited reference implementation of the alternative topology.&lt;/p&gt;
&lt;p&gt;Three questions must be answered with code-grounded evidence before the direction can be recorded:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Coherent?&lt;/strong&gt; — Is the #3129 cluster one genuine shared root cause, or fourteen unrelated bugs?&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Active?&lt;/strong&gt; — Is it still a live problem after thirteen of its fourteen point-fixes merged, #3128 shipped the fail-closed mitigation, and #2334 (the last open member) was addressed by #5986?&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Solvable by aligning to the existing design?&lt;/strong&gt; — Can it be closed by aligning to the enforced module chain and the single-canonical-authority / public-import SSOT seams, rather than by importing a foreign scoped-shadow-handle topology?&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Terminology (the CLAUDE.md footguns, named explicitly throughout).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; here means the &lt;strong&gt;PRIMARY partition&lt;/strong&gt; (the artifact-home set that lands on the Mission’s &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; for every topology) or the &lt;strong&gt;repository-root checkout&lt;/strong&gt; — never the Primary Branch &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; unless stated. &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; here means &lt;strong&gt;branch integration&lt;/strong&gt; or &lt;strong&gt;lane consolidation&lt;/strong&gt; — never publish-to-origin. &lt;code dir=&quot;auto&quot;&gt;routing&lt;/code&gt; here means &lt;strong&gt;branch-target routing&lt;/strong&gt; (which branch/checkout a write lands on) and &lt;strong&gt;placement&lt;/strong&gt; (kind + topology → surface) — never dispatch/model/event routing.&lt;/p&gt;
&lt;h2 id=&quot;the-three-question-verdict-code-grounded&quot;&gt;The three-question verdict (code-grounded)&lt;/h2&gt;
&lt;h3 id=&quot;1-coherent--yes&quot;&gt;1. Coherent — YES&lt;/h3&gt;
&lt;p&gt;All fourteen issues share one property: &lt;strong&gt;a command derives its write/read target from ambient location (cwd / the worktree it was invoked from) instead of from the Mission’s stored declaration.&lt;/strong&gt; The evidence is structural, not anecdotal:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The artifact-placement seam is &lt;em&gt;already&lt;/em&gt; a clean, CWD-invariant authority. &lt;code dir=&quot;auto&quot;&gt;PlacementSeam&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py&lt;/code&gt;) and its &lt;code dir=&quot;auto&quot;&gt;resolve_artifact_surface&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt; projections derive the physical surface from &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;mission_slug&lt;/code&gt; (the stored topology, read via &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;), “never from the current checkout”; the primary write-dir re-anchors through &lt;code dir=&quot;auto&quot;&gt;get_main_repo_root(self.repo_root)&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt; is partitioned into two home sets (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py&lt;/code&gt;): a PRIMARY kind resolves to the Mission’s &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; for every topology, a COORD kind to the coordination surface, with &lt;code dir=&quot;auto&quot;&gt;kind_is_coordination_residue&lt;/code&gt; deriving coord-routing solely from the stored &lt;code dir=&quot;auto&quot;&gt;MissionTopology&lt;/code&gt; via &lt;code dir=&quot;auto&quot;&gt;routes_through_coordination&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Ambient location enters &lt;strong&gt;upstream of the seam&lt;/strong&gt;, not inside it: &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; is seeded from &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;locate_project_root() or Path.cwd()&lt;/code&gt; at CLI entry points; the write-side resolvers (&lt;code dir=&quot;auto&quot;&gt;locate_project_root&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resolve_canonical_root&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;get_main_repo_root&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/paths.py&lt;/code&gt;) collapse worktree→primary, while the read-side &lt;code dir=&quot;auto&quot;&gt;get_status_read_root&lt;/code&gt; deliberately prefers the current worktree and carries a “READ paths only” contract; and &lt;code dir=&quot;auto&quot;&gt;resolve_primary_branch&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/git_ops.py&lt;/code&gt;) is biased to the checked-out branch when &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; has no &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The invariant is already load-bearing folklore: the hand-placed comment “never &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt; (C-003/#2647)” is replicated across &lt;code dir=&quot;auto&quot;&gt;coordination/transaction.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/emit.py&lt;/code&gt;, and more. The invariant exists; it is enforced per-site, not by construction.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The thirteen merged point-fixes collapse into four recurring shapes (collapse-to-primary resolver reached at a read site; placement WRITE mis-routed by ambient cwd; a fail-closed location assertion bolted on; a guard that self-churns). None changed what a lane fundamentally &lt;em&gt;is&lt;/em&gt; — a checkout sharing the object store and refs with every other checkout. That shared substrate is the permanent supply. &lt;strong&gt;The cluster is one root cause.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;2-active--yes-with-reduced-but-non-zero-residual-risk&quot;&gt;2. Active — YES, with reduced but non-zero residual risk&lt;/h3&gt;
&lt;p&gt;The supply is demonstrably not exhausting: the resolvers were never changed, only call sites; the defect recurred across structurally unrelated command families over quarters (#3051 called itself “the third confirmed command family hitting this exact mechanism”); two agents tripped it independently in one landing pass; and contributors repeatedly noted the point-fixes weren’t closing the class.&lt;/p&gt;
&lt;p&gt;What changed the risk profile but not the root cause:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;#3128&lt;/strong&gt; added &lt;code dir=&quot;auto&quot;&gt;enforce_checkout_identity&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/checkout_identity.py&lt;/code&gt;), a pure-path refusal. It is scoped to &lt;strong&gt;one&lt;/strong&gt; WP-mutation chokepoint — &lt;code dir=&quot;auto&quot;&gt;resolve_workspace_for_wp(write_intent=True)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/workspace/context.py&lt;/code&gt;), which only &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; set true. It refuses rather than redirects, and it does not cover the ~20 read call sites or the other mutating commands (&lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;add-history&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;record-analysis&lt;/code&gt;, …).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#5986&lt;/strong&gt; closed #2334 by retiring the markdown WP Activity Log in favour of &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, removing the last known &lt;em&gt;second writer&lt;/em&gt; for an artifact that already had one authoritative surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Residual risk:&lt;/strong&gt; every mutating command outside the &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; chokepoint still manufactures its write target from ambient location and is protected only by hand-placed per-site assertions. Any &lt;em&gt;new&lt;/em&gt; mutating command re-exposes the identical defect by default. The class is quieter, not closed.&lt;/p&gt;
&lt;h3 id=&quot;3-solvable-by-aligning-to-the-existing-design--yes&quot;&gt;3. Solvable by aligning to the existing design — YES&lt;/h3&gt;
&lt;p&gt;The fix does &lt;strong&gt;not&lt;/strong&gt; require importing ThickTicket’s foreign topology (a shadow workspace living outside the object store, reached only through an &lt;code dir=&quot;auto&quot;&gt;OpenShadowWorkspace&lt;/code&gt; handle). It aligns to what the repository already enforces:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The placement seam is the &lt;strong&gt;single canonical authority&lt;/strong&gt; for read/write surface resolution and is already CWD-invariant. The defect lives strictly &lt;em&gt;upstream&lt;/em&gt; of it, in the ambient &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;/branch seed.&lt;/li&gt;
&lt;li&gt;The enforced module chain (&lt;code dir=&quot;auto&quot;&gt;kernel &amp;#x3C;- charter &amp;#x3C;- {glossary, runtime, mission_runtime} &amp;#x3C;- specify_cli&lt;/code&gt;) already owns the layers the fix touches: &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt; owns the placement authority, &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; owns the command-entry seeds. The write-side handle is the dual of a seam that already exists, reached through public imports — not a new foreign authority.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Aligning to the existing SSOT/modular design beats adopting a shadow-outside-the-store topology, because the latter removes the shared substrate on which the consolidation engine’s correctness proofs are &lt;em&gt;defined&lt;/em&gt;, and would require rebuilding them (see Option A below). This reconciles exactly with the owner’s Option B.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; — close the class at the mechanism, not with a fourteenth per-site patch; the placement seam is the one authority to extend, not duplicate.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Architectural alignment / locality of change&lt;/strong&gt; — keep the fix inside the enforced module chain and the exact layer (command-entry + workspace resolution) the thirteen fixes already churn.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve hard-won correctness&lt;/strong&gt; — the consolidation/rollback engine (CAS ref advance, approval-stamp bound, blob-attribution/closed-world axes, coordination-teardown CAS, the single rollback authority) carries proven, dearly-earned invariants and must not be rewritten to fix a workspace-resolution problem.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Graceful incrementalism&lt;/strong&gt; — the direction must land in independently-valuable increments behind the owner’s pace, not as a big-bang cutover.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A — scoped shadow handles &lt;em&gt;replace&lt;/em&gt; the partition.&lt;/strong&gt; A lane becomes a shadow workspace outside the object store; the canonical tree is unreachable; &lt;code dir=&quot;auto&quot;&gt;ApplyShadowMerge&lt;/code&gt; is the single crossing point. Retires the coordination/primary partition and the whole &lt;code dir=&quot;auto&quot;&gt;routes_through_coordination&lt;/code&gt; machinery.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B — scoped shadow handles &lt;em&gt;layer onto&lt;/em&gt; the partition (CHOSEN).&lt;/strong&gt; Keep the partition and the consolidation engine untouched. Add a capability-narrowed &lt;strong&gt;write handle&lt;/strong&gt; as the only object an execution agent (&lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt;) is given — the write-side dual of the placement seam — through which the canonical tree and sibling lanes are not addressable. Generalises #3128 from “resolve, then refuse on mismatch” to “only ever hand out a handle that cannot address the foreign tree.”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C — incompatible; name reason X and take the cheaper structural step.&lt;/strong&gt; If a true shadow-outside-the-store boundary is judged incompatible, reason X is: &lt;em&gt;the consolidation engine’s correctness proofs are defined over a single shared object store and ref namespace.&lt;/em&gt; The cheaper structural step is a single typed, declaration-first &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;/branch resolution entry at the command-entry layer, replacing the scattered &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt; seeds.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option B (layer a scoped capability handle onto the coordination/primary partition), with Option C’s single declaration-first &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;/branch entry as its first, independently-valuable increment.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Option A is recorded as the deferred &lt;strong&gt;north star&lt;/strong&gt; — the highest-value end state and the truest expression of the issue’s argument — but it is a multi-mission programme (a new consolidation engine), not a spike follow-on, and is not started until explicitly commissioned. Option C is not a distinct destination: its structural step is subsumed as Increment 1 of Option B.&lt;/p&gt;
&lt;p&gt;This is the owner’s call, taken on 2026-10-09 and recorded in the merged mission artifacts. This ADR grounds it in current code and confirms the code does &lt;strong&gt;not&lt;/strong&gt; contradict it: the placement seam being already CWD-invariant is precisely why the handle is a &lt;em&gt;layer&lt;/em&gt; (narrowing what the agent can address) and not a &lt;em&gt;replacement&lt;/em&gt; (which would have to re-home every lane’s storage and rebuild the engine’s proofs).&lt;/p&gt;
&lt;h3 id=&quot;where-the-write-boundary-sits-and-which-ssot-seam-owns-it&quot;&gt;Where the write boundary sits, and which SSOT seam owns it&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The authority is the placement seam&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;artifacts.py&lt;/code&gt;), which already answers “which physical surface does this artifact live on” from the stored declaration. The scoped handle is its &lt;strong&gt;write-side dual&lt;/strong&gt;: a capability object (conceptually a &lt;code dir=&quot;auto&quot;&gt;WriteLocation&lt;/code&gt;-like value in &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;) that carries the &lt;em&gt;only&lt;/em&gt; paths/branches an agent may touch, so a bare &lt;code dir=&quot;auto&quot;&gt;git&lt;/code&gt;/path write outside them has no handle to reach.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The boundary is installed at the command-entry + workspace-resolution layer&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/workspace/context.py&lt;/code&gt; and the CLI entry points), the same layer the thirteen fixes already modify and the layer that today carries the “never &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt;” invariant by hand.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lanes stay lanes.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;routes_through_coordination&lt;/code&gt;, lane consolidation, branch integration, rollback, and the approval-stamp bound are untouched. The handle changes &lt;em&gt;what an agent can address&lt;/em&gt;, not &lt;em&gt;how lanes integrate&lt;/em&gt; or &lt;em&gt;where they are stored&lt;/em&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;incremental-roadmap&quot;&gt;Incremental roadmap&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Done — #2334 slice (PR #5986).&lt;/strong&gt; Retire the markdown WP Activity Log in favour of &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, eliminating the last known second writer for an already-authoritative surface. This was the first increment; it changed no write-path seam.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Increment 1 (next, Option C’s step, independently valuable).&lt;/strong&gt; A single typed “resolve the Mission’s write target from its declaration” entry at the command-entry layer, replacing the scattered &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt; seeds and folding in the hand-placed “never &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt;” assertions. Closes the collapse-to-primary and mis-routed-WRITE shapes by removing the ambient seed; useful even if the full handle is never built.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Increment 2 (design required before any structural step).&lt;/strong&gt; The capability-handle design proper — the write-side dual of the placement seam, generalised from #3128’s single-chokepoint refusal to the mutating-command surface. A separately-commissioned mission with its own spec/design.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Deferred north star (Option A).&lt;/strong&gt; Re-express consolidation over a shadow-outside-the-store model. Not started until explicitly commissioned.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Separate track, any time.&lt;/strong&gt; SugarFang-style mirrored-shadow &lt;em&gt;provenance&lt;/em&gt; (orthogonal to A/B/C) if the replayable-trust story is wanted — a new issue.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Already in flight, non-blocking.&lt;/strong&gt; PR #5957 / #3215 binds the Shadow Clone &lt;em&gt;dev-env shell activation&lt;/em&gt; to the current worktree; it operates at the shell layer, not the &lt;code dir=&quot;auto&quot;&gt;src/**&lt;/code&gt; write-path seam, and neither waits on nor blocks this decision.&lt;/li&gt;
&lt;/ol&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 §class defect converts from a per-call-site patch stream into a constructed boundary — the only thing shown to actually stop the supply.&lt;/li&gt;
&lt;li&gt;The consolidation/rollback engine keeps its proven invariants; none of Option A’s engine-rebuild risk is incurred.&lt;/li&gt;
&lt;li&gt;Blast radius stays in the familiar command-entry + workspace-resolution layer, inside the enforced module chain.&lt;/li&gt;
&lt;li&gt;The direction degrades gracefully: Increment 1 is valuable standalone.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Option B is still real work: every mutating command must be migrated to accept and honour a handle instead of a cwd-derived &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;, and the read-preferring &lt;code dir=&quot;auto&quot;&gt;get_status_read_root&lt;/code&gt; must be kept legitimately read-only.&lt;/li&gt;
&lt;li&gt;It does &lt;strong&gt;not&lt;/strong&gt; remove the shared object store (the permanent supply); it makes the foreign tree unaddressable &lt;em&gt;through the handle&lt;/em&gt;, so a deliberate bare-&lt;code dir=&quot;auto&quot;&gt;git&lt;/code&gt; call outside the handle is still physically possible. Only Option A removes the substrate.&lt;/li&gt;
&lt;li&gt;The physical N-copies of tracked &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; files across worktrees remain (inherent to &lt;code dir=&quot;auto&quot;&gt;git worktree&lt;/code&gt; sharing one object store); the seam makes one surface authoritative but cannot make the other copies not exist.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;#3128’s refusal remains correct and in place; Option B generalises it rather than retiring it.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; stays an in-repo coordination artifact (an Option A migration would have to re-home it; Option B does not).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;The decision is validated if, after Increment 1, a newly-added mutating command cannot reach the collapse-to-primary / mis-routed-WRITE shapes without going through the single declaration-first entry (enforced by a non-vacuous architectural gate per Standing Order #5), and the per-site “never &lt;code dir=&quot;auto&quot;&gt;Path.cwd()&lt;/code&gt;” assertions can begin to retire. Confidence is high that the direction is correct (it matches the owner’s call and the code grounding is consistent); the open design risk is sizing Increment 2’s handle, deferred to its own mission.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a--replace-the-partition&quot;&gt;Option A — replace the partition&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; the defect class becomes &lt;em&gt;unreachable&lt;/em&gt;, not merely refused; “do not write to someone else’s tree” becomes a property of the object graph; the shared-object-store supply is gone.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; very high blast radius — consolidation is built entirely on shared refs and one object store; a shadow-outside-the-store model re-expresses CAS ref advance, the approval-stamp bound, blob-attribution/closed-world, the coordination-teardown CAS and the single rollback authority as a cross-repository problem. It is a new consolidation engine, not a seam swap, and also re-homes the in-repo status model. A programme, not a spike follow-on.&lt;/p&gt;
&lt;h3 id=&quot;option-b--layer-onto-the-partition-chosen&quot;&gt;Option B — layer onto the partition (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; preserves the proven consolidation/rollback machinery and per-lane parallelism; converts the class from per-call-site patching into a constructed boundary; blast radius bounded to the layer the thirteen fixes already churn; degrades gracefully into independently-valuable increments.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; moderate migration cost across every mutating command; does not remove the shared substrate (a deliberate bare-&lt;code dir=&quot;auto&quot;&gt;git&lt;/code&gt; write outside the handle stays physically possible); physical N-copies persist.&lt;/p&gt;
&lt;h3 id=&quot;option-c--incompatible-name-reason-x&quot;&gt;Option C — incompatible; name reason X&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; the cheapest structural step (one declaration-first resolution entry) still attacks the supply by removing the ambient seed, and is valuable on its own.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; strictly less than B — no capability handle, no unreachability; writes stay &lt;em&gt;possible&lt;/em&gt;, merely &lt;em&gt;correctly targeted by default&lt;/em&gt;; the self-churn / ambient-history shapes remain per-site. Chosen only as B’s first increment, not as a standalone destination.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Decision record and full options analysis: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/scoped-shadow-workspace-write-boundary-01M4H5FQ/research.md&lt;/code&gt; (code citations in its Appendix) and &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Issue: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3129&quot;&gt;#3129&lt;/a&gt;. First increment: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2334&quot;&gt;#2334&lt;/a&gt; via PR &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/pull/5986&quot;&gt;#5986&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;The cheap mitigation it generalises: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3128&quot;&gt;#3128&lt;/a&gt;, &lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/checkout_identity.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Related in-flight dev-env work (non-blocking): PR #5957 / &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3215&quot;&gt;#3215&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Architecture: &lt;a href=&quot;/architecture/execution-lanes/&quot;&gt;execution-lanes.md&lt;/a&gt;, &lt;a href=&quot;/architecture/artifact-placement-seam/&quot;&gt;artifact-placement-seam.md&lt;/a&gt;; the &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;routing&lt;/code&gt; disambiguations in &lt;a href=&quot;/context/orchestration/&quot;&gt;orchestration.md&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
