<?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-05-3-org-packs-ship-their-builtin-override-sanction/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-05-3-org-packs-ship-their-builtin-override-sanction/</id>
  <title>ADR: org packs ship their own built-in override sanction</title>
  <updated>2026-10-19T00: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-05-3-org-packs-ship-their-builtin-override-sanction/"/>
  <summary>An org pack lists the built-ins it replaces in a pack-root replaceable-builtins.yaml; doctor doctrine honours it for that pack only, and the consumer can revoke it.</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-05&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (repository owner).&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/5767&quot;&gt;#5767&lt;/a&gt;, Mission &lt;code dir=&quot;auto&quot;&gt;pack-shipped-builtin-override-sanction-01M45WB7&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor doctrine&lt;/code&gt;, org-pack validation or assembly, or the work for &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2216&quot;&gt;#2216&lt;/a&gt; and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2594&quot;&gt;#2594&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;The three-layer DRG merge lets an org node replace a built-in node of the same kind in place. Whether a given repository accepts that replacement is a governance decision, made by &lt;code dir=&quot;auto&quot;&gt;charter.offering.drg.override_policy&lt;/code&gt; from one file in the consumer repository, &lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/replaceable-builtins.yaml&lt;/code&gt; (see &lt;a href=&quot;/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/&quot;&gt;the doctrine layer merge ADR&lt;/a&gt; and Mission &lt;code dir=&quot;auto&quot;&gt;doctrine-governance-fidelity-01KW42KY&lt;/code&gt;, where the check is fail-closed, NFR-004). An override that the file does not list makes &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor doctrine&lt;/code&gt; exit 1.&lt;/p&gt;
