<?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-31-1-expected-artifacts-loader-relocation/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-31-1-expected-artifacts-loader-relocation/</id>
  <title>ADR: Relocate the expected-artifacts.yaml loader authority into charter, sibling error model</title>
  <updated>2026-08-31T00: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-31-1-expected-artifacts-loader-relocation/"/>
  <summary>The canonical expected-artifacts.yaml loader moves into charter/activation for one shared authority under C-001, keeping MalformedManifestError and ManifestSchemaError as siblings.</summary>
  <content type="html">&lt;span id=&quot;adr-relocate-the-expected-artifactsyaml-loader-authority-into-charter-sibling-error-model&quot;&gt;&lt;/span&gt;
&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-08-31&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Mission &lt;code dir=&quot;auto&quot;&gt;expected-artifacts-loader-unification-01M1C9VQ&lt;/code&gt;
(mission_id &lt;code dir=&quot;auto&quot;&gt;01M1C9VQZ28CFRW741WRADS6SZ&lt;/code&gt;); closes #3770 and #3412; epic #3410
(charter/doctrine silent-drop). Decision &lt;code dir=&quot;auto&quot;&gt;01M1CBARZBBWVGWBTWRMHPP661&lt;/code&gt;
(operator-selected relocate-into-charter strategy).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; #3770 (four drifted &lt;code dir=&quot;auto&quot;&gt;expected-artifacts.yaml&lt;/code&gt; loader
reimplementations), #3412 (a YAML-syntax-broken &lt;em&gt;org&lt;/em&gt; manifest silently
laundered into a green guard for custom mission families). Planning
contracts under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/expected-artifacts-loader-unification-01M1C9VQ/&lt;/code&gt;
— &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; (FR-001/FR-002/FR-003/FR-007/FR-008), &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; (D1-D9),
&lt;code dir=&quot;auto&quot;&gt;contracts/arch-gate.md&lt;/code&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;Four independent modules each re-implemented the same
&lt;code dir=&quot;auto&quot;&gt;expected-artifacts.yaml&lt;/code&gt; org-tier-then-built-in-tier precedence, the same
&lt;code dir=&quot;auto&quot;&gt;ExpectedArtifactManifest.model_validate(...)&lt;/code&gt; call, and the same
&lt;code dir=&quot;auto&quot;&gt;ValidationError&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; wrapping:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli/dossier/manifest.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;ManifestRegistry.load_manifest&lt;/code&gt;,
cached) — the historical canonical loader.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;runtime/resolver.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_load_expected_artifact_manifest&lt;/code&gt;) — an uncached
mirror.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;runtime/next/runtime_bridge_io.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_presence_filenames_for&lt;/code&gt;) — another
uncached mirror, projecting into &lt;code dir=&quot;auto&quot;&gt;frozenset[str]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter/activation/mission_type_profiles.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;_resolve_expected_artifacts_slot&lt;/code&gt;) — the worst-drifted copy: it read
the &lt;strong&gt;raw, unvalidated&lt;/strong&gt; parsed-YAML mapping straight off
&lt;code dir=&quot;auto&quot;&gt;MissionTemplateRepository&lt;/code&gt;, bypassing &lt;code dir=&quot;auto&quot;&gt;model_validate&lt;/code&gt; entirely.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A fifth site, &lt;code dir=&quot;auto&quot;&gt;ExpectedArtifactManifest.from_yaml_file&lt;/code&gt;, was a direct-read
orphan with no production caller, constructing via &lt;code dir=&quot;auto&quot;&gt;cls(**data)&lt;/code&gt; — a shape
no &lt;code dir=&quot;auto&quot;&gt;model_validate&lt;/code&gt;-string gate could ever police.&lt;/p&gt;
&lt;p&gt;These four had already drifted once inside #3729 (each independently patched
a subset of the org-tier/cache/error-wrap behaviour). The behavioral
consequence of that drift was #3412: &lt;code dir=&quot;auto&quot;&gt;org_expected_artifacts._read_yaml_mapping&lt;/code&gt;
swallowed a real &lt;code dir=&quot;auto&quot;&gt;YAMLError&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;org_expected_artifacts.py:109-116&lt;/code&gt;), which two-stage-laundered through
&lt;code dir=&quot;auto&quot;&gt;_resolve_org_manifest_mapping&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;_expected_artifacts_manifest_resolves&lt;/code&gt; -&gt;
&lt;code dir=&quot;auto&quot;&gt;blocking_artifact_names=None&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;evaluate_guards_strict&lt;/code&gt; raising
&lt;code dir=&quot;auto&quot;&gt;UnregisteredMissionFamilyError&lt;/code&gt; -&gt; &lt;strong&gt;caught at
&lt;code dir=&quot;auto&quot;&gt;runtime_bridge_composition.py:504&lt;/code&gt; and degraded to &lt;code dir=&quot;auto&quot;&gt;return []&lt;/code&gt;&lt;/strong&gt; (silent
green). An operator who hand-edits a custom mission family’s org-tier
manifest and introduces a real YAML-syntax error gets no signal at all — the
mission proceeds as if the manifest were absent, not broken.&lt;/p&gt;
&lt;p&gt;Fixing #3412 at the swallow site alone would leave the fix duplicated across
whichever of the four loaders happened to be reachable for a given caller —
the same drift risk that produced the four-way split in the first place.
Unifying the loaders (#3770) is therefore the enabling move: fix the
behavioral gap in exactly one place, and make it structurally impossible for
a fifth copy to appear.&lt;/p&gt;
&lt;h3 id=&quot;the-c-001-boundary&quot;&gt;The C-001 boundary&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission_type_profiles.py&lt;/code&gt; (site 4 above) lives in &lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt;.
Charter must not import &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; (project-wide constraint C-001,
enforced by &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_charter_no_specify_cli_import.py&lt;/code&gt;).
The historical canonical loader (site 1) lived in
&lt;code dir=&quot;auto&quot;&gt;specify_cli/dossier/manifest.py&lt;/code&gt;. A charter-tier caller therefore could
&lt;strong&gt;never&lt;/strong&gt; reach the specify_cli-resident authority without violating C-001 —
which is exactly why site 4 grew its own third, unvalidated copy instead of
delegating to site 1. Unifying onto a single authority requires that
authority to live somewhere every caller — runtime AND charter-tier — can
import without crossing the boundary in the wrong direction. Only &lt;code dir=&quot;auto&quot;&gt;charter&lt;/code&gt;
satisfies that for both directions (activation may import offering, proven
by existing &lt;code dir=&quot;auto&quot;&gt;mission_type_profiles.py&lt;/code&gt; imports of
&lt;code dir=&quot;auto&quot;&gt;MissionTemplateRepository&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; may import &lt;code dir=&quot;auto&quot;&gt;charter&lt;/code&gt; freely).&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;C-001 (charter must not import specify_cli).&lt;/strong&gt; The relocated authority,
and every error type it raises, must be reachable from &lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt;
without a reverse-direction import.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DIRECTIVE_044 (canonical sources, one authority).&lt;/strong&gt; The goal is not
“these four now agree” — it’s “there is exactly one implementation the
other three (or a specify_cli-side delegate) call”.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;DIRECTIVE_043 (close the defect class by construction).&lt;/strong&gt; Consolidation
alone doesn’t stop a fifth copy appearing later; a non-vacuous arch-gate
(a companion artifact to this ADR, not covered here — see
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_expected_artifacts_loader_gate.py&lt;/code&gt;) is required.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Message correctness.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError.__str__&lt;/code&gt; says
“schema-invalid” (&lt;code dir=&quot;auto&quot;&gt;specify_cli/dossier/manifest.py:149-155&lt;/code&gt; pre-move); its
own docstring pre-move explicitly &lt;em&gt;excluded&lt;/em&gt; YAML-syntax failures from its
scope. Routing a parse fault through it would be actively misleading.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Minimal blast radius for the stateful registry.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt; is
instantiated four times across specify_cli
(&lt;code dir=&quot;auto&quot;&gt;dossier_pipeline.py:361&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reconcile.py:158&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rebaseline.py:346&lt;/code&gt;, +
one doc reference) as &lt;code dir=&quot;auto&quot;&gt;Indexer(ManifestRegistry())&lt;/code&gt;; it also owns sibling
completeness methods (&lt;code dir=&quot;auto&quot;&gt;get_required_artifacts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;get_blocking_artifacts&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;get_optional_artifacts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;validate_manifest&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;clear_cache&lt;/code&gt;) that are
genuinely specify_cli-owned (dossier/indexer concerns, not manifest
resolution). Moving the whole class would drag unrelated
specify_cli-owned logic into charter.&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:&lt;/strong&gt; relocate only the &lt;em&gt;load-and-validate&lt;/em&gt; function (plus its
sibling error type) into &lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt;, and keep &lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt;
in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; as a thin delegate to that function — because it is the
smallest move that satisfies C-001 for every existing caller while leaving
specify_cli-owned state and completeness logic where it already lives.&lt;/p&gt;
&lt;h3 id=&quot;a-the-relocated-authority&quot;&gt;(a) The relocated authority&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;charter/activation/manifest_loader.py&lt;/code&gt; gains one function,
&lt;code dir=&quot;auto&quot;&gt;load_manifest(mission_type, *, repo_root)&lt;/code&gt;, carrying its own module-level
&lt;code dir=&quot;auto&quot;&gt;_cache&lt;/code&gt; keyed &lt;code dir=&quot;auto&quot;&gt;(mission_type, org_roots)&lt;/code&gt; — the same key shape the
pre-move &lt;code dir=&quot;auto&quot;&gt;ManifestRegistry._cache&lt;/code&gt; used (NFR-002: cache semantics,
cross-root non-shadowing, and declaration-order guarantees are preserved
byte-for-byte). It owns:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;org-tier resolution via &lt;code dir=&quot;auto&quot;&gt;resolve_org_expected_artifacts&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;charter/activation/org_expected_artifacts.py&lt;/code&gt;) and
&lt;code dir=&quot;auto&quot;&gt;resolve_existing_org_roots&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;charter/offering/drg/org_pack_config.py&lt;/code&gt;),&lt;/li&gt;
&lt;li&gt;built-in-tier resolution via &lt;code dir=&quot;auto&quot;&gt;MissionTemplateRepository&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;charter/offering/missions/repository.py&lt;/code&gt;),&lt;/li&gt;
&lt;li&gt;the &lt;code dir=&quot;auto&quot;&gt;ExpectedArtifactManifest.model_validate(...)&lt;/code&gt; call for both tiers,
and&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ValidationError&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; wrapping.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This satisfies FR-001. &lt;code dir=&quot;auto&quot;&gt;mission_type_profiles._resolve_expected_artifacts_slot&lt;/code&gt;
(FR-006) now calls this function directly — an intra-&lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt;
call, not a boundary crossing — and gains real schema validation as a side
effect (it previously handed callers a raw, unvalidated mapping).&lt;/p&gt;
&lt;h3 id=&quot;b-the-sibling-error-model-not-a-single-canonicalized-channel&quot;&gt;(b) The sibling error model, not a single canonicalized channel&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; (already charter-resident,
&lt;code dir=&quot;auto&quot;&gt;charter/offering/missions/repository.py:38&lt;/code&gt;, shipped in &lt;code dir=&quot;auto&quot;&gt;1763bf2ae3&lt;/code&gt; for
the built-in tier’s YAML-syntax case) and &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; (relocated
here from &lt;code dir=&quot;auto&quot;&gt;specify_cli/dossier/manifest.py&lt;/code&gt;) are &lt;strong&gt;siblings&lt;/strong&gt;, not one
canonicalized onto the other:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; — present-but-unparseable: YAML-syntax error,
non-mapping parse result, or present-but-unreadable
(&lt;code dir=&quot;auto&quot;&gt;OSError&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;UnicodeDecodeError&lt;/code&gt;) — on &lt;strong&gt;both&lt;/strong&gt; tiers (FR-007, FR-012).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; — schema/&lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt; violation, i.e. the
content parses as YAML but fails &lt;code dir=&quot;auto&quot;&gt;ExpectedArtifactManifest.model_validate&lt;/code&gt;
(FR-008).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Both are distinct from &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; = “not found” — the &lt;em&gt;only&lt;/em&gt; legitimately
absent case. The post-spec squad’s earlier draft (spec FR-008 v1)
canonicalized malformation onto &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt;; that was corrected
during research (decision D2) for three independent reasons that all point
the same direction: &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt;’s message and docstring actively
exclude parse faults; the built-in tier already used
&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; for exactly this case, so re-pointing would break
tier symmetry; and — the load-bearing one for this ADR — a
&lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt;-only design would still need &lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt;
to exist somewhere in charter anyway, since the built-in tier already raised
it, so nothing is saved by conflating the two.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; stays where it already lived
(&lt;code dir=&quot;auto&quot;&gt;charter/offering/missions/repository.py&lt;/code&gt;), beside
&lt;code dir=&quot;auto&quot;&gt;MissionTemplateRepository&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; moves to
&lt;code dir=&quot;auto&quot;&gt;charter/activation/manifest_loader.py&lt;/code&gt;, beside the function that raises it.
They live in &lt;strong&gt;two different charter modules&lt;/strong&gt;, not one, because
&lt;code dir=&quot;auto&quot;&gt;charter.offering&lt;/code&gt; (where &lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; sits) must not import
&lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt; (where the loader sits) — the same directional
constraint as C-001, one layer down: activation may depend on offering,
never the reverse (confirmed by the only existing offering-side reference to
activation being a &lt;code dir=&quot;auto&quot;&gt;TYPE_CHECKING&lt;/code&gt;-only mention,
&lt;code dir=&quot;auto&quot;&gt;mission_step_repository.py:44&lt;/code&gt;). The loader in &lt;code dir=&quot;auto&quot;&gt;activation&lt;/code&gt; imports
&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;offering&lt;/code&gt; (the allowed direction) to raise
it for the org-tier and widened-built-in-tier parse-fault cases; it does not
need to import anything from &lt;code dir=&quot;auto&quot;&gt;activation&lt;/code&gt; to define
&lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; locally beside itself.&lt;/p&gt;
&lt;h3 id=&quot;c-the-deprecation-shim-contract&quot;&gt;(c) The deprecation-shim contract&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli/dossier/manifest.py&lt;/code&gt; re-exports, with &lt;strong&gt;object identity&lt;/strong&gt;
preserved (verified by &lt;code dir=&quot;auto&quot;&gt;tests/dossier/test_manifest.py&lt;/code&gt;’s shim-reexport-surface
tests — &lt;code dir=&quot;auto&quot;&gt;import X as Y; X is Y&lt;/code&gt;, not a re-implementation):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt; — kept in place (see (d)).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;load_manifest&lt;/code&gt; — the relocated authority function, re-exported directly.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; — the relocated sibling error, re-exported directly.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; — re-exported from its charter home, so a
specify_cli-side &lt;code dir=&quot;auto&quot;&gt;except MalformedManifestError&lt;/code&gt; catches the same
exception type the charter-tier authority raises.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This is FR-002. &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; is caught at 8+ specify_cli sites
(&lt;code dir=&quot;auto&quot;&gt;sync/namespace.py:102&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;sync/dossier_pipeline.py:363&lt;/code&gt;, six tests as of
this mission); omitting it from the shim would break every one of those
catch sites on import. The shim’s removal is a future, separately announced
deprecation — not scheduled by this ADR.&lt;/p&gt;
&lt;h3 id=&quot;d-manifestregistry-stays-in-specify_cli&quot;&gt;(d) &lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt; stays in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ManifestRegistry.load_manifest&lt;/code&gt; becomes a thin delegate to
&lt;code dir=&quot;auto&quot;&gt;charter.activation.manifest_loader.load_manifest&lt;/code&gt;; the class itself, and
its sibling completeness methods (&lt;code dir=&quot;auto&quot;&gt;get_required_artifacts&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;get_blocking_artifacts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;get_optional_artifacts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;validate_manifest&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;clear_cache&lt;/code&gt;), do &lt;strong&gt;not&lt;/strong&gt; move (FR-003, decision D3). The alternative —
moving the whole class into charter — was rejected: it would relocate
dossier/indexer-completeness logic that has nothing to do with the
charter↔specify_cli manifest-resolution seam, purely to keep one class’s
methods physically adjacent. &lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt; is instantiated four times
in specify_cli as &lt;code dir=&quot;auto&quot;&gt;Indexer(ManifestRegistry())&lt;/code&gt;; none of those call sites
need to change.&lt;/p&gt;
&lt;h3 id=&quot;e-c-006--a-corrupt-org-override-now-hard-blocks-a-registered-built-in-family&quot;&gt;(e) C-006 — a corrupt org override now hard-blocks a registered built-in family&lt;/h3&gt;
&lt;p&gt;The guard-table short-circuit for a &lt;strong&gt;registered built-in family&lt;/strong&gt; (e.g.
&lt;code dir=&quot;auto&quot;&gt;software-dev&lt;/code&gt;) — &lt;code dir=&quot;auto&quot;&gt;runtime_bridge_cores.py:721-723&lt;/code&gt; — decides
&lt;code dir=&quot;auto&quot;&gt;blocking_artifact_names&lt;/code&gt; &lt;strong&gt;before&lt;/strong&gt; the composed guard reads the manifest
resolution result, and that short-circuit is explicitly out of this
mission’s scope (C-003, owned by #3386/#3397/#3407). Manifest resolution
itself, however, now runs at &lt;em&gt;gather&lt;/em&gt; time
(&lt;code dir=&quot;auto&quot;&gt;runtime_bridge_composition.py:486&lt;/code&gt;), &lt;strong&gt;before&lt;/strong&gt; that short-circuit
decision is consulted. If an operator has authored a &lt;strong&gt;corrupt org-tier
override&lt;/strong&gt; for &lt;code dir=&quot;auto&quot;&gt;software-dev&lt;/code&gt; — a family the project has registered and
that therefore has a perfectly good built-in &lt;code dir=&quot;auto&quot;&gt;expected-artifacts.yaml&lt;/code&gt;
available as a fallback — &lt;code dir=&quot;auto&quot;&gt;load_manifest&lt;/code&gt; still raises
&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; at gather time, because C-006 treats a
present-but-corrupt org file as an operator-authored override that failed,
never as “fall back silently to the good built-in file underneath it.”&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This is a deliberate hard-block, not an oversight.&lt;/strong&gt; The operator wrote
the org override expecting it to take effect; silently falling back to the
built-in manifest instead would mean the override is inert exactly when it
is broken — the worst possible time to discover that. The consequence is
that a single malformed org file for a registered built-in family now
blocks that &lt;em&gt;entire&lt;/em&gt; family’s guard evaluation, not just the custom-family
case #3412 originally targeted. This is covered by an explicit acceptance
scenario (spec.md Edge Cases, “Corrupt org override, registered built-in
family”) and is intentional scope: &lt;code dir=&quot;auto&quot;&gt;C-002&lt;/code&gt; (the &lt;code dir=&quot;auto&quot;&gt;blocking_artifact_names&lt;/code&gt;
None-vs-&lt;code dir=&quot;auto&quot;&gt;frozenset()&lt;/code&gt; tri-state, #3729) and &lt;code dir=&quot;auto&quot;&gt;C-003&lt;/code&gt; (the guard-table
short-circuit itself) are both untouched — the raise happens &lt;em&gt;before either
is consulted&lt;/em&gt;, so this ADR’s change composes with both without mutating
them.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A. Fix #3412 at the swallow site only, leave the four loaders
unconsolidated.&lt;/strong&gt; Rejected: the fix would live in whichever loader the
swallow site’s caller happened to route through; the other three copies
keep their own independent (and in one case, unvalidated) resolution
paths, so the drift that caused #3412 in the first place remains
structurally possible for the next behavioral change.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B. Consolidate the four loaders in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;, leave the
charter-tier caller unable to reach the shared authority.&lt;/strong&gt; Rejected:
C-001 forbids charter importing specify_cli, so
&lt;code dir=&quot;auto&quot;&gt;mission_type_profiles.py&lt;/code&gt; would still need its own copy — #3770 stays
half-closed, and the worst-drifted (unvalidated) copy survives.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C. Relocate the authority into &lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt;; keep
&lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt; as a specify_cli-side thin delegate; shim the old
import path (chosen).&lt;/strong&gt; Satisfies C-001 for every caller, leaves the
smallest possible blast radius on &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;-owned state, and breaks
no existing importer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D. Canonicalize malformation onto &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; instead of a
sibling &lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt;.&lt;/strong&gt; Rejected during research (D2): message
content is misleading for a parse fault, it would break built-in-tier
symmetry with the already-shipped &lt;code dir=&quot;auto&quot;&gt;1763bf2ae3&lt;/code&gt; fix, and it does not avoid
needing &lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; to exist in charter regardless (the
built-in tier already raises it).&lt;/li&gt;
&lt;/ul&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;Exactly one production implementation of the org-tier/built-in-tier
precedence + &lt;code dir=&quot;auto&quot;&gt;model_validate&lt;/code&gt; + error-wrap logic remains (SC-001); the
three mirrors delegate to it, and the &lt;code dir=&quot;auto&quot;&gt;from_yaml_file&lt;/code&gt; orphan is deleted
outright rather than routed (FR-013 — &lt;code dir=&quot;auto&quot;&gt;cls(**data)&lt;/code&gt; construction is a
shape no &lt;code dir=&quot;auto&quot;&gt;model_validate&lt;/code&gt;-string gate can see, so deleting it is the only
way to keep it dead).&lt;/li&gt;
&lt;li&gt;A YAML-syntax-broken org manifest for a custom mission family now fails
loud via &lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt;, distinct from absence, closing #3412 at
its one true source instead of at a caller-specific swallow point.&lt;/li&gt;
&lt;li&gt;The charter-tier consumer (&lt;code dir=&quot;auto&quot;&gt;_resolve_expected_artifacts_slot&lt;/code&gt;) gains real
schema validation it never had before this mission — a schema-invalid
manifest at that call site now raises &lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt; instead of
silently handing every downstream reader a bad raw mapping.&lt;/li&gt;
&lt;li&gt;No existing importer of &lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;load_manifest&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; from
&lt;code dir=&quot;auto&quot;&gt;specify_cli/dossier/manifest&lt;/code&gt; breaks (the shim re-exports all four with
preserved object identity).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A corrupt org-tier override for a &lt;em&gt;registered&lt;/em&gt; built-in family (C-006)
now hard-blocks that family’s guard evaluation even though a good
built-in fallback exists on disk — a strictly more blocking behavior than
before this mission for that specific edge case. This is accepted as the
honest outcome of fail-loud-on-override; the alternative (silent
fallback) reopens the exact class of bug #3412 exists to close, one layer
up.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter.offering&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt; now each hold one half of a
conceptually paired sibling-error model
(&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;ManifestSchemaError&lt;/code&gt;) rather than both living
in one module — a direct consequence of the offering-must-not-import-activation
direction constraint, documented here so a future reader does not “fix”
the split by moving one beside the other.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ManifestRegistry&lt;/code&gt;’s public API (&lt;code dir=&quot;auto&quot;&gt;get_required_artifacts&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;get_blocking_artifacts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;get_optional_artifacts&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;validate_manifest&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;clear_cache&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;load_manifest&lt;/code&gt;) is unchanged from every caller’s
perspective; only &lt;code dir=&quot;auto&quot;&gt;load_manifest&lt;/code&gt;’s internals became a delegate call.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;NFR-001 (byte-compatible resolution) / NFR-002 (cache semantics
preserved):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;test_configured_artifact_name&lt;/code&gt;, the bridge-parity suites,
and &lt;code dir=&quot;auto&quot;&gt;TestManifestRegistryOrgTier&lt;/code&gt;’s cache tests pass unchanged, exercised
through the delegate.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;FR-011 (non-vacuous arch-gate), companion to this ADR:&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_expected_artifacts_loader_gate.py&lt;/code&gt; forbids bare
&lt;code dir=&quot;auto&quot;&gt;ExpectedArtifactManifest.model_validate(&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;ExpectedArtifactManifest(&lt;/code&gt;
outside &lt;code dir=&quot;auto&quot;&gt;charter/activation/manifest_loader.py&lt;/code&gt; and the model’s own
module; a self-mutation test proves the gate is not vacuous.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;FR-009/FR-010 (launder-seam closure):&lt;/strong&gt; a positive regression asserts a
malformed org manifest through the composed guard path propagates and is
never degraded to &lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C-006 (hard-block acceptance):&lt;/strong&gt; covered by an explicit RED-on-main
acceptance scenario for the registered-built-in-family + corrupt-org-override
case (spec.md Edge Cases).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec:
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/expected-artifacts-loader-unification-01M1C9VQ/spec.md&lt;/code&gt;
(FR-001, FR-002, FR-003, FR-007, FR-008, and the full FR-001..FR-014 set).&lt;/li&gt;
&lt;li&gt;Research decisions D1-D9:
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/expected-artifacts-loader-unification-01M1C9VQ/research.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Arch-gate contract:
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/expected-artifacts-loader-unification-01M1C9VQ/contracts/arch-gate.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Relocated authority:
&lt;a href=&quot;../../../src/charter/activation/manifest_loader.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/manifest_loader.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Deprecation shim:
&lt;a href=&quot;../../../src/specify_cli/dossier/manifest.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dossier/manifest.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MalformedManifestError&lt;/code&gt; home:
&lt;a href=&quot;../../../src/charter/offering/missions/repository.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/missions/repository.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Arch-gate enforcement:
&lt;a href=&quot;../../../tests/architectural/test_expected_artifacts_loader_gate.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_expected_artifacts_loader_gate.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;C-001 boundary enforcement:
&lt;a href=&quot;../../../tests/architectural/test_charter_no_specify_cli_import.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_charter_no_specify_cli_import.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Prior built-in-tier fail-loud fix (symmetry baseline): commit &lt;code dir=&quot;auto&quot;&gt;1763bf2ae3&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
