<?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-05-24-2-pack-augmentation-vocabulary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-24-2-pack-augmentation-vocabulary/</id>
  <title>ADR: Pack Augmentation Vocabulary — `overrides` and `enhances` as Declarative Fields</title>
  <updated>2026-05-24T00: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-05-24-2-pack-augmentation-vocabulary/"/>
  <summary>Adds mutually exclusive overrides and enhances fields to five doctrine artifact kinds, making full replacement versus field-level augmentation a declared intent.</summary>
  <content type="html">&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-1-charter-freshness-ux-contract/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-24-1-charter-freshness-ux-contract.md&lt;/code&gt;&lt;/a&gt; (sibling — surfaces &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; in the freshness banners and preflight checks)&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-3-shipped-to-built-in-cutover/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-24-3-shipped-to-built-in-cutover.md&lt;/code&gt;&lt;/a&gt; (sibling — renames the &lt;code dir=&quot;auto&quot;&gt;shipped&lt;/code&gt; layer this vocabulary augments)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;ADR &lt;code dir=&quot;auto&quot;&gt;2026-05-16-1&lt;/code&gt; ratified that the doctrine layer merge is &lt;strong&gt;field-level&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;{**shipped.model_dump(), **project_data}&lt;/code&gt;), not artifact-level full
replacement. Under that model, a pack-side artifact that shares an ID with a
built-in artifact silently augments the built-in by field merge — and the
runtime currently emits a generic same-ID-collision &lt;em&gt;advisory&lt;/em&gt; asking the pack
author to disambiguate.&lt;/p&gt;
&lt;p&gt;Two structural gaps remain:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Intent is not declarable.&lt;/strong&gt; A pack author cannot say “I mean to fully
replace this built-in” versus “I mean to add a few fields to it.” The
collision advisory therefore cannot tell intentional augmentation from an
accidental ID clash; it fires equally in both cases, producing churn for
intentional pack design.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt; blocks the most natural fix.&lt;/strong&gt; Every doctrine model
carries &lt;code dir=&quot;auto&quot;&gt;model_config = ConfigDict(frozen=True, extra=&quot;forbid&quot;, ...)&lt;/code&gt; so
pack YAMLs that declare an &lt;em&gt;unknown&lt;/em&gt; augmentation field (e.g. &lt;code dir=&quot;auto&quot;&gt;enhances: &amp;#x3C;id&gt;&lt;/code&gt;) get rejected at the Pydantic boundary before the loader ever sees
the relation.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Issue #1291 surfaced this when a pack author tried to encode “enhance
built-in &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;&lt;/code&gt;” as a free-form field and was rejected by &lt;code dir=&quot;auto&quot;&gt;extra_forbidden&lt;/code&gt;.
Wording the validator output as a collision &lt;em&gt;also&lt;/em&gt; did not reflect the
field-merge semantics that &lt;code dir=&quot;auto&quot;&gt;2026-05-16-1&lt;/code&gt; ratified — the runtime &lt;em&gt;does&lt;/em&gt;
combine these artifacts; it just lacked the vocabulary to call it that.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Add two &lt;strong&gt;first-class, optional declarative fields&lt;/strong&gt; to five doctrine artifact
kinds (&lt;code dir=&quot;auto&quot;&gt;Tactic&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Styleguide&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Paradigm&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Procedure&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;AgentProfile&lt;/code&gt;):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;overrides: &amp;#x3C;id&gt; | None&lt;/code&gt; — declares full replacement of the built-in
artifact with this ID.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;enhances: &amp;#x3C;id&gt; | None&lt;/code&gt; — declares augmentation of the built-in artifact
with this ID via field-merge (the existing &lt;code dir=&quot;auto&quot;&gt;2026-05-16-1&lt;/code&gt; semantics).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A cross-field validator (&lt;code dir=&quot;auto&quot;&gt;_augmentation_intent_is_exclusive&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;@model_validator(mode=&quot;after&quot;)&lt;/code&gt;)
on every artifact kind raises a structured &lt;code dir=&quot;auto&quot;&gt;ValidationError&lt;/code&gt; if both fields
are set on the same artifact; setting neither remains the default and
preserves backward compatibility.&lt;/p&gt;
&lt;p&gt;WP06 (a downstream WP in this mission) consumes these fields to auto-emit
&lt;code dir=&quot;auto&quot;&gt;OVERRIDES&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ENHANCES&lt;/code&gt; edges in the doctrine reference graph and to
&lt;strong&gt;suppress&lt;/strong&gt; the same-ID-collision advisory when either field is set —
because the pack author has declared intent.&lt;/p&gt;
&lt;h3 id=&quot;vocabulary-canon&quot;&gt;Vocabulary canon&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; (canonical) — synonyms-to-avoid: &lt;code dir=&quot;auto&quot;&gt;augments&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;extends&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; (canonical) — synonyms-to-avoid: &lt;code dir=&quot;auto&quot;&gt;replaces&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;supersedes&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Both terms are added to &lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/spec_kitty_core.yaml&lt;/code&gt; per
DIR-032 (project glossary as the source of truth for vocabulary).&lt;/p&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;alternative-a--drop-extraforbid-on-doctrine-models&quot;&gt;Alternative A — Drop &lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt; on doctrine models&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Rejected.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt; is the principal defense against typo’d field
names in pack YAMLs (e.g. &lt;code dir=&quot;auto&quot;&gt;enhanced_by:&lt;/code&gt; instead of &lt;code dir=&quot;auto&quot;&gt;enhances:&lt;/code&gt;). Loosening
it would degrade the validation surface for every pack author to fix a single
intent-declaration use case. The cost-benefit is wrong.&lt;/p&gt;
&lt;h3 id=&quot;alternative-b--magic-precedence-rules-no-declaration-needed&quot;&gt;Alternative B — Magic precedence rules (no declaration needed)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Rejected.&lt;/strong&gt; “Same ID + extra fields ⇒ enhances; same ID + same fields ⇒
overrides” is implicit, fragile, and hostile to review. Pack authors and
reviewers would need to memorize precedence rules instead of reading a
declarative statement at the top of the artifact. Implicit intent also makes
the DRG edge type (&lt;code dir=&quot;auto&quot;&gt;ENHANCES&lt;/code&gt; vs &lt;code dir=&quot;auto&quot;&gt;OVERRIDES&lt;/code&gt;) unstable across refactors.&lt;/p&gt;
&lt;h3 id=&quot;alternative-c--relation-enum-field-with-values-overridesenhances&quot;&gt;Alternative C — &lt;code dir=&quot;auto&quot;&gt;relation:&lt;/code&gt; enum field with values &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Rejected.&lt;/strong&gt; A single &lt;code dir=&quot;auto&quot;&gt;relation:&lt;/code&gt; field couples the &lt;em&gt;kind&lt;/em&gt; of relation to a
&lt;em&gt;target ID&lt;/em&gt; through positional convention, and a future relation type would
force breaking changes to the field shape. Two narrowly-typed optional
fields, each &lt;code dir=&quot;auto&quot;&gt;string | None&lt;/code&gt;, keep each relation independently evolvable and
make the mutually-exclusive validator trivially expressible.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Pack authors can declare augmentation intent in one line per artifact.&lt;/li&gt;
&lt;li&gt;The same-ID collision advisory (WP06) can suppress correctly on intentional
augmentation, eliminating churn.&lt;/li&gt;
&lt;li&gt;DRG edge emission (WP06) becomes deterministic from the artifact source —
no separate &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt; entry required for &lt;code dir=&quot;auto&quot;&gt;OVERRIDES&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ENHANCES&lt;/code&gt;
edges.&lt;/li&gt;
&lt;li&gt;The field-merge semantics ratified in &lt;code dir=&quot;auto&quot;&gt;2026-05-16-1&lt;/code&gt; are now &lt;em&gt;namable&lt;/em&gt; in
the doctrine vocabulary; reviewers and downstream tooling share one term.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative--cost&quot;&gt;Negative / cost&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Five symmetric model changes plus five matching schema YAML changes are
required; the cross-cutting fixture surface is large (NFR-004 forces a
zero-regression sweep across the full doctrine test suite).&lt;/li&gt;
&lt;li&gt;Pack-validator advisory wording (WP06) must be updated in lockstep — the
vocabulary canon is not useful if downstream messages still say
“augments”.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Both fields default to &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;; existing fixtures that omit them are
unaffected. The added schema properties are not &lt;code dir=&quot;auto&quot;&gt;required&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt; is preserved on all five models — only the known-field
set widens.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;forward-chain&quot;&gt;Forward chain&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;WP06&lt;/strong&gt; (this mission): adds &lt;code dir=&quot;auto&quot;&gt;Relation.OVERRIDES&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;Relation.ENHANCES&lt;/code&gt;
to the DRG enum, auto-emits edges from these fields in
&lt;code dir=&quot;auto&quot;&gt;org_pack_loader.py&lt;/code&gt;, and rewords the collision advisory to suppress when
either field is set.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WP07+&lt;/strong&gt; (future): pack-validator hard error path for
&lt;code dir=&quot;auto&quot;&gt;enhances: &amp;#x3C;unknown-id&gt;&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;overrides: &amp;#x3C;unknown-id&gt;&lt;/code&gt; (target must exist as
a built-in).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;compliance&quot;&gt;Compliance&lt;/h2&gt;
&lt;p&gt;This ADR is binding on every change that touches:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/{tactics,styleguides,paradigms,procedures,agent_profiles}/models*.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/schemas/*.schema.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/models.py&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;Relation&lt;/code&gt; enum, via WP06)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/spec_kitty_core.yaml&lt;/code&gt; entries for &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Any new doctrine artifact kind added in the future SHOULD inherit the same
two declarative fields and the same &lt;code dir=&quot;auto&quot;&gt;_augmentation_intent_is_exclusive&lt;/code&gt;
validator unless an explicit deviation is documented in a successor ADR.&lt;/p&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: a field-level merge (2026-05-16-1) or a declared &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; relation (2026-05-24-2) applies only where the owning pack’s level permits the
operation (spec-kitty-charter ADR-0012); otherwise the merge refuses with
&lt;code dir=&quot;auto&quot;&gt;governance_policy_violation&lt;/code&gt;.&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>