&lt;p&gt;The sanction lived only in the consumer repository. An org pack that wanted to replace built-ins could ship a template at &lt;code dir=&quot;auto&quot;&gt;templates/setup/replaceable-builtins.yaml&lt;/code&gt;, and the consumer was expected to copy it. Nothing read that template. The copy drifted: when upstream promoted an org-authored artifact into the built-in set, the pack’s same-id artifact became an override of a built-in. Every consumer whose copied file predated the promotion then failed &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; with exit 1, although the consumer had changed nothing (&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5767&quot;&gt;#5767&lt;/a&gt;).&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;An org pack ships its sanction in a &lt;code dir=&quot;auto&quot;&gt;replaceable-builtins.yaml&lt;/code&gt; at its &lt;strong&gt;pack root&lt;/strong&gt;: the resolved root of the pack, including any configured &lt;code dir=&quot;auto&quot;&gt;subdir&lt;/code&gt;. The file uses the same entry grammar as the consumer file, &lt;code dir=&quot;auto&quot;&gt;replaceable_builtins: [{urn, reason}]&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; reads it in place; nothing is copied into the consumer repository.&lt;/p&gt;
&lt;p&gt;All sanction semantics (parse, scope, union, revoke, decision table) live in &lt;code dir=&quot;auto&quot;&gt;charter.offering.drg.override_policy&lt;/code&gt;. One loader, &lt;code dir=&quot;auto&quot;&gt;load_effective_override_policy&lt;/code&gt;, combines the consumer file, every pack’s file and the revocations, and feeds both &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; and the built-in-override architectural gate, so the two cannot adjudicate differently. The verdict predicates stay free of I/O.&lt;/p&gt;
&lt;p&gt;Rules:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Scoped to the contributing pack.&lt;/strong&gt; A pack entry sanctions an override only when the surviving node was contributed by that same pack. The pack is identified by the registry name in the consumer’s configuration, taken from the loaded fragments, never by a name the pack declares. Pack B cannot sanction pack A’s override.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unioned with the consumer file, which is checked first.&lt;/strong&gt; A valid consumer entry sanctions the override and is reported as the source.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A directive needs a reason.&lt;/strong&gt; A built-in directive override is sanctioned only by an entry with a non-empty reason, whichever source supplies it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Revocable.&lt;/strong&gt; The consumer file gains an optional &lt;code dir=&quot;auto&quot;&gt;revoked_pack_sanctions&lt;/code&gt; list whose entries are &lt;code dir=&quot;auto&quot;&gt;{urn}&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;{pack}&lt;/code&gt;, each with an optional reason. A revocation withdraws only what packs delivered; an entry in the consumer’s own &lt;code dir=&quot;auto&quot;&gt;replaceable_builtins&lt;/code&gt; still sanctions.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail closed and isolated.&lt;/strong&gt; An override that nobody sanctions still exits 1. A pack file that is malformed, unreadable, not a regular file, or resolves outside the pack root voids only that pack’s sanctions and makes the report unhealthy with an error naming the pack and the file. Every loaded pack’s file is checked, whether or not the pack overrides anything. A &lt;code dir=&quot;auto&quot;&gt;revoked_pack_sanctions&lt;/code&gt; key in a pack file is an error, because that key is consumer-only.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Visible.&lt;/strong&gt; The report lists every sanctioned override with its source and reason, on green runs too.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;decision-table&quot;&gt;Decision table&lt;/h3&gt;
&lt;p&gt;For one surviving org override of built-in &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt;, contributed by pack &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt;. “Valid” means the entry lists &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt; and, for a directive, carries a non-empty reason.&lt;/p&gt;






















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Consumer allowlist&lt;/th&gt;&lt;th&gt;Pack &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt; sanction&lt;/th&gt;&lt;th&gt;Consumer revokes &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt;&lt;/th&gt;&lt;th&gt;Verdict&lt;/th&gt;&lt;th&gt;Reported source or finding&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;valid&lt;/td&gt;&lt;td&gt;any&lt;/td&gt;&lt;td&gt;any&lt;/td&gt;&lt;td&gt;sanctioned&lt;/td&gt;&lt;td&gt;consumer&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;absent or invalid&lt;/td&gt;&lt;td&gt;valid&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;sanctioned&lt;/td&gt;&lt;td&gt;pack &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;absent or invalid&lt;/td&gt;&lt;td&gt;valid&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;unsanctioned&lt;/td&gt;&lt;td&gt;pack sanction revoked by the consumer &lt;code dir=&quot;auto&quot;&gt;replaceable-builtins.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;absent&lt;/td&gt;&lt;td&gt;absent&lt;/td&gt;&lt;td&gt;not applicable&lt;/td&gt;&lt;td&gt;unsanctioned&lt;/td&gt;&lt;td&gt;not on the consumer file or pack &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;replaceable-builtins.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;absent or not listing &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt;&lt;/td&gt;&lt;td&gt;lists &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt;, directive, empty reason&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;unsanctioned&lt;/td&gt;&lt;td&gt;directive override requires a non-empty reason (pack &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;lists &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt;, directive, empty reason&lt;/td&gt;&lt;td&gt;absent or invalid&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;unsanctioned&lt;/td&gt;&lt;td&gt;directive override requires a non-empty reason&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A revocation is reported in preference to a reason finding when the pack would otherwise have sanctioned &lt;code dir=&quot;auto&quot;&gt;U&lt;/code&gt;. Revoking a URN the pack never sanctioned changes nothing, and a revocation that names another pack does not affect &lt;code dir=&quot;auto&quot;&gt;P&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;report-shape&quot;&gt;Report shape&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;doctor doctrine --json&lt;/code&gt; gains three additive keys under &lt;code dir=&quot;auto&quot;&gt;profile_health.org_drg&lt;/code&gt;, each present only when non-empty: &lt;code dir=&quot;auto&quot;&gt;sanctioned_overrides&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;urn&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pack&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;source&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reason&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;pack_sanction_errors&lt;/code&gt;, and, on each &lt;code dir=&quot;auto&quot;&gt;unsanctioned_overrides&lt;/code&gt; entry, an optional &lt;code dir=&quot;auto&quot;&gt;legacy_template&lt;/code&gt;. Every sanction error is also appended to &lt;code dir=&quot;auto&quot;&gt;errors&lt;/code&gt;, which drives exit 1. The frozen top-level &lt;code dir=&quot;auto&quot;&gt;profile_health&lt;/code&gt; key set is unchanged. With no org packs configured the output is byte-identical to before.&lt;/p&gt;
&lt;p&gt;Two checks are new and deliberate. A malformed consumer allowlist is now reported as an error that names the file, and is treated as empty. A &lt;code dir=&quot;auto&quot;&gt;revoked_pack_sanctions&lt;/code&gt; entry that names a pack that is not configured (exact, case-sensitive match) is an error, so a typo can never leave a sanction in force that the operator believes revoked. Both make &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; unhealthy even when no org override exists.&lt;/p&gt;
&lt;h3 id=&quot;authoring-tools&quot;&gt;Authoring tools&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctrine pack validate&lt;/code&gt; parses the pack-root file with the same parser. A malformed file, or a directive entry without a reason, is an error; an entry the pack does not override is an advisory (category &lt;code dir=&quot;auto&quot;&gt;pack_sanction&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctrine pack assemble&lt;/code&gt; writes the union of its inputs’ sanction files to the assembled pack root. Two inputs that give the same URN different reasons are a conflict (artifact type &lt;code dir=&quot;auto&quot;&gt;replaceable_builtins&lt;/code&gt;); &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; keeps the last pack’s reason.&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;Read the pack’s file in place (chosen).&lt;/strong&gt; No copy exists, so nothing drifts, and scoping per pack is possible because provenance is &lt;code dir=&quot;auto&quot;&gt;org:&amp;#x3C;registry name&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fetch installs the file into the consumer repository.&lt;/strong&gt; Rejected. The copy drifts on the next promotion, scoping is lost, &lt;code dir=&quot;auto&quot;&gt;doctrine fetch&lt;/code&gt; would mutate consumer governance, it never runs for local-path packs, and it has no lifecycle.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A per-node &lt;code dir=&quot;auto&quot;&gt;replaces:&lt;/code&gt; marker.&lt;/strong&gt; Rejected. The marker is absent at the moment of promotion, and it would widen a strict node schema.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A key in &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt;.&lt;/strong&gt; Rejected. &lt;code dir=&quot;auto&quot;&gt;OrgCharterPolicy&lt;/code&gt; refuses unknown keys, so a new key would break every CLI already shipped, pack assembly rebuilds &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; from four keys only, and the sanction logic must live in &lt;code dir=&quot;auto&quot;&gt;charter.offering&lt;/code&gt;, which cannot import that model.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A pack author moves the sanction to the pack root once. A consumer who refreshes the pack stays green across later built-in promotions, with no edit in the consumer repository.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Legacy template hint (transitional).&lt;/strong&gt; A template at &lt;code dir=&quot;auto&quot;&gt;templates/setup/replaceable-builtins.yaml&lt;/code&gt; is never a sanction. For an unsanctioned override whose own pack lists the URN there, &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; still exits 1 and prints the pack-author move and the exact &lt;code dir=&quot;auto&quot;&gt;{urn, reason}&lt;/code&gt; entry to append to the consumer file. The one exception is a directive whose template entry has no reason: the hint then says a reason is required instead of printing an entry. It never prints a whole-file copy command, because a copy would overwrite consumer entries and revocations, bypass scoping and drift again. A malformed template yields no hint and no error. The probe is removed with #2594.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;API sources.&lt;/strong&gt; A pack fetched through an API source does not carry pack-root files, so it delivers no sanction and the consumer file still governs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Integrity.&lt;/strong&gt; The sanction file has the integrity of the pack’s other files. Git and https fetches hash the whole tree at fetch time; local-path packs carry no integrity check. It is not recorded in the pack-manifest constituents, whose model refuses entries that are not artifact kinds, and &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; does not verify it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bounded I/O.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; reads at most one sanction file per configured pack, plus at most one legacy template per unsanctioned override.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Compatibility.&lt;/strong&gt; A CLI that predates this change ignores both the pack-root file and the &lt;code dir=&quot;auto&quot;&gt;revoked_pack_sanctions&lt;/code&gt; key, with no new errors or warnings.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unchanged.&lt;/strong&gt; DRG merge behavior, and the intentional exemption of project-tier overrides (&lt;code dir=&quot;auto&quot;&gt;doctrine-governance-fidelity-01KW42KY&lt;/code&gt;, FR-012). When several packs override one built-in, the last pack’s node survives and only that node is adjudicated, against its own pack’s sanction.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;absorption-by-2594&quot;&gt;Absorption by #2594&lt;/h3&gt;
&lt;p&gt;Delegated governance in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2594&quot;&gt;#2594&lt;/a&gt; can absorb this design without new concepts. The pack sanction becomes the pack’s declared overlay intent, and the revocation becomes consumer narrowing of a delegated sanction, the consumer-side counterpart of &lt;code dir=&quot;auto&quot;&gt;governed&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;locked&lt;/code&gt;. The entry grammar &lt;code dir=&quot;auto&quot;&gt;{urn, reason}&lt;/code&gt; is the only governance concept introduced here.&lt;/p&gt;
&lt;h3 id=&quot;follow-ups-not-in-scope&quot;&gt;Follow-ups, not in scope&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Make &lt;code dir=&quot;auto&quot;&gt;OrgCharterPolicy&lt;/code&gt; tolerant of unknown keys when the schema version is newer, as groundwork for #2594.&lt;/li&gt;
&lt;li&gt;Edges that a losing org pack contributes at a built-in URN, and edge-form &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; relations that target a built-in, are not adjudicated. Tracked in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5769&quot;&gt;#5769&lt;/a&gt; and &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5770&quot;&gt;#5770&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Updating the external org packs to move their template to the pack root is outside this repository.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-19-owner-declared-mutability-levels-spec-kitty-charter-adr-0012&quot;&gt;Amendment 2026-10-19: owner-declared mutability levels (spec-kitty-charter ADR-0012)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator), 2026-10-19. Requested by &lt;code dir=&quot;auto&quot;&gt;spec-kitty-charter&lt;/code&gt;
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-charter/blob/main/docs/adr/0012-pack-mutability-policy.md&quot;&gt;ADR-0012&lt;/a&gt; (the owning pack declares a mutability level per artifact: &lt;code dir=&quot;auto&quot;&gt;open&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;extendable&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;locked&lt;/code&gt;), recorded in &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-charter/pull/88&quot;&gt;spec-kitty-charter#88&lt;/a&gt;.
The record above is unchanged; this note bounds it.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Amendment 2026-10-19: superseded for the decision of whether an override is permitted by
spec-kitty-charter ADR-0012. The owning pack’s mutability level decides;
&lt;code dir=&quot;auto&quot;&gt;replaceable-builtins.yaml&lt;/code&gt; is read for one release as a deprecated input and then ignored.
The built-in pack ships a policy file whose kind defaults are &lt;code dir=&quot;auto&quot;&gt;extendable&lt;/code&gt; and which lists
as &lt;code dir=&quot;auto&quot;&gt;open&lt;/code&gt; every URN sanctioned today.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Migration, confirmed by the operator on 2026-10-19:&lt;/strong&gt; the built-in pack ships its own policy
file whose kind defaults are &lt;code dir=&quot;auto&quot;&gt;extendable&lt;/code&gt;, and every URN that a released
&lt;code dir=&quot;auto&quot;&gt;replaceable-builtins.yaml&lt;/code&gt; sanctions today is listed in it as &lt;code dir=&quot;auto&quot;&gt;open&lt;/code&gt;. Until the policy
enforcement lands (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-charter&lt;/code&gt; #58, after the org-precedence defect
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-charter&lt;/code&gt; #87 is fixed), current behavior is unchanged.&lt;/p&gt;</content>
</entry>
