What: Replace the current parallel defaultConfig + envBindings tree shape in ai/config.template.mjs with a single meta-leaf tree ({env, default, parse} per leaf) consumed by a new BaseConfig extends Neo.state.Provider. Consumers read AiConfig.X.Y directly at point of use; orchestrator delegation getters / helper-takes-config / direct-.data bypass / hidden-default-fallback (??) anti-pattern classes all retire via codemod sweep. Conservative-merge mode added to ai/scripts/setup/initServerConfigs.mjs so operator overlays advance with template additions without losing local overrides.
Why: Operator surfaced 2026-05-27 on PR #12099 diff that ~92 consumer-side anti-pattern sites (across 5 sub-classes) had accreted because env-vs-default-precedence leaks into consumer code through delegation getters + Env.parseX('NEO_X') ?? AiConfig.X patterns. Root cause: BaseConfig's Proxy was never properly extending Body-tier Neo.state.Provider (which has had hierarchical reactive substrate since July 2025 — 8949 commits, ~10 months production). Extending Provider directly eliminates ~900-1200 LOC of consumer-side boilerplate + structurally prevents the regression-accretion pattern.
Approach: Extend Body-tier Neo.state.Provider + Neo.core.Config + createHierarchicalDataProxy primitives directly; do not invent parallel reactivity machinery. Brain-specific extensions limited to: env-layer (#runtimeEnvOverrides Map), parser registry (#leafMetadataRegistry), parser-validation override at internalSetData() choke point, env-overlay-merge in compileMetaLeaves. Same discipline extends to Brain-tier bootstrap scripts (ai/scripts/setup/initServerConfigs.mjs extension, not parallel primitive). PR review checkpoint: grep src/state/ AND ai/scripts/ for analogous primitives BEFORE accepting any new mechanism.
Migration shape (7 stages, sub-tickets linked via native parent_child):
- Stage 0: extend
initServerConfigs.mjs with overlay-preserving template advancement (--merge-config flag distinct from --migrate-config overwrite)
- Stage 1:
BaseConfig extends Neo.state.Provider; compileMetaLeaves + parser registry + setEnvOverride API + path-scoped observeConfig
- Stage 2: rewrite
ai/config.template.mjs to single meta-leaf tree
- Stage 3: orchestrator codemod — delete 16 delegation getters
- Stage 4: services + MCP-server codemod — A/B/D-prod/E sub-classes (~50-70 sites; D-test 33 sites stay as-is per set-trap pattern preserving test ergonomics)
- Stage 5: retract
Env.mjs consumer-facing exports + delete regression-as-doctrine JSDoc
- Stage 6: delete legacy
applyEnv() path from ai/BaseConfig.mjs
Acceptance Criteria
Out of Scope
- Per-file enumeration of the ~92 actionable migration sites — deferred to Stage 3/4 codemod execution evidence (initial-scope OQ8 ledger sufficient at graduation gate per @neo-gpt indicative-scale framing)
- Full reactive integration of aiConfig with Neo's effect system —
observeConfig(path, fn) returning cleanup is sufficient
- Body-tier
Neo.state.Provider modifications — extends only; no upstream Provider edits
- Test-overlay drift (#11976 scope) — distinct surface; tests read canonical templates/fixtures, runtime reads operator overlays
- Hot-reload of
ai/config.mjs during dev — Stage 1 prototype scope is construct/load-time
Related
- Discussion #12100 — graduation source (CLOSED RESOLVED); design rationale + 5 OQs (OQ6 PR disposition / OQ7 per-MCP-server scoping / OQ8 consumer ledger / OQ9 density prototype / OQ10 Option A vs F)
- PR #12099 — Sandman P0 mitigation MERGED with retirement-contract pointer to this Epic
- PR #12098 — envBindings expansion MERGED under "interim debt accepted" framing; Stage 3 retires
- #11976 — test-overlay-drift scope (complementary, not absorbed)
Discussion Criteria Mapping
Carried into the Epic body from the source Discussion #12100 final body (v15, populated per §6.6) per @neo-gpt epic-review Stage 2.5 review (2026-05-28). Lives here so sub-ticket pickup can verify no graduation criterion was dropped Discussion → Epic.
| Discussion #12100 Criterion |
Resolution Tag |
Epic AC Mapping |
| §9 Criterion 1: §5.2 Step-Back sweep posted by ≥1 non-author peer |
DONE — 15 cycles by @neo-gpt (3 STEP_BACK + multiple refinements) + 2 cycles by @neo-gemini-pro |
cross-family substrate-review provenance preserved in the Epic "Graduation provenance" section below |
| §9 Criterion 2: All 10 OQs reach resolution tags |
DONE — OQ1 REJECTED; OQ2/6/7/8/9/10 RESOLVED_TO_AC; OQ3/4/5/11 PENDING (all Stage-1-implementation-detail, non-blocking) |
implementation OQs (3/4/5/11) deferred to Stage 1 sub-ticket #12103 per §9 explicit tagging |
| §9 Criterion 3: OQ8 consumer ledger COMPLETE |
DONE — initial-scope ledger (~92 actionable sites bucketed across 5 sub-classes; 94% of 1486-hit corpus in target shape) |
per-file enumeration deferred to Stage 3/4 sub-tickets #12105 / #12106 execution evidence per @neo-gpt indicative-scale framing; mirrored in ## Out of Scope |
| §9 Criterion 4: OQ9 density/UX prototype LANDED |
DONE — 21-leaf prototype by @neo-gemini-pro + @neo-gpt parser-semantics + path-scoped-observer + canonical-or-pseudocode corrections |
prototype validates compileTree end-to-end; Stage 1 sub-ticket #12103 inherits prototype shape (AC-Epic-3 + AC-Epic-5) |
| §9 Criterion 5: §6.2 Signal Ledger quorum reached |
DONE — @neo-gpt [GRADUATION_APPROVED_INHERITS_WITH_STAGE1_REFINEMENT] inheritance chain v6→v14 with 8+ anchored confirmations |
quorum-bearing residuals (3 Stage 1 ACs + 3 Stage 0 ACs + Epic-level implementation discipline mandate) preserved as Epic + sub-ticket ACs (AC-Epic-4/5 + #12102 / #12103) |
| §9 Criterion 6: Migration staging refined to concrete sub-ticket decomposition |
DONE — 7 stages defined with explicit ACs per stage |
7 stage sub-tickets #12102–#12108 filed + native parent_child linkage; later context-limits children #12114 / #12116 / #12117 (all CLOSED) also linked under this Epic |
Graduation provenance (process archaeology — fresh sessions can skip)
Graduated from /ideation-sandbox Discussion #12100 (v15 anchor 2026-05-27T20:09:42Z). 15-cycle STEP_BACK convergence with @neo-gpt + @neo-gemini-pro cross-family peer review.
Quorum: [GRADUATION_APPROVED_INHERITS_WITH_STAGE1_REFINEMENT] by @neo-gpt with 8+ anchored inheritance confirmations across v6→v14. @neo-gemini-pro [GRADUATION_DEFERRED] converging per stated condition (OQ8 + OQ9 both landed; conversion welcome but not quorum-required since GPT inheritance alone satisfies §6.2).
15 STEP_BACK convergence cycles produced: 3 Stage 1 ACs (parser-validation choke point + separate metadata registry + hierarchical deep-merge) + 3 Stage 0 ACs (per-key-path drift detection + conservative-merge mode + no --migrate-config regression) + Epic-level implementation discipline mandate (extend Body Provider + Brain bootstrap scripts; avoid parallel machinery; PR-review checkpoint).
Origin Session ID: ba55de70-c601-448e-9eb4-9c214be1d9c6. Authored by Claude Opus 4.7 (Claude Code 1M).
What: Replace the current parallel
defaultConfig+envBindingstree shape inai/config.template.mjswith a single meta-leaf tree ({env, default, parse}per leaf) consumed by a newBaseConfig extends Neo.state.Provider. Consumers readAiConfig.X.Ydirectly at point of use; orchestrator delegation getters / helper-takes-config / direct-.databypass / hidden-default-fallback (??) anti-pattern classes all retire via codemod sweep. Conservative-merge mode added toai/scripts/setup/initServerConfigs.mjsso operator overlays advance with template additions without losing local overrides.Why: Operator surfaced 2026-05-27 on PR #12099 diff that ~92 consumer-side anti-pattern sites (across 5 sub-classes) had accreted because env-vs-default-precedence leaks into consumer code through delegation getters +
Env.parseX('NEO_X') ?? AiConfig.Xpatterns. Root cause: BaseConfig's Proxy was never properly extending Body-tierNeo.state.Provider(which has had hierarchical reactive substrate since July 2025 — 8949 commits, ~10 months production). Extending Provider directly eliminates ~900-1200 LOC of consumer-side boilerplate + structurally prevents the regression-accretion pattern.Approach: Extend Body-tier
Neo.state.Provider+Neo.core.Config+createHierarchicalDataProxyprimitives directly; do not invent parallel reactivity machinery. Brain-specific extensions limited to: env-layer (#runtimeEnvOverridesMap), parser registry (#leafMetadataRegistry), parser-validation override atinternalSetData()choke point, env-overlay-merge incompileMetaLeaves. Same discipline extends to Brain-tier bootstrap scripts (ai/scripts/setup/initServerConfigs.mjsextension, not parallel primitive). PR review checkpoint: grepsrc/state/ANDai/scripts/for analogous primitives BEFORE accepting any new mechanism.Migration shape (7 stages, sub-tickets linked via native
parent_child):initServerConfigs.mjswith overlay-preserving template advancement (--merge-configflag distinct from--migrate-configoverwrite)BaseConfig extends Neo.state.Provider; compileMetaLeaves + parser registry +setEnvOverrideAPI + path-scopedobserveConfigai/config.template.mjsto single meta-leaf treeEnv.mjsconsumer-facing exports + delete regression-as-doctrine JSDocapplyEnv()path fromai/BaseConfig.mjsAcceptance Criteria
Neo.state.Provider; parallel reactivity machinery REJECTED at PR review. Permitted extensions enumerated above; anything else is reinvention.aiConfig.set('debug', true); D-test 33 sites unchanged under Provider's set-trap-routes-to-setData mechanism).set/setEnvOverride) + path-scoped reactive subscriptions (observeConfig(path, fn)) + direct-assignment via Provider set trap (preserves 157+ test mutation sites without rewrite per @neo-gemini-pro V-B-A).data_) so future agents don't re-ask "should we extend Provider or invent parallel?"internalSetData()choke point (metadata-path-first rule — validate ANY value at known leaf path; namespace recursion intermediates pass through) + separate#leafMetadataRegistry(independent of Provider's reactive#dataConfigs) + hierarchical deep-merge via Provider'sdata_: {[isDescriptor]: true, merge: 'deep', value: {}}descriptor.Out of Scope
observeConfig(path, fn)returning cleanup is sufficientNeo.state.Providermodifications — extends only; no upstream Provider editsai/config.mjsduring dev — Stage 1 prototype scope is construct/load-timeRelated
Discussion Criteria Mapping
Carried into the Epic body from the source Discussion #12100 final body (v15, populated per §6.6) per @neo-gpt
epic-reviewStage 2.5 review (2026-05-28). Lives here so sub-ticket pickup can verify no graduation criterion was dropped Discussion → Epic.## Out of Scope[GRADUATION_APPROVED_INHERITS_WITH_STAGE1_REFINEMENT]inheritance chain v6→v14 with 8+ anchored confirmationsparent_childlinkage; later context-limits children #12114 / #12116 / #12117 (all CLOSED) also linked under this EpicGraduation provenance (process archaeology — fresh sessions can skip)
Graduated from
/ideation-sandboxDiscussion #12100 (v15 anchor 2026-05-27T20:09:42Z). 15-cycle STEP_BACK convergence with @neo-gpt + @neo-gemini-pro cross-family peer review.Quorum:
[GRADUATION_APPROVED_INHERITS_WITH_STAGE1_REFINEMENT]by @neo-gpt with 8+ anchored inheritance confirmations across v6→v14. @neo-gemini-pro[GRADUATION_DEFERRED]converging per stated condition (OQ8 + OQ9 both landed; conversion welcome but not quorum-required since GPT inheritance alone satisfies §6.2).15 STEP_BACK convergence cycles produced: 3 Stage 1 ACs (parser-validation choke point + separate metadata registry + hierarchical deep-merge) + 3 Stage 0 ACs (per-key-path drift detection + conservative-merge mode + no
--migrate-configregression) + Epic-level implementation discipline mandate (extend Body Provider + Brain bootstrap scripts; avoid parallel machinery; PR-review checkpoint).Origin Session ID:
ba55de70-c601-448e-9eb4-9c214be1d9c6. Authored by Claude Opus 4.7 (Claude Code 1M).