<?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-07-08-1-mission-resolver-port/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-08-1-mission-resolver-port/</id>
  <title>ADR: MissionResolver Port — One Walk Trunk, Shell-Side DI, No Shared Container</title>
  <updated>2026-07-08T00: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-07-08-1-mission-resolver-port/"/>
  <summary>One `MissionResolver` Protocol in `mission_runtime` with adapters injected shell-side and a token-keyed AST allowlist — no second Protocol and no shared container.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The Phase 1 gate (&lt;a href=&quot;/adr/3.x/2026-06-26-1-single-authority-seam-and-call-site-gate/&quot;&gt;2026-06-26-1&lt;/a&gt;)
closed the #2164 canonicalization-fold and #2160 coord-authority classes with a
seam-plus-AST-gate, but deliberately deferred the deeper defect this mission (#2173
Phase 2) closes: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; is walked from &lt;strong&gt;many&lt;/strong&gt; independent call sites
(&lt;code dir=&quot;auto&quot;&gt;_build_index&lt;/code&gt; in the canonicalizer, &lt;code dir=&quot;auto&quot;&gt;status/identity_audit.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;core/paths.py&lt;/code&gt;, a dashboard scanner, a handful of
&lt;code dir=&quot;auto&quot;&gt;--all&lt;/code&gt;-mode CLI validators, migration scripts, …), each re-implementing the same
&lt;code dir=&quot;auto&quot;&gt;iterdir()&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; read, each re-walking on every call with no shared
in-memory index, and each free to silently diverge from the others’ notion of
“how to find a mission.” Phase 1’s gate fences the canonicalization &lt;em&gt;fold&lt;/em&gt;; it does
not fence &lt;em&gt;walking&lt;/em&gt; itself, so a new raw &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; enumeration can still be
added anywhere in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; without tripping anything.&lt;/p&gt;
&lt;p&gt;This mission ships the Phase 2 follow-on recorded as deferred work in the Phase 1
ADR: a &lt;code dir=&quot;auto&quot;&gt;MissionResolver&lt;/code&gt; Protocol port with one real filesystem adapter
(&lt;code dir=&quot;auto&quot;&gt;FsMissionResolver&lt;/code&gt;) and one in-memory test double (&lt;code dir=&quot;auto&quot;&gt;FakeMissionResolver&lt;/code&gt;), a
single free-function trunk (&lt;code dir=&quot;auto&quot;&gt;resolve_mission&lt;/code&gt;) that every identity-resolution
caller is threaded through (WP01–WP03), and — the subject of this ADR — the
structural gate that makes “one walk” a build-time invariant rather than a
reviewer-memory convention (WP04, mirroring the Phase 1 ADR’s own closing
argument: a convention “leaks” the moment nobody is looking).&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;Bind the “one walk” invariant by construction (D-06).&lt;/strong&gt; Without a structural
gate, the trunk this mission builds is exactly as durable as the last
reviewer’s attention span — a “walker #7” reappears the next time someone needs
a quick mission listing and reaches for &lt;code dir=&quot;auto&quot;&gt;Path.iterdir()&lt;/code&gt; instead of the port.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Full trunk, not a 7th parallel path (D-08).&lt;/strong&gt; The dominant read path reaches
the walk through the &lt;em&gt;free function&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;resolve_mission&lt;/code&gt;, not through an
assembler-injected port alone — so the gate must also guard against
&lt;code dir=&quot;auto&quot;&gt;resolve_mission&lt;/code&gt; callers silently multiplying, not only against raw
&lt;code dir=&quot;auto&quot;&gt;iterdir()&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;glob()&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;scandir()&lt;/code&gt; calls.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Stay inside the existing ledger (D-Q2).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;test_layer_rules.py&lt;/code&gt;’s
&lt;code dir=&quot;auto&quot;&gt;_MISSION_RUNTIME_ALLOWED_SPECIFY_CLI&lt;/code&gt; ledger does not list &lt;code dir=&quot;auto&quot;&gt;&quot;context&quot;&lt;/code&gt;; this
mission’s charter is to &lt;strong&gt;drain&lt;/strong&gt; that ledger, not add to it, so the Protocol
location and the gate’s own imports must not create a new
&lt;code dir=&quot;auto&quot;&gt;mission_runtime → specify_cli.context&lt;/code&gt; edge.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No partial-adoption tax.&lt;/strong&gt; Every genuine &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; walker that predates
this mission must be accounted for on day one — the gate must be green on
introduction, not a slow-burn migration that reds CI the moment it lands.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve the anti-fold carve-outs (C-001/C-002/C-003).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status/identity_audit.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;core/paths.py&lt;/code&gt; have deliberately-different semantics
from the resolver (identity-audit needs the missions the resolver &lt;em&gt;skips&lt;/em&gt;;
&lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt; needs a caller-supplied non-primary scan root under a merge
lock; &lt;code dir=&quot;auto&quot;&gt;core/paths.py&lt;/code&gt;’s error-listing helper is a best-effort swallow-and-degrade,
never fail-closed) — folding them into the resolver would silently change their
behavior, so the gate must &lt;strong&gt;permit&lt;/strong&gt; them, not force them through the trunk.&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;Rely on code review alone&lt;/strong&gt; to catch new raw walkers (status quo after WP01–WP03).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fold every walker into the resolver unconditionally&lt;/strong&gt;, including the three
anti-fold sites (C-001/C-002/C-003).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AST call-site gate + token-keyed allowlist&lt;/strong&gt;, modeled on
&lt;code dir=&quot;auto&quot;&gt;test_protection_resolver_call_sites.py&lt;/code&gt; and the Phase 1 gate — &lt;strong&gt;chosen&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Runtime enforcement&lt;/strong&gt; (e.g., monkeypatch &lt;code dir=&quot;auto&quot;&gt;Path.iterdir&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;Path.glob&lt;/code&gt; process-wide
to detect &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; access outside the resolver).&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “AST call-site gate + token-keyed allowlist” (Option 3).&lt;/p&gt;
&lt;h3 id=&quot;decisions-recorded&quot;&gt;Decisions recorded&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One &lt;code dir=&quot;auto&quot;&gt;MissionResolver&lt;/code&gt; trunk.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;mission_runtime.mission_resolver_port.MissionResolver&lt;/code&gt;
is the sole Protocol; &lt;code dir=&quot;auto&quot;&gt;specify_cli.context.mission_resolver.FsMissionResolver&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;FakeMissionResolver&lt;/code&gt; are the sole adapters. There is no second Protocol, no
second real adapter.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Protocol in &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;, adapters in &lt;code dir=&quot;auto&quot;&gt;specify_cli.context&lt;/code&gt;&lt;/strong&gt; (D-Q2). The
shell (&lt;code dir=&quot;auto&quot;&gt;mission_runtime.resolution&lt;/code&gt;) types its &lt;code dir=&quot;auto&quot;&gt;resolver&lt;/code&gt; parameters against the
local Protocol without importing &lt;code dir=&quot;auto&quot;&gt;specify_cli.context&lt;/code&gt; — no new
&lt;code dir=&quot;auto&quot;&gt;mission_runtime → specify_cli.context&lt;/code&gt; ledger edge. Adapters import the
Protocol via the already-allowed &lt;code dir=&quot;auto&quot;&gt;specify_cli → mission_runtime&lt;/code&gt; (package-root)
direction. &lt;code dir=&quot;auto&quot;&gt;test_layer_rules.py&lt;/code&gt; stays green with &lt;strong&gt;zero new edges&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-seam default-param DI (&lt;code dir=&quot;auto&quot;&gt;x or Default()&lt;/code&gt;), no shared container.&lt;/strong&gt; Every
seam in this mission family (&lt;code dir=&quot;auto&quot;&gt;MissionResolver&lt;/code&gt;, Clock, InstalledVersion) injects
independently at its own call site (&lt;code dir=&quot;auto&quot;&gt;resolver: MissionResolver | None = None&lt;/code&gt;
→ &lt;code dir=&quot;auto&quot;&gt;resolver or FsMissionResolver(repo_root)&lt;/code&gt;). There is &lt;strong&gt;no&lt;/strong&gt; DI container or
registry shared across seams (C-006) — each port is wired where it is consumed,
not resolved through a central object graph.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One adapter per port.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;FsMissionResolver&lt;/code&gt; is the only production adapter;
&lt;code dir=&quot;auto&quot;&gt;FakeMissionResolver&lt;/code&gt; exists solely to make consumers FS-free-testable
(NFR-001). Neither is cached at module or process scope (C-005): no
&lt;code dir=&quot;auto&quot;&gt;@lru_cache&lt;/code&gt;, no singleton — each instance re-walks (or re-reads its in-memory
list) on every call, so a mission created or merged mid-process is visible to
the very next &lt;code dir=&quot;auto&quot;&gt;resolve&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No port on the frozen context.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;MissionExecutionContext&lt;/code&gt; (renamed from
&lt;code dir=&quot;auto&quot;&gt;ExecutionContext&lt;/code&gt; in WP01) remains a plain, frozen, FS-free value object.
&lt;code dir=&quot;auto&quot;&gt;build_execution_context&lt;/code&gt; takes no resolver and performs no I/O; the port is
injected at the shell’s assembler and at the callers that resolve a handle
&lt;em&gt;before&lt;/em&gt; the context exists (&lt;code dir=&quot;auto&quot;&gt;resolve_action_context&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission_context_for&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;resolve_placement_only&lt;/code&gt;) — never inside the pure builder (D-01).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;corollaries-scope-boundaries&quot;&gt;Corollaries (scope boundaries)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The resolver is handle→mission resolution only.&lt;/strong&gt; It is explicitly &lt;strong&gt;not&lt;/strong&gt;:
&lt;ul&gt;
&lt;li&gt;the &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt; field reader (a separate, sibling concern — FR-008 /
&lt;code dir=&quot;auto&quot;&gt;#2139&lt;/code&gt;, delivered as its own WP, not folded into this port);&lt;/li&gt;
&lt;li&gt;the &lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt; aggregate (caller-supplied non-primary scan root,
&lt;code dir=&quot;auto&quot;&gt;mission_number&lt;/code&gt; assignment, under the merge lock — C-002).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The blind-primitive non-fold rule is restated (C-007).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;primary_feature_dir_for_mission&lt;/code&gt;
stays handle-blind, exactly as ADR &lt;code dir=&quot;auto&quot;&gt;2026-06-26-1&lt;/code&gt; established: the
canonicalizer that calls it also calls the resolver’s fold, so folding
canonicalization &lt;em&gt;into&lt;/em&gt; the primitive would recurse. The resolver sits at the
shell, in front of the primitive, never inside it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No new layer-ledger edge (the ledger-dodge).&lt;/strong&gt; This is the direct
continuation of D-Q2 above: #2173’s own charter is to &lt;strong&gt;drain&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;_MISSION_RUNTIME_ALLOWED_SPECIFY_CLI&lt;/code&gt;, not add to it. A design that “solves”
the Protocol-location question by adding &lt;code dir=&quot;auto&quot;&gt;&quot;context&quot;&lt;/code&gt; to the ledger would be
self-defeating — it would grow the very debt ledger this mission exists to pay
down. The chosen split (Protocol in &lt;code dir=&quot;auto&quot;&gt;mission_runtime&lt;/code&gt;, adapters in
&lt;code dir=&quot;auto&quot;&gt;specify_cli.context&lt;/code&gt;, structural typing instead of inheritance) is what makes
a zero-new-edge outcome possible; any future variant of this port must clear
the same bar.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No process cache.&lt;/strong&gt; Restated from C-005 for emphasis: the resolver is
request-scoped. A process-level cache would reintroduce the exact staleness
bug (a mission created mid-process invisible to a stale index) that motivated
moving off the ad-hoc per-caller walks in the first place.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail-closed-loud.&lt;/strong&gt; Ambiguity raises &lt;code dir=&quot;auto&quot;&gt;AmbiguousHandleError&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;MissionSelectorAmbiguous&lt;/code&gt;; a cold-miss raises &lt;code dir=&quot;auto&quot;&gt;MissionNotFoundError&lt;/code&gt; naming
&lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate backfill-identity&lt;/code&gt;. Neither path silently picks a
first match or falls back to a verbatim handle (NFR-005, C-009).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;the-gate-fr-007&quot;&gt;The gate (FR-007)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_mission_resolver_walker_gate.py&lt;/code&gt; enforces three
guarantees:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;G-1 — no unsanctioned raw enumeration.&lt;/strong&gt; No &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; module performs a raw
&lt;code dir=&quot;auto&quot;&gt;iterdir()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;glob()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;scandir()&lt;/code&gt; enumeration of &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; except the
sanctioned resolver module (&lt;code dir=&quot;auto&quot;&gt;specify_cli/context/mission_resolver.py&lt;/code&gt;) and a
&lt;strong&gt;token-keyed allowlist&lt;/strong&gt; of legacy walkers being strangled. The allowlist was
seeded from a &lt;strong&gt;live census grep&lt;/strong&gt;, not copied from the mission’s planning
estimate: the actual count is &lt;strong&gt;19 legacy runtime walker files&lt;/strong&gt; (not the
planning-time “~16” estimate), plus two migration-package directory prefixes
(&lt;code dir=&quot;auto&quot;&gt;upgrade/migrations/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;migration/&lt;/code&gt;) covering 10 migration-only files that must
never depend on the runtime resolver (C-004). Two files the planning notes
named as walkers (&lt;code dir=&quot;auto&quot;&gt;retrospective/summary.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;cli/commands/retrospect.py&lt;/code&gt;)
turned out, on inspection, to walk &lt;code dir=&quot;auto&quot;&gt;.kittify/missions/&lt;/code&gt; — a &lt;strong&gt;different&lt;/strong&gt;
scan root — and are correctly &lt;em&gt;not&lt;/em&gt; in the allowlist; a scan-root-keyed gate
would never match them regardless.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;G-2 — token-keyed, not line-pinned.&lt;/strong&gt; The allowlist and the taint-detection
heuristic both key on module paths and identifier/name tokens (a curated
&lt;code dir=&quot;auto&quot;&gt;KITTY_SPECS_DIR&lt;/code&gt;-derived-variable check plus a small closed vocabulary of
established parameter names such as &lt;code dir=&quot;auto&quot;&gt;mission_specs_dir&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scan_root&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;wt_specs&lt;/code&gt;), never on line numbers — line numbers drift on every unrelated
edit and rot the gate silently (the Phase 1 ADR’s own maintenance warning).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;G-3 — scope derives from &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;.&lt;/strong&gt; The gate walks &lt;code dir=&quot;auto&quot;&gt;_SRC_ROOT.rglob(&quot;*.py&quot;)&lt;/code&gt;
wholesale; it does not hardcode a subdirectory allowlist that a new package
could fall outside of. A companion sanity test asserts the scan actually
reaches known walker files, proving the scope has not silently narrowed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Free-function-caller ceiling.&lt;/strong&gt; Because the dominant read path is the free
function &lt;code dir=&quot;auto&quot;&gt;resolve_mission&lt;/code&gt; (D-08), not only the assembler-injected port, the
gate separately counts bare-name &lt;code dir=&quot;auto&quot;&gt;resolve_mission(...)&lt;/code&gt; call sites across
&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; and asserts the count does not exceed the known ceiling (9, as of this
mission). A tenth caller must not appear silently; raising the ceiling is a
deliberate, reviewed edit to this test file, exactly like every other ratchet
constant in this codebase.&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 “one walk” invariant recorded in D-06/D-08 is now a CI failure, not a
reviewer-memory convention — a future “quick mission listing” reaching for
&lt;code dir=&quot;auto&quot;&gt;Path.iterdir()&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; fails the gate immediately, and a new
&lt;code dir=&quot;auto&quot;&gt;resolve_mission&lt;/code&gt; caller past the ceiling fails just as loudly.&lt;/li&gt;
&lt;li&gt;The anti-fold carve-outs (C-001/C-002/C-003) are preserved by construction:
they are allowlisted, not silently swept into the resolver, so
&lt;code dir=&quot;auto&quot;&gt;identity_audit&lt;/code&gt;’s “find the missions the resolver skips” and
&lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt;’s caller-supplied scan root keep their distinct semantics.&lt;/li&gt;
&lt;li&gt;The gate generalizes a pattern this codebase already trusts
(&lt;code dir=&quot;auto&quot;&gt;test_protection_resolver_call_sites.py&lt;/code&gt;, and the Phase 1 seam gate) rather
than inventing new machinery.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The taint-detection heuristic (KITTY_SPECS_DIR-derived variable names plus a
curated parameter-name vocabulary) is a static approximation, not full
dataflow analysis — it can in principle miss a walker that threads the specs
directory through an unconventional name with no local &lt;code dir=&quot;auto&quot;&gt;KITTY_SPECS_DIR&lt;/code&gt;
reference in the same file. This is the same class of limitation the Phase 1
gate accepted (bare-name-call matching over full call-graph resolution); the
mitigation is the same: the allowlist and the vocabulary are both
human-reviewed, deliberately-extended surfaces, not machine-inferred ones.&lt;/li&gt;
&lt;li&gt;The allowlist itself is maintenance surface: 19 legacy files (plus 2 migration
prefixes) must be revisited if &lt;code dir=&quot;auto&quot;&gt;#2173&lt;/code&gt;’s later phases fold any of them into
the trunk — each fold is a deliberate allowlist-shrink, mirroring NFR-002’s
shrink-only-ratchet discipline.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;This ADR does not itself perform any additional folding of the 19 allowlisted
legacy walkers into the resolver — that is out of scope for WP04 and left to
future #2173 phases (or explicit non-goals, for the three anti-fold sites).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;The decision is confirmed when: (1) the gate is green against the live
allowlist on introduction (no red-on-day-one migration debt); (2) a deliberately
planted raw &lt;code dir=&quot;auto&quot;&gt;iterdir()&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;glob()&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;scandir()&lt;/code&gt; enumeration of &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;
outside the allowlist fails the gate; (3) the free-function-caller ceiling
assertion fails if a &lt;strong&gt;10th&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;resolve_mission&lt;/code&gt; call site is added without a
corresponding, reviewed ceiling bump; and (4) the full
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; suite remains green, proving no regression against the
Phase 1 gate or any other structural ratchet.&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-1--rely-on-code-review-alone&quot;&gt;Option 1 — Rely on code review alone&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; zero new infrastructure.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; this is exactly the status quo the Phase 1 ADR already showed leaks
(#2164, #2160); nothing stops “walker #7” from reappearing the moment a reviewer
is looking elsewhere.&lt;/p&gt;
&lt;h3 id=&quot;option-2--fold-every-walker-into-the-resolver-unconditionally&quot;&gt;Option 2 — Fold every walker into the resolver unconditionally&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; conceptually simplest — “everything goes through one function.”&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; breaks the three anti-fold sites’ deliberately different contracts.
&lt;code dir=&quot;auto&quot;&gt;status/identity_audit.py&lt;/code&gt; exists specifically to find the missions the
resolver’s fail-closed contract would skip (&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;-less directories);
folding it in would make the audit blind to the exact defect class it audits
for. &lt;code dir=&quot;auto&quot;&gt;merge/ordering.py&lt;/code&gt; needs a caller-supplied, possibly non-primary scan
root under an active merge lock — the resolver’s &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt;-bound construction
doesn’t fit. &lt;code dir=&quot;auto&quot;&gt;core/paths.py&lt;/code&gt;’s helper is a best-effort, swallow-and-degrade
error-listing aid for CLI messages; the resolver’s fail-closed-loud contract
would turn a friendly hint into a hard crash in exactly the CLI-error-message
context where a crash is least welcome.&lt;/p&gt;
&lt;h3 id=&quot;option-3--ast-call-site-gate--token-keyed-allowlist-chosen&quot;&gt;Option 3 — AST call-site gate + token-keyed allowlist (CHOSEN)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; closes the class by construction; reuses a proven, shipped idiom;
allows explicit, reviewed carve-outs for the three anti-fold sites; scope
derives from &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; so it can’t silently go blind; token-keyed so it doesn’t rot
on unrelated line-number drift.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; the taint heuristic is a static approximation (see Negative
consequences above); the allowlist is maintenance surface.&lt;/p&gt;
&lt;h3 id=&quot;option-4--runtime-enforcement-monkeypatch-pathiterdirpathglob&quot;&gt;Option 4 — Runtime enforcement (monkeypatch &lt;code dir=&quot;auto&quot;&gt;Path.iterdir&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;Path.glob&lt;/code&gt;)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; would catch violations regardless of how cleverly a caller obscures
the raw call syntactically.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt; process-wide monkeypatching of &lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt; methods is invasive, has to be
active during every test run (not just an architectural-gate pass), cannot
distinguish “walking &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;” from “walking any other directory that
happens to share a &lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt; instance’s method” without also tracking &lt;em&gt;which path&lt;/em&gt;
was walked at runtime — effectively reimplementing the same
&lt;code dir=&quot;auto&quot;&gt;KITTY_SPECS_DIR&lt;/code&gt;-anchored check, but at runtime cost, in every test process,
instead of once in CI’s architectural pass. Static AST analysis is strictly
cheaper for a build-time invariant.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Predecessor: &lt;a href=&quot;/adr/3.x/2026-06-26-1-single-authority-seam-and-call-site-gate/&quot;&gt;2026-06-26-1 — Single-Authority Seam + Call-Site Gate for
Resolution Boundaries (Phase 1)&lt;/a&gt;
— this ADR is the “Phase 2 (deferred follow-on)” that ADR’s “More Information”
section named.&lt;/li&gt;
&lt;li&gt;Gate precedent copied: &lt;a href=&quot;../../../tests/architectural/test_protection_resolver_call_sites.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_protection_resolver_call_sites.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;New gate: &lt;a href=&quot;../../../tests/architectural/test_mission_resolver_walker_gate.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_mission_resolver_walker_gate.py&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Port contract: &lt;a href=&quot;../../../kitty-specs/mission-resolver-port-01KX1C05/contracts/mission-resolver.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/mission-resolver-port-01KX1C05/contracts/mission-resolver.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Cross-references: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2173&quot;&gt;#2173&lt;/a&gt;, &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1619&quot;&gt;#1619&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
