<?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-13-3-gate-execution-targets-through-kernel-surface-selector/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-13-3-gate-execution-targets-through-kernel-surface-selector/</id>
  <title>ADR: Gate execution targets a surface through a kernel selector and the topology placement seam</title>
  <updated>2026-08-13T00: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-13-3-gate-execution-targets-through-kernel-surface-selector/"/>
  <summary>A gate declares an executionTarget from a kernel-owned surface-selector vocabulary; the placement seam gains an execute verb that resolves it to a physical workdir.</summary>
  <content type="html">&lt;h2 id=&quot;gate-execution-targets-a-surface-through-a-kernel-selector-and-the-topology-placement-seam&quot;&gt;Gate execution targets a surface through a kernel selector and the topology placement seam&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-13-3-gate-execution-targets-through-kernel-surface-selector.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Proposed&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-13&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Operator (ATDD)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Depends on &lt;a href=&quot;/adr/3.x/2026-08-13-2-gates-are-declarative-asset-backed-doctrine-artefacts/&quot;&gt;ADR 2026-08-13-2&lt;/a&gt;.
A declarative gate that executes an asset needs a defined &lt;strong&gt;working directory / execution
context&lt;/strong&gt;. Rather than a free-form enum, this reuses the existing placement seam.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;post-dialectics-revision-2026-08-13&quot;&gt;Post-dialectics revision (2026-08-13)&lt;/h2&gt;
&lt;p&gt;Hardened after the dialectics pass (&lt;code dir=&quot;auto&quot;&gt;work/gate-design-dialectics/02-...&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;99-COHERENCE.md&lt;/code&gt;). Settled deltas:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;CHANGE — no kernel elevation.&lt;/strong&gt; Doctrine only needs to validate a token &lt;strong&gt;string&lt;/strong&gt;, so
&lt;strong&gt;doctrine owns the surface-selector &lt;code dir=&quot;auto&quot;&gt;frozenset[str]&lt;/code&gt;&lt;/strong&gt; (it owns the gate schema anyway),
&lt;strong&gt;specify_cli owns the resolver map&lt;/strong&gt;, and a &lt;strong&gt;parity test&lt;/strong&gt; binds them. Layer directionality
is satisfied with &lt;strong&gt;zero kernel change&lt;/strong&gt;. Option C below (ship &lt;code dir=&quot;auto&quot;&gt;MissionTopology&lt;/code&gt; into doctrine)
and the “elevate a vocabulary into kernel” framing are &lt;strong&gt;superseded&lt;/strong&gt; by this.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CHANGE — &lt;code dir=&quot;auto&quot;&gt;execute_dir&lt;/code&gt; ≠ &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt;.&lt;/strong&gt; It must &lt;strong&gt;reuse the existing stamped
&lt;code dir=&quot;auto&quot;&gt;GateExecutionContext&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;build_gate_execution_context&lt;/code&gt;, honouring &lt;code dir=&quot;auto&quot;&gt;surface_cannot_hold&lt;/code&gt;),
never return a bare &lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt; — a bare workdir strips the surface stamp and reopens the
#2885/#1834 pass-by-default-against-empty-tree failure. &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; additionally needs a &lt;code dir=&quot;auto&quot;&gt;wp_id&lt;/code&gt;
and the materialization-aware &lt;code dir=&quot;auto&quot;&gt;resolve_workspace_for_wp&lt;/code&gt; (a different resolver from reads).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CLARIFY — &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; is a loud, non-default escape hatch&lt;/strong&gt; (“judge the ambient checkout”),
never the default selector.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;A gate that runs a check needs to know &lt;em&gt;where&lt;/em&gt; it runs — the repo root, the mission’s
primary planning tree, the coord status tree, or a WP lane worktree. Which physical tree each
of those is depends on the mission’s &lt;strong&gt;topology&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;That mapping already exists. The &lt;strong&gt;placement seam&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;docs/architecture/artifact-placement-seam.md&lt;/code&gt;) resolves &lt;code dir=&quot;auto&quot;&gt;(MissionArtifactKind, MissionTopology, materialization)&lt;/code&gt; → a &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:22&lt;/code&gt;)
→ a physical tree, via &lt;code dir=&quot;auto&quot;&gt;PlacementSeam&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/resolution.py:1373&lt;/code&gt;). It answers
&lt;strong&gt;read_dir&lt;/strong&gt; and &lt;strong&gt;write_target&lt;/strong&gt; today. It does &lt;strong&gt;not&lt;/strong&gt; answer “execute in”.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;MissionTopology&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/context.py:55&lt;/code&gt;) is the 2×2 coord×lanes grid
(&lt;code dir=&quot;auto&quot;&gt;SINGLE_BRANCH&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;LANES&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;LANES_WITH_COORD&lt;/code&gt;). It lives in &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;,
which is &lt;strong&gt;above &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt;&lt;/strong&gt; in the layer graph (&lt;code dir=&quot;auto&quot;&gt;kernel ← doctrine ← charter ← runtime&lt;/code&gt;).
A doctrine-layer gate schema that referenced it would be an &lt;strong&gt;upward import&lt;/strong&gt; — a layering
violation.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;One mechanism for “where to look / write / run” — do not fork a second workdir resolver.&lt;/li&gt;
&lt;li&gt;Respect layer directionality (doctrine must not import upward into &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Keep the doctrine schema’s dependency footprint minimal.&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;A — Free-form workdir enum on the gate&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;mission_dossier&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;wp_worktree&lt;/code&gt;), resolved by a new gate-local helper.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B — Surface selector routed through the placement seam.&lt;/strong&gt; The gate declares an
&lt;code dir=&quot;auto&quot;&gt;executionTarget&lt;/code&gt; from a small &lt;strong&gt;kernel-owned&lt;/strong&gt; surface-selector vocabulary; the
topology-aware seam gains an &lt;code dir=&quot;auto&quot;&gt;execute_dir&lt;/code&gt; verb that resolves it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C — Ship the whole &lt;code dir=&quot;auto&quot;&gt;MissionTopology&lt;/code&gt; enum down into &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt;&lt;/strong&gt; so the gate schema types the field against it directly.&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: “B”.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A gate carries &lt;code dir=&quot;auto&quot;&gt;executionTarget: &amp;#x3C;selector&gt;&lt;/code&gt; where the selector comes from a &lt;strong&gt;small
surface-selector vocabulary elevated into &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt;&lt;/strong&gt; (e.g. &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; |
&lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;). Kernel is the root layer, so &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; may import it without violating
directionality. &lt;code dir=&quot;auto&quot;&gt;src/kernel/&lt;/code&gt; already hosts this class of shared primitive (&lt;code dir=&quot;auto&quot;&gt;paths.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;clock.py&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;The placement seam gains a &lt;strong&gt;third verb, &lt;code dir=&quot;auto&quot;&gt;execute_dir&lt;/code&gt;&lt;/strong&gt;, over the same
&lt;code dir=&quot;auto&quot;&gt;(surface, topology, materialization)&lt;/code&gt; inputs it already uses for &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;write_target&lt;/code&gt;.
The topology &lt;em&gt;math&lt;/em&gt; stays in &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;; doctrine only names a selector.&lt;/li&gt;
&lt;li&gt;Option C is rejected — it drags a runtime-shaped enum into the doctrine layer. Option A is
rejected — it forks a second “where” resolver the placement seam already owns.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This subsumes the gate’s working-directory question into the one partition decision every
other mission artifact already routes through: in &lt;code dir=&quot;auto&quot;&gt;SINGLE_BRANCH&lt;/code&gt; all selectors collapse to
primary; in &lt;code dir=&quot;auto&quot;&gt;LANES_WITH_COORD&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;coord&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; diverge, exactly as reads/writes do.&lt;/p&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;Gate execution location is topology-correct for free, and consistent with read/write placement.&lt;/li&gt;
&lt;li&gt;Elevating the selector strengthens the seam (the placement doc notes callers that still bypass it).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Elevating a vocabulary into &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; + adding a seam verb is cross-cutting (touches kernel,
the placement seam, and the gate schema) — larger than a gate-local field.&lt;/li&gt;
&lt;li&gt;The selector vocabulary and &lt;code dir=&quot;auto&quot;&gt;MissionTopology&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; must be kept in sync; a
contract test is required to prevent drift.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Whether the elevated vocabulary is a brand-new selector enum or a subset of the existing
&lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; is a design detail (open Q).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;open-questions-for-the-dialectics-squad&quot;&gt;Open questions (for the dialectics squad)&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;New kernel selector enum, or elevate/reuse &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; itself?&lt;/li&gt;
&lt;li&gt;Is &lt;code dir=&quot;auto&quot;&gt;execute_dir&lt;/code&gt; truly the same resolution as &lt;code dir=&quot;auto&quot;&gt;read_dir&lt;/code&gt;, or does execution need a distinct
materialization rule (e.g. must the lane worktree already exist)?&lt;/li&gt;
&lt;li&gt;Do gates ever need to run &lt;em&gt;outside&lt;/em&gt; any mission surface (e.g. repo-root global checks), and
is &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; a first-class selector or an escape hatch?&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
