<?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-4-executable-doctrine-runs-only-from-trusted-publishers/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-13-4-executable-doctrine-runs-only-from-trusted-publishers/</id>
  <title>ADR: Executable doctrine runs only from trusted publishers (built-in trusted by position; TOFU for the rest)</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-4-executable-doctrine-runs-only-from-trusted-publishers/"/>
  <summary>Gate assets run only from trusted packs: built-in by install position; others via a user-home TOFU store keyed on a local executable-surface hash. Untrusted is BLOCKING.</summary>
  <content type="html">&lt;h2 id=&quot;executable-doctrine-runs-only-from-trusted-publishers&quot;&gt;Executable doctrine runs only from trusted publishers&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-13-4-executable-doctrine-runs-only-from-trusted-publishers.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-09-27, amended in place)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-13 (proposed) · 2026-09-27 (amended and accepted)&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; &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;
makes gates run shipped code. Org and project packs can ship gates too — arbitrary code
executing on every Mission transition. That is a supply-chain surface and needs a trust model.
Implementation tracks the #2539 epic and the #2540 enabler; signing is deferred to #2543/#2544.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;amendment-note-2026-09-27&quot;&gt;Amendment note (2026-09-27)&lt;/h2&gt;
&lt;p&gt;Accepted together with &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;
and &lt;a href=&quot;/adr/3.x/2026-08-13-6-gate-outcomes-carry-severity-operator-strategy-decides-effect/&quot;&gt;ADR 2026-08-13-6&lt;/a&gt;
as one set, after the pack-trust ADR review (architect-alphonso / paula-patterns squad,
operator-approved 2026-09-27). The body is &lt;strong&gt;rewritten in place&lt;/strong&gt;. Changes against the Proposed
text:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;“Skip + warn, transition proceeds” is gone. Untrusted, hash-mismatch and tamper outcomes are
&lt;strong&gt;BLOCKING&lt;/strong&gt; could-not-run outcomes (fixed by the dispatcher, ADR -6).&lt;/li&gt;
&lt;li&gt;Trust is no longer keyed on &lt;code dir=&quot;auto&quot;&gt;pack-meta.yaml&lt;/code&gt;, which does not exist: packs carry &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; (&lt;a href=&quot;/adr/3.x/2026-08-16-1-pack-metadata-manifest-unification/&quot;&gt;ADR 2026-08-16-1&lt;/a&gt;).
Trust keys on the operator-config coordinate plus a &lt;strong&gt;locally computed&lt;/strong&gt; hash of the
executable surface.&lt;/li&gt;
&lt;li&gt;The consent store lives in the &lt;strong&gt;user home&lt;/strong&gt;. Repo-committed files may only &lt;strong&gt;pin&lt;/strong&gt; an expected
hash; they can never grant consent.&lt;/li&gt;
&lt;li&gt;Added: what the hash covers, re-hash at dispatch time (TOCTOU), the first-fetch disclosure,
the update / re-pin flow, the CI seed, and positional built-in trust.&lt;/li&gt;
&lt;li&gt;Release signing for built-in is &lt;strong&gt;deferred&lt;/strong&gt; (#2543/#2544); it stays the to-be design for
fetched packs.&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;Declarative gates execute code shipped inside a doctrine pack. Built-in gates are first-party.
But the pack ecosystem (org packs, project packs) means a downstream pack could ship a gate
whose asset runs on every transition — an unreviewed code-execution surface.&lt;/p&gt;
&lt;p&gt;What exists today: no trust store, no TOFU and no signing anywhere in &lt;code dir=&quot;auto&quot;&gt;src/charter&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli&lt;/code&gt;. Org-pack config carries &lt;code dir=&quot;auto&quot;&gt;url&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ref&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;source_type&lt;/code&gt; only, with no expected
hash (&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/org_pack_config.py&lt;/code&gt;), and the git source checks out whatever
&lt;code dir=&quot;auto&quot;&gt;ref&lt;/code&gt; names without pinning a commit (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/doctrine/sources/git_source.py&lt;/code&gt;). Hash
machinery does exist, but only for cache reuse: the snapshot digest
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/doctrine/snapshot.py&lt;/code&gt;) is self-written at fetch time, and the pack manifest’s
per-constituent &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;manifest_hash&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/doctrine/pack_manifest.py&lt;/code&gt;,
LF-normalized in &lt;code dir=&quot;auto&quot;&gt;builtin_manifest.py&lt;/code&gt;) are authored by whoever built the pack. None of these is
a trust pin, but the LF-normalized hashing is the reusable basis for one.&lt;/p&gt;
&lt;p&gt;Inert doctrine (directives, tactics, styleguides) is text and is never executed — so a trust
decision is only ever needed for &lt;strong&gt;executing shipped code&lt;/strong&gt; (gate assets). The scope is narrow
by construction.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Never execute unreviewed third-party code silently.&lt;/li&gt;
&lt;li&gt;Never hang a Mission on a trust decision — gates fire in CI and (later) under a daemon, where
no operator is present to prompt. A missing decision must fail &lt;strong&gt;loudly&lt;/strong&gt;, not silently pass.&lt;/li&gt;
&lt;li&gt;The operator, not the pack author, is the authority: identity comes from the operator’s
config, and hashes are computed locally, never read from pack-authored metadata.&lt;/li&gt;
&lt;li&gt;A pull request must not be able to add a pack and approve it in the same change.&lt;/li&gt;
&lt;li&gt;Cosmetic edits to inert doctrine must not re-prompt.&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 — Trust everything&lt;/strong&gt; (execute any pack’s gate). Rejected: supply-chain hole.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B — Trust nothing but built-in&lt;/strong&gt; (never run org/project gates). Rejected: kills the ecosystem value.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C — Trust-on-first-use (TOFU), SSH-&lt;code dir=&quot;auto&quot;&gt;known_hosts&lt;/code&gt; style&lt;/strong&gt;, keyed on the operator-config
coordinate plus an observed content hash.&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: “C”.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;tiers&quot;&gt;Tiers&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Built-in is trusted by position.&lt;/strong&gt; A pack loaded from the installed wheel’s &lt;code dir=&quot;auto&quot;&gt;packs/built-in&lt;/code&gt;
root is trusted. “Built-in” means &lt;em&gt;where it was loaded from&lt;/em&gt;, never a pack that merely names
itself built-in. Only &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; ships in the wheel (ADR 2026-08-16-3).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Everything else is TOFU&lt;/strong&gt;: org packs (including &lt;code dir=&quot;auto&quot;&gt;packs/internal&lt;/code&gt;, which is consumed through
the org tier via &lt;code dir=&quot;auto&quot;&gt;local_path&lt;/code&gt; — ADR 2026-08-16-3) and project packs. This also covers a
freshly cloned hostile repository: its gates stay inert until the operator trusts them, the
same way git hooks are not run on clone.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;trust-key-and-what-is-hashed&quot;&gt;Trust key and what is hashed&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A trust entry is keyed on the &lt;strong&gt;operator-config coordinate&lt;/strong&gt; of the pack (the source as the
operator’s config names it: URL or &lt;code dir=&quot;auto&quot;&gt;local_path&lt;/code&gt;, plus &lt;code dir=&quot;auto&quot;&gt;ref&lt;/code&gt;) and the &lt;strong&gt;observed hash&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;The hash is &lt;strong&gt;recomputed locally&lt;/strong&gt; over the pack’s &lt;strong&gt;executable surface only&lt;/strong&gt;: every gate
constituent, every asset a gate references, and each gate’s &lt;code dir=&quot;auto&quot;&gt;interpreter&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;args&lt;/code&gt;. It uses
the existing LF-normalized hashing (&lt;code dir=&quot;auto&quot;&gt;hash_content_bytes&lt;/code&gt; over &lt;code dir=&quot;auto&quot;&gt;builtin_manifest&lt;/code&gt;’s
LF-normalized bytes). The pack’s own &lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;manifest_hash&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt;
values are &lt;strong&gt;never&lt;/strong&gt; read as the trust hash, because the pack author controls them.&lt;/li&gt;
&lt;li&gt;Hashing only the executable surface means a typo fix in an inert directive does not re-prompt.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;where-consent-and-pins-live&quot;&gt;Where consent and pins live&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Consent lives in the user home&lt;/strong&gt;, in a &lt;code dir=&quot;auto&quot;&gt;known_hosts&lt;/code&gt;-style trust store under the spec-kitty
home directory. Only the operator writes it, and only through the trust prompt or an explicit
trust command.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Repo-committed files may only pin.&lt;/strong&gt; A committed file (for example an org-pack entry in
&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;) may declare an &lt;em&gt;expected&lt;/em&gt; hash, with lockfile semantics: it is reviewed
like code, and a mismatch between the pin and the locally computed hash is a tamper outcome.
A pin &lt;strong&gt;never records consent&lt;/strong&gt;; a pinned but unconsented pack is still untrusted.&lt;/li&gt;
&lt;li&gt;Repo-committed configuration also cannot demote trust outcomes below BLOCKING (ADR -6).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;when-trust-is-checked&quot;&gt;When trust is checked&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Prompt at activation / install time, never mid-transition.&lt;/strong&gt; At run time the decision is
looked up non-interactively.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Re-hash at dispatch time.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;local_path&lt;/code&gt; pack is a mutable directory, so the executable
surface is re-hashed at dispatch, not only at activation. A mismatch against the consented or
pinned hash is a &lt;strong&gt;tamper&lt;/strong&gt; outcome.&lt;/li&gt;
&lt;li&gt;The trust check completes before any asset is resolved or executed (ADR -2 ordering invariant).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;first-fetch-and-updates&quot;&gt;First fetch and updates&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;First-fetch disclosure.&lt;/strong&gt; TOFU trusts whatever the first fetch returned, so the activation
prompt shows the source URL, the &lt;strong&gt;resolved commit SHA&lt;/strong&gt;, the executable-surface hash, and the
list of executable assets (the #2536 warning). A pack that ships executables from a git &lt;code dir=&quot;auto&quot;&gt;ref&lt;/code&gt;
that is a branch (not a tag or commit SHA) gets a warning interactively and is refused in CI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Updates re-prompt.&lt;/strong&gt; A hash change is handled like a changed &lt;code dir=&quot;auto&quot;&gt;known_hosts&lt;/code&gt; key: never
accepted silently. An explicit &lt;code dir=&quot;auto&quot;&gt;trust accept-update&lt;/code&gt; step shows which executable files
changed and records the new hash on consent.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Non-interactive mode never prompts.&lt;/strong&gt; An unknown or changed hash in CI or under a daemon is
a BLOCKING could-not-run outcome. CI seeds trust from a CI-side configuration or environment
source that lives &lt;strong&gt;outside the pull-request diff&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;outcomes&quot;&gt;Outcomes&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Untrusted, hash mismatch against a pin or consent, and tamper detected at dispatch are
&lt;strong&gt;BLOCKING&lt;/strong&gt; could-not-run outcomes, fixed by the dispatcher (ADR -6). There is no
“skip and proceed” path for trust failures.&lt;/li&gt;
&lt;li&gt;Trust is not containment: a trusted pack’s gate still runs under the ADR -2 refuse-unconfinable
baseline.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;signing-deferred&quot;&gt;Signing (deferred)&lt;/h3&gt;
&lt;p&gt;Release signing remains the &lt;strong&gt;to-be design&lt;/strong&gt;, recorded here and deferred to #2543/#2544. Built-in
ships in the same wheel as its verifier and any bundled key, so signing built-in adds nothing
near-term; positional trust already covers it. Signing’s value is a provenance chain for
&lt;em&gt;fetched&lt;/em&gt; packs, and that is where #2543/#2544 will pick it up.&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;Third-party code never runs unreviewed; the operator’s trust decision is explicit, persisted
outside the repository, and cannot be forged by a pull request.&lt;/li&gt;
&lt;li&gt;Tampering with a mutable &lt;code dir=&quot;auto&quot;&gt;local_path&lt;/code&gt; pack between activation and dispatch is caught.&lt;/li&gt;
&lt;li&gt;CI never hangs on trust and never silently skips a gate: a missing seed blocks loudly.&lt;/li&gt;
&lt;li&gt;Inert doctrine edits never re-prompt.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A home-directory store is per operator and per machine; teams need the CI seed and
repository pins to get reproducible behaviour.&lt;/li&gt;
&lt;li&gt;Re-hashing the executable surface on every dispatch costs I/O on each gated transition.&lt;/li&gt;
&lt;li&gt;A strict CI refusal of branch refs forces pack consumers onto tags or SHAs.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Trust is orthogonal to gate correctness — a trusted gate can still be a bad check; an untrusted
gate can still be a good one that simply will not run.&lt;/li&gt;
&lt;li&gt;Built-in positional trust needs no new machinery beyond knowing the load root.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;resolved-and-open-questions&quot;&gt;Resolved and open questions&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;em&gt;Resolved:&lt;/em&gt; prompt at activation, never at first execution.&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Resolved (2026-09-27):&lt;/em&gt; untrusted is not a skip; trust failures are BLOCKING (ADR -6).&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Resolved:&lt;/em&gt; trust granularity is the operator-config coordinate plus the executable-surface hash.&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Deferred:&lt;/em&gt; signing format and key rotation (#2543/#2544).&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Open:&lt;/em&gt; the exact on-disk format of the home trust store and of repository pins
(settled in #2540).&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
