Context
The #12456 epic's C3 row (tests import the gitignored operator overlay instead of the canonical template), re-scoped by the 2026-07-12 fan-out census and sharpened to import-statement grain on the epic today (comment IC_kwDODSospM8AAAABKWkI4g): ~13 actual import statements across 15 test files reference a config.mjs overlay. Predecessor #11976 (closed) cleared ~78 at the time; today's set is regression-since or residue. ADR 0019 §3 C3 is the authority; the danger class is machine-dependent test behavior — a gitignored, operator-edited overlay silently changes what specs assert on different checkouts (this machine currently runs FIVE peer checkouts, each with divergent overlays — today's port-collision incident #15221 is the live demonstration of overlay divergence).
The Problem
Three sub-classes from the import-grain census, requiring different treatment:
- Swap-to-template (the mechanical majority): the
ai/ unit-spec cluster importing ../../../config.mjs / ai/config.mjs where the spec needs "a valid AiConfig shape", not this operator's values — the canonical config.template.mjs is the deterministic substitute.
- Legit-subject (keep, allowlist): specs whose SUBJECT is the overlay/template relationship itself —
lintConfigTemplateSsot.spec.mjs (tests the overlay-vs-template lint) and, if verification confirms, initServerConfigs.spec.mjs (tests the drift detector). These import the overlay BECAUSE it is what they test; swapping them would delete their subject.
- Needs-judgment: the
ai/mcp/client/config.mjs (×2) and mcp/server/github-workflow/config.mjs (×1) importers — per-file check whether a canonical template sibling exists for that surface and whether the spec's assertions depend on live overlay state.
The Architectural Reality
- ADR 0019 §3 C3 (
learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md) — the read-gate authority; §5.5 governs when an env/overlay read is legitimate.
- The recurrence backstop belongs to the #14500 lint rail (now shipping via its own subs) — this ticket's classification list is the allowlist seed for that rule.
- Census provenance: the epic comment above carries the exact per-file breakdown (7× relative root-overlay, 2×
ai/config.mjs, 2× client, 1× server/github-workflow, 1× ./config.mjs).
The Fix
One PR: (1) per-file verification of each of the 15 against the three classes (blame for regression-vs-residue lineage recorded in the PR body); (2) the class-1 swaps to config.template.mjs; (3) class-2 files annotated in place (one-line rationale comment) and listed for the lint allowlist; (4) class-3 dispositions executed or explicitly deferred with reasons; (5) the affected specs green.
Acceptance Criteria
Out of Scope
- The lint rule itself (#14500 rail owns enforcement).
- B4/A1/C2 rows (separate census rows on the epic).
- The overlay/template SSOT mechanics (owned by
initServerConfigs + its lint).
Related
Parent: #12456 (linked natively) · authority: ADR 0019 §3 C3 · predecessor: #11976 (closed) · census: the 2026-07-16 epic comment · enforcement rail: #14500 · overlay-divergence demonstration: #15221
Live latest-open sweep: checked latest 8 open issues at 2026-07-16T08:32Z; no equivalent. A2A sweep: mailbox drained 08:29Z, no overlapping claim (the 07-12 census explicitly left subs self-selectable).
Origin Session ID: 2c0a23e9-f468-4de6-9e29-ddec96103fb4
Retrieval Hint: "C3 tests import canonical template overlay swap allowlist classification"
Context
The #12456 epic's C3 row (
tests import the gitignored operator overlay instead of the canonical template), re-scoped by the 2026-07-12 fan-out census and sharpened to import-statement grain on the epic today (commentIC_kwDODSospM8AAAABKWkI4g): ~13 actual import statements across 15 test files reference aconfig.mjsoverlay. Predecessor #11976 (closed) cleared ~78 at the time; today's set is regression-since or residue. ADR 0019 §3 C3 is the authority; the danger class is machine-dependent test behavior — a gitignored, operator-edited overlay silently changes what specs assert on different checkouts (this machine currently runs FIVE peer checkouts, each with divergent overlays — today's port-collision incident #15221 is the live demonstration of overlay divergence).The Problem
Three sub-classes from the import-grain census, requiring different treatment:
ai/unit-spec cluster importing../../../config.mjs/ai/config.mjswhere the spec needs "a valid AiConfig shape", not this operator's values — the canonicalconfig.template.mjsis the deterministic substitute.lintConfigTemplateSsot.spec.mjs(tests the overlay-vs-template lint) and, if verification confirms,initServerConfigs.spec.mjs(tests the drift detector). These import the overlay BECAUSE it is what they test; swapping them would delete their subject.ai/mcp/client/config.mjs(×2) andmcp/server/github-workflow/config.mjs(×1) importers — per-file check whether a canonical template sibling exists for that surface and whether the spec's assertions depend on live overlay state.The Architectural Reality
learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md) — the read-gate authority; §5.5 governs when an env/overlay read is legitimate.ai/config.mjs, 2× client, 1× server/github-workflow, 1×./config.mjs).The Fix
One PR: (1) per-file verification of each of the 15 against the three classes (blame for regression-vs-residue lineage recorded in the PR body); (2) the class-1 swaps to
config.template.mjs; (3) class-2 files annotated in place (one-line rationale comment) and listed for the lint allowlist; (4) class-3 dispositions executed or explicitly deferred with reasons; (5) the affected specs green.Acceptance Criteria
test/(verified by the census grep re-run in the PR body).Out of Scope
initServerConfigs+ its lint).Related
Parent: #12456 (linked natively) · authority: ADR 0019 §3 C3 · predecessor: #11976 (closed) · census: the 2026-07-16 epic comment · enforcement rail: #14500 · overlay-divergence demonstration: #15221
Live latest-open sweep: checked latest 8 open issues at 2026-07-16T08:32Z; no equivalent. A2A sweep: mailbox drained 08:29Z, no overlapping claim (the 07-12 census explicitly left subs self-selectable).
Origin Session ID: 2c0a23e9-f468-4de6-9e29-ddec96103fb4
Retrieval Hint: "C3 tests import canonical template overlay swap allowlist classification"