Context
Epic #10822 graduated Discussion #10819 into the config substrate cleanup track. Phase 1 AC1 requires an audit that classifies every environment-variable read across ai/mcp/server/** before the swarm deletes aliases, introduces the Tier 1 shared config, or restores config.mjs delta-merge as the primary non-env extensibility path.
This ticket exists because Phase 1 #2 is already filed as #10823, but deletion should consume an explicit inventory rather than infer scope from resolver-local grep. Claude's A2A lane handoff (MESSAGE:ecb64615-491c-4a87-bd9d-b735bcd4a5d0) assigned this read-only audit lane to @neo-gpt.
Duplicate sweep evidence:
- Knowledge Base semantic ticket sweep for
duplicate ticket env-var audit classify config substrate cleanup AC1 returned no relevant documents.
- GitHub exact sweeps found #10822 and #10823, but no standalone AC1 inventory ticket.
- Local grep found the AC1 parent text in
resources/content/issues/issue-10822.md:99.
The Problem
The current config substrate mixes at least five env-var roles in one surface: secrets, runtime binding, identity/session binding, single-writer process role, and operator one-shot toggles. It also carries dev-branch-only aliases and config-key fallbacks that are scheduled for hard deletion under #10823.
Without an explicit inventory, follow-up PRs can accidentally delete boot-critical env reads too early, leave dead aliases behind, or move values into the wrong tier of the three-tier model. The audit is the dependency that turns KISS deletion into a controlled substrate change.
The Architectural Reality
Empirical starter scan on current dev:
rg "process\\.env\\.[A-Z0-9_]+|process\\.env\\[[^\\]]+\\]" ai/mcp/server finds reads in Memory Core, Knowledge Base, and shared server services.ai/mcp/server/shared/helpers/DeploymentConfig.mjs:23 resolves MCP_HTTP_PORT with legacy SSE_PORT.ai/mcp/server/shared/helpers/DeploymentConfig.mjs:67 and :89 resolve Chroma host/port with optional legacy env-var names.ai/mcp/server/memory-core/helpers/EmbeddingProviderConfig.mjs:12 resolves canonical and legacy embedding-provider inputs.ai/mcp/server/knowledge-base/config.template.mjs:141 still reads both NEO_MEMORY_DB_PATH and NEO_MEMORY_CORE_DB_PATH.ai/mcp/server/shared/services/TransportService.mjs:112 still reads bare HOST, which needs classification rather than blind deletion.
The target classification is defined by #10822: keep env vars only when they belong to secrets, runtime-binding, identity-binding, single-writer-process-role, multi-tenant-isolation, or operator-one-shot-toggle roles. Everything else should move to Tier 1 shared config or Tier 2 per-server config, or be deleted.
The Fix
Produce a markdown audit table, committed with the implementation PR, covering every env-var read under ai/mcp/server/**.
Required table columns:
| env var |
current readers |
target tier |
deletion/keep rationale |
The audit must distinguish canonical env vars from legacy aliases and must explicitly call out reads that are not direct process.env.NAME dot-access, such as indexed legacy env reads.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback / Edge Case |
Docs |
Evidence |
Env-var inventory for ai/mcp/server/** |
#10822 AC1 + operator KISS/v13 direction |
Complete markdown table classifying every env-var read into the target tier model |
If a read cannot be classified confidently, mark it needs-design with the owning file and rationale instead of guessing |
PR body links the table and summarizes keep/delete counts |
rg command output plus reviewed source paths |
| Alias deletion dependency |
#10822 AC2 + #10823 |
#10823 consumes the audit output before deleting aliases |
Deletion PR must not remove boot-critical vars before Phase 1.5 substrate is active per #10822 AC14 |
Cross-link from #10823 or PR body |
Audit table rows for each alias |
Acceptance Criteria
Out of Scope
- Deleting aliases or flattening resolvers. That belongs to #10823 and later #10822 AC12 work.
- Creating the Tier 1 shared config module.
- Implementing the boot-time validator.
- Operator-side
.env migration across harnesses.
Avoided Traps
- Blind deletion from grep output: env-var reads have different roles; some are secrets or runtime binding and should stay env-backed.
- Framework-style deprecation chains: the audit should not preserve aliases just because they exist; dev-branch-only aliases are not released-version compatibility.
- Moving secrets into config files: secrets remain env territory.
Related
- Parent: #10822
- Feeds: #10823
- Originating Discussion: #10819
- Origin A2A Message:
MESSAGE:ecb64615-491c-4a87-bd9d-b735bcd4a5d0
Handoff Retrieval Hints
query_raw_memories(query="config substrate cleanup KISS three-tier env-var audit")query_raw_memories(query="Phase 1 env var audit classify every process.env ai/mcp/server")- GitHub archaeological source: Discussion #10819 and Epic #10822
Context
Epic #10822 graduated Discussion #10819 into the config substrate cleanup track. Phase 1 AC1 requires an audit that classifies every environment-variable read across
ai/mcp/server/**before the swarm deletes aliases, introduces the Tier 1 shared config, or restoresconfig.mjsdelta-merge as the primary non-env extensibility path.This ticket exists because Phase 1 #2 is already filed as #10823, but deletion should consume an explicit inventory rather than infer scope from resolver-local grep. Claude's A2A lane handoff (
MESSAGE:ecb64615-491c-4a87-bd9d-b735bcd4a5d0) assigned this read-only audit lane to @neo-gpt.Duplicate sweep evidence:
duplicate ticket env-var audit classify config substrate cleanup AC1returned no relevant documents.resources/content/issues/issue-10822.md:99.The Problem
The current config substrate mixes at least five env-var roles in one surface: secrets, runtime binding, identity/session binding, single-writer process role, and operator one-shot toggles. It also carries dev-branch-only aliases and config-key fallbacks that are scheduled for hard deletion under #10823.
Without an explicit inventory, follow-up PRs can accidentally delete boot-critical env reads too early, leave dead aliases behind, or move values into the wrong tier of the three-tier model. The audit is the dependency that turns KISS deletion into a controlled substrate change.
The Architectural Reality
Empirical starter scan on current
dev:rg "process\\.env\\.[A-Z0-9_]+|process\\.env\\[[^\\]]+\\]" ai/mcp/serverfinds reads in Memory Core, Knowledge Base, and shared server services.ai/mcp/server/shared/helpers/DeploymentConfig.mjs:23resolvesMCP_HTTP_PORTwith legacySSE_PORT.ai/mcp/server/shared/helpers/DeploymentConfig.mjs:67and:89resolve Chroma host/port with optional legacy env-var names.ai/mcp/server/memory-core/helpers/EmbeddingProviderConfig.mjs:12resolves canonical and legacy embedding-provider inputs.ai/mcp/server/knowledge-base/config.template.mjs:141still reads bothNEO_MEMORY_DB_PATHandNEO_MEMORY_CORE_DB_PATH.ai/mcp/server/shared/services/TransportService.mjs:112still reads bareHOST, which needs classification rather than blind deletion.The target classification is defined by #10822: keep env vars only when they belong to secrets, runtime-binding, identity-binding, single-writer-process-role, multi-tenant-isolation, or operator-one-shot-toggle roles. Everything else should move to Tier 1 shared config or Tier 2 per-server config, or be deleted.
The Fix
Produce a markdown audit table, committed with the implementation PR, covering every env-var read under
ai/mcp/server/**.Required table columns:
The audit must distinguish canonical env vars from legacy aliases and must explicitly call out reads that are not direct
process.env.NAMEdot-access, such as indexed legacy env reads.Contract Ledger Matrix
ai/mcp/server/**needs-designwith the owning file and rationale instead of guessingrgcommand output plus reviewed source pathsAcceptance Criteria
process.env.*andprocess.env[...]read underai/mcp/server/**is represented in the table.Out of Scope
.envmigration across harnesses.Avoided Traps
Related
MESSAGE:ecb64615-491c-4a87-bd9d-b735bcd4a5d0Handoff Retrieval Hints
query_raw_memories(query="config substrate cleanup KISS three-tier env-var audit")query_raw_memories(query="Phase 1 env var audit classify every process.env ai/mcp/server")