<?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-16-1-doctrine-layer-merge-semantics/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/</id>
  <title>ADR: Doctrine Layer Merge Semantics — Field-Level Merge with Collision Warnings</title>
  <updated>2026-05-16T00: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-16-1-doctrine-layer-merge-semantics/"/>
  <summary>Doctrine layers combine by field-level overlay with explicit collision warnings, preserving partial project overrides instead of replacing whole artifacts.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;layered-doctrine-org-layer-01KRNPEE&lt;/code&gt; shipped with a documented contradiction
between specification and implementation that no per-WP reviewer flagged:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; FR-003&lt;/strong&gt; stated: &lt;em&gt;“the higher layer fully replaces the lower
layer’s artifact (full-replace semantics). Partial field merging is not
applied across layers.”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;&lt;/strong&gt; stated: &lt;em&gt;“Higher layer fully replaces lower layer on
artifact ID collision. No field-level merging across layers.”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;tasks/WP02-base-repository-org-layer.md&lt;/code&gt;&lt;/strong&gt; “Key invariant to preserve”
stated the OPPOSITE: &lt;em&gt;“The existing &lt;code dir=&quot;auto&quot;&gt;_merge()&lt;/code&gt; (field-level merge) is used
within the project override step for artifacts whose ID exists in shipped
(project fields override shipped fields). The same field-level merge is used
for org overrides of shipped.”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/base.py::_merge&lt;/code&gt;&lt;/strong&gt; ships the field-level merge:
&lt;code dir=&quot;auto&quot;&gt;{**shipped.model_dump(), **project_data}&lt;/code&gt; — a project override that omits
a field inherits the lower layer’s value for that field.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;WP02’s implementer correctly preserved the pre-2.x project-overlay behaviour
(field-merge has been in place since well before the org layer was added) and
followed WP02’s “Key invariant to preserve” note. The contradiction with
&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt; was not raised in any per-WP review and only
surfaced in post-merge mission review.&lt;/p&gt;
&lt;h3 id=&quot;whats-actually-at-stake&quot;&gt;What’s actually at stake&lt;/h3&gt;
&lt;p&gt;Two distinct user-facing semantics could legitimately be called “the higher
layer wins”:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Artifact-level full replace.&lt;/strong&gt; When a higher layer declares an artifact ID,
the lower layer’s artifact for that ID is discarded entirely; the higher
layer’s YAML must contain every field that downstream consumers need.
Overrides are self-contained.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Field-level replace (the actual behaviour).&lt;/strong&gt; When a higher layer declares
an artifact ID, fields present in the higher layer’s YAML replace the
same-named fields in the lower layer; fields absent from the higher layer
fall through to the lower layer’s value. Overrides may be partial.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Both share the same “no two artifacts with the same ID coexist across layers
in the resolved view” guarantee. They differ in what an override YAML must
contain and how surprising a partial override is.&lt;/p&gt;
&lt;h3 id=&quot;options&quot;&gt;Options&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;(A) Make code match literal spec.&lt;/strong&gt; Rewrite &lt;code dir=&quot;auto&quot;&gt;_merge&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;type(shipped).model_validate(project_data)&lt;/code&gt;. Project overlays in any
deployed project that uses partial overrides start failing pydantic
validation. The existing test &lt;code dir=&quot;auto&quot;&gt;test_org_overrides_shipped_field_merge&lt;/code&gt;
needs revision. Real, observable regression with no operator-facing
benefit beyond doctrinal purity.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(B) Make spec match code, no other change.&lt;/strong&gt; Reword FR-003 and
&lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt; to describe field-merge. Zero code change. Risk: operators
who override an artifact may not realise a higher-layer file silently
shadowed a lower-layer artifact — the merge is invisible until someone
reads the resulting &lt;code dir=&quot;auto&quot;&gt;provenance&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(C) Field-merge &lt;strong&gt;with explicit collision warnings&lt;/strong&gt;.&lt;/strong&gt; Same as (B) but
the loader emits a &lt;code dir=&quot;auto&quot;&gt;UserWarning&lt;/code&gt; whenever an override collision occurs,
so operators are explicitly notified that an org or project artifact
shadowed a builtin artifact (and which fields it replaced).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Adopt &lt;strong&gt;Option C: field-level merge with explicit collision warnings&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;Operators retain the convenience of partial overrides (which the project
overlay layer has supported throughout 2.x). Spec and code are reconciled.
The previously-invisible “top layer wins” semantics become surfaceable.&lt;/p&gt;
&lt;p&gt;The decision rests on five facts:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Pre-existing behaviour.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;_merge&lt;/code&gt; has performed field-level merge in
every spec-kitty release that supported a project doctrine overlay.
Changing it now would silently break any deployed project with partial
&lt;code dir=&quot;auto&quot;&gt;.kittify/doctrine/&lt;/code&gt; overrides, with no operator-facing benefit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;WP02 explicitly preserved this invariant.&lt;/strong&gt; The “Key invariant to
preserve” note in &lt;code dir=&quot;auto&quot;&gt;WP02-base-repository-org-layer.md&lt;/code&gt; ratified field-merge
for the new org layer. The contradiction is in the spec’s wording, not in
delivery intent.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Operator ergonomics.&lt;/strong&gt; Override files are short and focused on what
changes. Requiring full artifacts in every override file would inflate
YAML and make overrides harder to maintain.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The user’s mission-review feedback explicitly asked for collision
visibility, not behaviour change.&lt;/strong&gt; &lt;em&gt;“The user should be explicitly warned
about these collisions and the ‘top level will win’ behaviour.”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No information is destroyed.&lt;/strong&gt; Field-merge never drops fields the
operator did not explicitly target; the merge is non-destructive at the
field grain. The risk is solely about operator surprise, which collision
warnings address directly.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;specification-updates-required-normative&quot;&gt;Specification updates (required, normative)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; FR-003&lt;/strong&gt; is reworded:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;When the same artifact ID appears in multiple layers, the higher layer
takes ownership of the resolved artifact (its &lt;code dir=&quot;auto&quot;&gt;provenance&lt;/code&gt; becomes that
layer). Field-level merge applies: fields present in the higher layer’s
YAML replace the same-named fields in the lower layer; fields absent
from the higher layer fall through to the lower layer’s value. No two
artifacts with the same ID coexist across layers — the higher layer’s
identity wins. The resolver emits an operator-visible collision warning
each time a higher layer shadows a lower-layer artifact, with the
artifact ID, the source and target layers, and the count of replaced
fields.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;&lt;/strong&gt; “Merge precedence” paragraph is reworded to align.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;code-changes-required-normative&quot;&gt;Code changes (required, normative)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;BaseDoctrineRepository._apply_org_overrides&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;_apply_project_overrides&lt;/code&gt; emit a &lt;code dir=&quot;auto&quot;&gt;UserWarning&lt;/code&gt; of the shape:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Doctrine override: &amp;#x3C;artifact_id&gt; from &amp;#x3C;higher_layer&gt; shadowed&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;&amp;#x3C;lower_layer&gt; (&amp;#x3C;N&gt; field(s) replaced; &amp;#x3C;M&gt; field(s) inherited).&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The warning is emitted exactly once per collision, at load time, with
&lt;code dir=&quot;auto&quot;&gt;stacklevel=3&lt;/code&gt; so the warning surfaces in the caller’s frame.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;AgentProfileRepository._load_org_profiles_from_dir&lt;/code&gt; and the analogous
project-merge path in the same module emit the equivalent warning for
profile collisions.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;The warnings are categorised under a new
&lt;code dir=&quot;auto&quot;&gt;doctrine.base.DoctrineLayerCollisionWarning&lt;/code&gt; subclass of &lt;code dir=&quot;auto&quot;&gt;UserWarning&lt;/code&gt;
so operators can filter them via standard &lt;code dir=&quot;auto&quot;&gt;warnings&lt;/code&gt; machinery if
they intentionally maintain heavy overrides.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;cli-layer-surfacing-operator-ux&quot;&gt;CLI-layer surfacing (operator UX)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor doctrine&lt;/code&gt; adds a “Collisions” section that lists every
override collision detected at load time, grouped by pack, so operators
can audit their override footprint without parsing log noise. (No new
command; extension of the existing WP07 command.)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;migration-story&quot;&gt;Migration story&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;Zero migration burden for operators: existing overlays continue to work
unchanged. The only new artifact in operator experience is the warning
stream and the doctor section.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Existing tests for project-overlay field-merge behaviour (e.g.,
&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_base_org_layer.py::test_org_overrides_shipped_field_merge&lt;/code&gt;)
remain valid. New tests are added for warning emission.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Per-artifact opt-in &lt;code dir=&quot;auto&quot;&gt;_layering: full-replace&lt;/code&gt; strategy.&lt;/strong&gt; Adds
per-artifact API surface, documentation burden, and more code paths for
a use case nobody has requested. Rejected on YAGNI grounds; can be
added later if operator demand emerges.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Strict &lt;code dir=&quot;auto&quot;&gt;--strict-overrides&lt;/code&gt; CLI flag that promotes warnings to
errors.&lt;/strong&gt; Tempting for CI lint purposes, but cleanly orthogonal to
the warning emission itself. Captured as a follow-up consideration,
not part of this ADR.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;verification&quot;&gt;Verification&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Reword FR-003 in &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Reword the merge precedence paragraph in &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Implement the &lt;code dir=&quot;auto&quot;&gt;DoctrineLayerCollisionWarning&lt;/code&gt; emission in &lt;code dir=&quot;auto&quot;&gt;base.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;agent_profiles/repository.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Add unit tests asserting the warning is emitted for org-over-shipped,
project-over-shipped, and project-over-org collisions, with the
expected field-count payload.&lt;/li&gt;
&lt;li&gt;Extend &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor doctrine&lt;/code&gt; to surface collision counts.&lt;/li&gt;
&lt;li&gt;Update &lt;code dir=&quot;auto&quot;&gt;docs/explanation/org-doctrine-layer.md&lt;/code&gt; (the WP08 explanation
doc) with a section on collision semantics + warnings.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;All verification is local to the doctrine package and its tests; no cross-repo
or downstream-mission impact.&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>
