Author ADR 0019 (AiConfig SSOT) + the turn-loaded AGENTS.md read-gate

Sub #1 of Epic #12456 (AiConfig-SSOT antipattern cleanup). PRIO 0 — the read-gate keystone; every other sub + every reviewer depends on it. Graduated from Discussion #12453; Decision Record: REQUIRED per ADR 0005. Drafted ADR content already exists: discussion comment DC_kwDODSospM4BBglP (the raw material for this PR).

Backfill (operator OQ1 reversal, 2026-06-04): learn/agentos/AiConfigModel.md is public-facing docs (learn/tree.json is its nav) and is PRESERVED unchanged — the ADR complements it, it is NOT absorbed/retired. The new ADR file is registered in learn/tree.json. This body is backfilled to match the shipped shape (PR #12458 head 249bc5ebf).

Context

Reading the 3 primitive files (src/state/Provider.mjs + src/state/createHierarchicalDataProxy.mjs + ai/BaseConfig.mjs) to understand AiConfig before touching ai/ config is too heavy for a hot fix — so it gets skipped, and authors/reviewers pattern-match the broken surrounding code instead (the #12420 broken-window: 4 defects, 0 caught across 2 reviews). The structural fix is a sharp ADR distillation authors read instead of the 3 files, made un-skippable by a turn-loaded one-line trigger.

The Problem

Without (a) a lean authority and (b) a mechanical read-gate, the antipattern cluster re-rots after cleanup. "I'll be more careful" is empirically falsified (4/4 #12420 defects missed). The ADR is the sanctioned-pattern reference a reviewer + the lint (sub #2) check against; the AGENTS.md trigger makes the ADR-read un-skippable for every family.

The Architectural Reality

• ADR path (deterministic): learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md (next number after 0018). Registered in learn/tree.json under Architectural Decision Records (a new learn/ file must appear in the docs nav).
• Turn-loaded hook placement (verified): .claude/CLAUDE.md is a symlink → ../AGENTS.md (no generator in buildScripts//workflows/). One edit to AGENTS.md §edge_case_triggers covers all families. Net loaded-byte delta negative — one line replaces a 3-file primitive read.
• Compaction discipline: ADR 0007 (high-frequency trigger in the turn-loaded layer, depth in the ADR).
• AiConfigModel.md (public guide): it overlaps the ADR's how-it-works, but it is public-facing docs → preserved, not absorbed. The ADR carries its own maintainer-facing how-it-works (§2.1) and cross-references the guide.

The Fix

1. Author ADR 0019 from the drafted content (DC_kwDODSospM4BBglP), structured per ADR 0005 §2.4 (lean, executable authority — NOT a Discussion paste): primitive model (leaf/hierarchy/formulas/proxy/merge:deep) + the A/B/C antipattern catalog with each ID tagged live-on-dev vs #12420-proposed + the ⭐ B4 safety-critical danger + sanctioned patterns + the V-B-A pre-flight read-gate.
2. OQ1 (operator-reversed): preserve learn/agentos/AiConfigModel.md (public docs guide); the ADR complements it (maintainer audience) and carries the examples/stateProvider/advanced read-up/write-to-owner link into §2.1; register ADR 0019 in learn/tree.json.
3. OQ3 (opus V-B-A DC_kwDODSospM4BBgm5): the ai/ daemons are entrypoints (they import Neo/_export/AiConfig), so their path re-derivation is A1, not C1; the single genuine C1×B5 site is TaskDefinitions.mjs. Frame C1 as bootstrap-weight (entrypoints read AiConfig directly; only genuine non-entrypoint helpers use the pure-defaults module). Catalog tags A1-with-AiConfig-imported vs genuine-C1.
4. Add the one-line trigger to AGENTS.md §edge_case_triggers; cite ADR 0007 + substrate-accretion defense in the PR body.

Contract Ledger Matrix

Acceptance Criteria

• learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md authored (Status: Draft → Accepted on human merge), lean per ADR 0005 §2.4.
• Catalog A/B/C present, each ID tagged live-on-dev vs #12420-proposed.
• ⭐ B4 documented as safety-critical (the #12335 test→live-DB bleed mechanism; chromaTestIsolation by-construction).
• OQ3: C1 framed as bootstrap-weight; daemons tagged A1 (entrypoints); genuine C1×B5 = TaskDefinitions.mjs; catalog tags A1-with-AiConfig-imported vs genuine-C1; pure-defaults-module sanctioned shape named.
• AiConfigModel.md preserved unchanged (public guide); ADR 0019 complements it (OQ1 reversal) and carries its examples/stateProvider/advanced link into §2.1.
• ADR 0019 registered in learn/tree.json (docs nav).
• One-line turn-loaded trigger added to AGENTS.md §edge_case_triggers → ADR 0019; PR body declares net-negative loaded-byte delta + cites ADR 0007.
• Cross-family review: @neo-gpt holds peer-review on this PR; @neo-opus-ada contributed OQ3.
• (human-gated) merge by @tobiu = ADR content-accuracy approval; ADR flips to Accepted. Fan-out + cleanup subs unblock only after this PR merges.

Out of Scope

• The fail-build lint (= sub #2).
• The exhaustive ai/ fan-out inventory + cleanup subs (post-merge; operator-gated).
• Backfilling ADRs 0002–0018 into learn/tree.json (pre-existing docs-nav gap; separate follow-up).

Decision Record impact

produces ADR 0019; aligned-with ADR 0007; depends-on ADR 0005; complements (does not replace) learn/agentos/AiConfigModel.md.

Related

• Parent: Epic #12456. Origin: Discussion #12453 (ADR draft DC_kwDODSospM4BBglP; V-B-A refinement DC_kwDODSospM4BBgl2). gpt STEP_BACK: DC_kwDODSospM4BBgl_. opus OQ3 daemon-A1 V-B-A: DC_kwDODSospM4BBgm5.
• Complements (does not replace): learn/agentos/AiConfigModel.md (public configuration-model guide).

Origin Session ID

3ecb40bf-bfef-40b1-8693-a8aae5afa1b7

Handoff Retrieval Hints

• query_raw_memories: "ADR 0019 AiConfig SSOT read-gate AGENTS.md trigger", "AiConfig participation prerequisite primitive".
• The complete drafted ADR content is Discussion #12453 comment DC_kwDODSospM4BBglP.