<?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-5-local-daemon-amortizes-doctrine-parse-and-caches-gate-verdicts/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-13-5-local-daemon-amortizes-doctrine-parse-and-caches-gate-verdicts/</id>
  <title>ADR: A local loopback daemon amortizes doctrine parse and caches deterministic gate verdicts (direction)</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-5-local-daemon-amortizes-doctrine-parse-and-caches-gate-verdicts/"/>
  <summary>Direction-setting ADR: a local loopback daemon holds parsed doctrine and a content-hash-keyed verdict cache, making gate execution a warm API call rather than a cold subprocess.</summary>
  <content type="html">&lt;h2 id=&quot;a-local-loopback-daemon-amortizes-doctrine-parse-and-caches-deterministic-gate-verdicts&quot;&gt;A local loopback daemon amortizes doctrine parse and caches deterministic gate verdicts&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-13-5-local-daemon-amortizes-doctrine-parse-and-caches-gate-verdicts.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Proposed (direction-setting; not a prerequisite for the gate work)&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; Records a direction surfaced while designing declarative gates
(&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;).
Captured now so the gate design is daemon-ready, but scoped as a follow-on.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;post-dialectics-revision-2026-08-13--decision-held-open&quot;&gt;Post-dialectics revision (2026-08-13) — DECISION HELD OPEN&lt;/h2&gt;
&lt;p&gt;Per operator: &lt;strong&gt;this decision is held open for further discussion&lt;/strong&gt;; the rest of the gate
architecture proceeds without it. Recorded from the dialectics pass
(&lt;code dir=&quot;auto&quot;&gt;work/gate-design-dialectics/04-...&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;99-COHERENCE.md&lt;/code&gt;), not yet settled:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;The verdict cache keyed on pack content-hash is contested as unsound.&lt;/strong&gt; The pack hash omits
the &lt;strong&gt;working tree&lt;/strong&gt;, which is the dominant input of both the incumbent &lt;code dir=&quot;auto&quot;&gt;spec-kitty-pre-review&lt;/code&gt;
gate (scoped tests at head) and the &lt;code dir=&quot;auto&quot;&gt;docs-structural-lint&lt;/code&gt; example (lints the tree). Editing a
tracked file leaves the pack hash unchanged → a stale &lt;strong&gt;PASS&lt;/strong&gt; could cross a blocking gate.
Capturing “everything a subprocess reads” is not feasible without tracing infra that dwarfs the
daemon.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Parse-amortization is sound and daemon-independent&lt;/strong&gt; — the parse is a pure function of pack
bytes and can be a content-addressed on-disk cache with no daemon.&lt;/li&gt;
&lt;li&gt;No decision is folded here yet. The daemon-as-warm-API and the verdict-cache question remain
&lt;strong&gt;open&lt;/strong&gt; pending further discussion.&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;The CLI parses doctrine + DRG (and, with declarative gates, gate definitions) on &lt;strong&gt;every
invocation&lt;/strong&gt;. Adding gate execution compounds that per-invocation cost. But gates are
&lt;strong&gt;deterministic and side-effect-free&lt;/strong&gt;, which makes their verdicts &lt;strong&gt;cacheable&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;There is precedent for a resident local process: the dashboard daemon
(&lt;code dir=&quot;auto&quot;&gt;.kittify/.dashboard&lt;/code&gt;) and the &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; external surface already exist, and the
project’s loopback-only HTTP posture (127.0.0.1, no forced TLS) is the established security
model for such a surface.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Amortize doctrine/DRG/gate parse across invocations.&lt;/li&gt;
&lt;li&gt;Exploit gate determinism: identical inputs ⇒ identical verdict ⇒ cache hit.&lt;/li&gt;
&lt;li&gt;Do not couple the gate design to a daemon that does not exist yet.&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;Direction (not yet a committed build):&lt;/strong&gt; a &lt;strong&gt;local, loopback-only daemon&lt;/strong&gt; may host doctrine
resolution and gate execution behind an API. It holds:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Parsed doctrine / DRG&lt;/strong&gt;, loaded once and reused across calls.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A deterministic gate-verdict cache&lt;/strong&gt;, keyed on &lt;code dir=&quot;auto&quot;&gt;(gate id, gate/pack version, hash of the inputs the gate reads)&lt;/code&gt;. The &lt;strong&gt;pack &lt;code dir=&quot;auto&quot;&gt;pack-meta.yaml&lt;/code&gt; content-hash&lt;/strong&gt; is the natural
invalidation key — the same hash that is signed for trust (ADR 2026-08-13-4). Three
concerns converge on one hash: &lt;strong&gt;integrity (signature), identity (version), and cache-key&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Gate execution then becomes a warm API call; a cold CLI subprocess remains the fallback and
the v1 path. &lt;strong&gt;The gate design (ADRs -2/-3/-4) must stand on its own without the daemon&lt;/strong&gt; —
the daemon is an optimization, not a dependency.&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;Repeated transitions collapse to cache hits; parse cost is paid once.&lt;/li&gt;
&lt;li&gt;Reuses existing loopback-daemon precedent and security posture.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A daemon that executes shipped code is a &lt;strong&gt;persistent execution surface&lt;/strong&gt; with a real
lifecycle (start/stop/staleness) and security story — deserves its own ADR + threat model
before it is built.&lt;/li&gt;
&lt;li&gt;Cache correctness depends entirely on the input-hash being complete; a gate that reads an
un-hashed input would return a stale verdict.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Whether this extends the existing dashboard daemon or is a new process is unresolved.&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;Extend the dashboard daemon, or a separate gate/doctrine daemon?&lt;/li&gt;
&lt;li&gt;How is “the inputs the gate reads” captured completely enough to be a safe cache key?&lt;/li&gt;
&lt;li&gt;Is verdict caching even worth it before the daemon exists (cold CLI has no persistent cache)?&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
