msd-core/docs/adr/1411-resolution-provenance.md

Resolution must report provenance, not fall open silently

• Status: Accepted
• Date: 2026-06-17

Context

A verb resolves config (or a skill set, or a planning path) from the invoking cwd / MSD_WORKSTREAM / stored workstream pointer. When that ambient context is "off" — a descendant subdirectory with no .planning/, or a workstream with no scoped config — resolution silently falls open to bare defaults, the verb succeeds with empty output and no signal, and a downstream subagent plans or verifies without its configured context. The gap is invisible: output is still produced.

We have shipped the same fix-shape ≈11 times between April and June 2026 — anchor to the project root / fall back to the root config instead of defaults / bolt a diagnostic onto one verb. The recurrence is concentrated, not scattered:

• loadConfig is a 9-patch try/catch ladder (#315, #443, #910, #1683, #2517, #2714, #3023, #3024, #3523). Each "config fell to defaults" bug adds a branch, and the returned object is the same shape whether it found real config or bare defaults — so every caller that cares re-detects degradation by sniffing the contents.
• The agent-skills verb received this exact fix twice in two weeks: #1374/#1376 (the warnings[] field) and then #1366 (PR #1408).
• The diagnostic half is hand-rolled eight ways across seven files; the I/O Module's output() has no notion of a "degraded" result.
• The walk-up to the project root exists three-to-four times; PR #1408 adds a weaker fourth (resolvePlanningCwd) because the canonical findProjectRoot (Project-Root Resolution Module) skips the plain single-repo-descendant case.

The #1366 trigger

msd-tools query agent-skills <agent> resolved a configured agent's <agent_skills> block to empty with no diagnostic under two invocation-context drifts: (1) invoked from a descendant subdirectory with no .planning/, config fell through to bare defaults → agent_skills was {}; (2) MSD_WORKSTREAM pointed at a workstream with no scoped config → the same fall-through. In both cases the verb exited 0 and emitted an empty block, so a planner/checker subagent planned or verified without its configured skill/rule context, invisibly.

The generalizing precedent

ADR-227 established that input validation at a trust boundary must check semantic shape, not just type, and surface coercion rather than propagate a contractually-invalid value. This ADR is the analog for the resolution side of the same trust boundary: looking a value up from ambient context (cwd, env, a stored pointer) is itself a trust boundary, and silently substituting defaults when the lookup misses is the resolution-side equivalent of propagating a garbage value — the caller cannot tell a real answer from a degraded one. CONTEXT.md's Planning Path Projection Module already states the rule for the SDK path-projection seam — "invalid workspace context is a validation error at this seam rather than a silent fallback" — but the CJS loadConfig never adopted it.

Decision

Context resolution at a trust boundary — reading config, anchoring to a project root, resolving a workstream — MUST report its provenance. A resolver may fall back, but the fallback must be a visible value, not a silent substitution. Three sub-rules:

1. Deterministic anchoring. Resolve the project root through one walk-up module. Resolution MUST NOT depend on an arbitrary descendant cwd. The single owner is the Project-Root Resolution Module; ad-hoc walk-ups (e.g. resolvePlanningCwd) are retired into it.
2. Provenance, not a bare value. A resolver returns what it resolved and where it came from. Callers branch on the provenance field, never on the resolved contents, to detect degradation.
3. Visible degradation. A configured input that resolves empty MUST emit a diagnostic. "Not configured" and "configured-but-resolved-empty" MUST be distinguishable in the output contract.

Concretely, the principle binds three seams:

• Config Loader Module — loadConfig exposes a ConfigResolution { config, source: 'workstream' | 'root' | 'global-defaults' | 'builtin-defaults', degraded: boolean }. Introduced additively (loadConfigResolved) so the ~16 existing loadConfig call sites, SDK parity, and the generated .cjs are unaffected until they opt in.
• Project-Root Resolution Module — absorbs the nearest-.planning/ ancestor as a first-class heuristic; resolvePlanningCwd and any sibling walk-up are deleted.
• I/O Module — a shared Resolution<T> { value, configured, reason, warnings } envelope; output() carries degradation so the eight hand-rolled warnings[] shapes converge on one.

A configured input that resolves empty without a reason is a CI-guarded regression (grandfather burn-down, mirroring the no-adhoc-markdown-parsing rule).

Consequences

Bug classes avoided

• Silent context drop — a planner/checker subagent planning or verifying without its configured skills (the #1366 / #1374 class).
• N callers re-sniffing — every consumer re-deriving "did this fall open?" from config contents instead of reading one field.
• Walk-up drift — a fourth or fifth project-root resolver diverging from the canonical one.

Cost

• loadConfig's result type grows — mitigated by the additive loadConfigResolved; callers migrate incrementally.
• One envelope to learn; ~18 verbs migrate onto it across phases P3–P4.

Tradeoff

As in ADR-227, resolution may still fall back to preserve continuity — a missing workstream config should not abort the verb. The difference is that the fallback is now a visible value plus an opt-in warning, never a silent success. Fields where a miss is genuinely fatal may throw; that is a per-call decision, not the general rule.

Alternatives considered

Per-verb patching (status quo)

Rejected. The same fix-shape regenerated ≈11 times because each patch fixed one call site without changing the policy that the resolver fails open and hides which branch fired.

Throw on a resolution miss

Rejected, for ADR-227's reason: throwing breaks pipeline continuity. A missing workstream config must not abort query agent-skills. Visible provenance preserves continuity and visibility.

Deterministic anchoring only (no provenance)

Rejected. Fixing cwd/workstream drift removes the most common trigger but leaves callers re-sniffing contents and the diagnostic hand-rolled per verb — the bug class would keep regenerating at the next new consumer.

Related

• Epic: #1411 (Resolution Provenance) · This ADR (P0): #1412
• Supersedes the tactical fix in PR #1408 (closed) — its resolvePlanningCwd and local AgentSkillsReason/AgentSkillsDiagnostics are redelivered through the seams above in P1–P3.
• Builds on: ADR-227 (input validation shape), ADR-0004 (Planning Workspace Module), ADR-0006 (Planning Path Projection Module).
• Prior recurrences of this class: #1374/#1376, #1683, #991, #2714, #2638, #3523, #2652, #2791, #2555, #2623, #3196.

Amendment — 2026-06-18: P3 narrowed (the shared envelope is not a real seam)

The original P3 plan was a single Resolution<T> { value, configured, reason, warnings } envelope adopted by agent-skills, capability-state, and capability-writer. An adversarial fit-analysis showed this fails the deletion test: configured/reason are meaningless for the capability read/mutation verbs, and capability-writer's errors[] (operation-not-applied) is load-bearing and cannot fold into warnings[] (advisory). The only genuinely shared seam across the three is warnings: string[].

P3 is therefore narrowed to an honest convention rather than a forced generic:

• Resolution<T> { value, configured, reason, warnings } (src/resolution.cts) is the canonical shape for config-interpreting read verbs. agent-skills is the first adopter — the value field is added additively to its --json IR with the flat fields retained for back-compat; source/degraded remain config-provenance extras.
• Capability verbs keep their existing shapes, named explicitly: read = { runtimeConfigDir, capabilities, warnings? }; mutation = { capabilities, warnings, errors }.
• The shared contract is documented, not forced: read verbs expose warnings[]; mutation verbs expose warnings[] + errors[]; configured/reason appear only on config-interpreting read verbs.

Recurrence prevention does not depend on a shared envelope — it is delivered by P4's CI guard (a configured input resolving empty must carry a reason). (#1416)

Amendment — 2026-07-26: corrupt is not absent

This ADR reasons exclusively about a resolution miss — ambient context is "off", the lookup finds nothing, resolution falls open to defaults. It is silent on the adjacent case: input that is present but not usable. That silence is why five engine read paths (#1879) could fold an unusable input into the very value that means "genuinely absent" without contradicting an Accepted ADR.

The failure detection differs per site and is not one mechanism — naming them precisely, because the fix differs with them:

Site	How "not usable" is detected
config-loader.cts (#1880)	SyntaxError from JSON.parse, or an errno (EACCES) re-thrown by platformReadSync
roadmap-parser.cts (#1881)	errno only — the parse is regex over text and cannot throw
frontmatter.cts (#1882)	neither — no I/O and no throw site; an opening --- with no closing fence is a structural check the function must make for itself
planning-workspace.cts / verify.cts (#1883)	errno from readdirSync (EACCES/EIO)
planning-workspace.cts (#1884)	an errno that was swallowed, then misclassified as a different condition

What the two governing ADRs actually permit

Read together rather than selectively, ADR-1411 and ADR-227 converge, and they do not license throwing as a cluster-wide answer:

• ADR-227's Decision requires malformed input to be "silently coerced to the contract's safe default … It MUST NOT be propagated. Throw only if the surrounding codebase treats throws as a normal-flow signal (it usually does not …)", and its rejection of throwing carves out only fields where a value is "genuinely fatal (not just malformed) … a per-field decision, not the general rule." Malformed is explicitly on the coerce side of that line.
• This ADR's own Decision says: "A resolver may fall back, but the fallback must be a visible value, not a silent substitution."

The gap in the five sites is therefore not that they fall back. It is that they fall back invisibly. Continuity is correct and stays; the silence is the defect.

The pattern — keep the fallback, make it visible

Both mechanisms below preserve every current return value. Neither changes a return type, so no caller that treats "absent" and "unusable" identically breaks.

• In-band, where the result already carries provenance. A read whose result is a provenance envelope names the cause in that envelope. loadConfigResolved's ConfigResolution { config, source, degraded } is the first adopter (#1880): genuine absence keeps degraded:false; an unusable config sets degraded:true and adds a reason. Resolution<T> (src/resolution.cts) has no value for this case today — its documented vocabulary is resolved / not_configured / configured_empty / configured_unresolved, all of which describe a miss. #1880 introduces the unusable-input values and is responsible for documenting them alongside the existing four.

• Out-of-band, where the return is a bare value that cannot carry provenance. A read that returns a bare sentinel or a plausible default keeps returning exactly that, and emits a deduplicated stderr diagnostic naming the file and the errno. This covers getRoadmapPhaseInternal (#1881), findContextMdIn / listMilestoneArchiveDirs (#1883), getMilestoneInfo (#1881) — whose fallback is a populated { version: 'v1.0', name: 'milestone' } rather than an empty sentinel, and a plausible-looking default is more in need of a diagnostic than an empty one, not less — and extractFrontmatter (#1882), which returns {}. The repo's existing seam is config-loader.cts's _warnedUnknownConfigKeys guard around process.stderr.write.

  This is unconditional, and that is a deliberate divergence from ADR-227. ADR-227's Tradeoff proposes mitigating silent coercion with "an opt-in debug log (process.env.MSD_DEBUG)"; that env var has never been implemented, and an opt-in nobody sets is indistinguishable from the silence #1879 is about. This ADR's own Decision is the stronger rule and the one that governs here — degradation must be visible, not discoverable-on-request. The _warnedUnknownConfigKeys precedent is likewise unconditional. Appliers follow this ADR, not ADR-227's tradeoff, on that point.

  Dedup key. Key the guard on the resolved absolute path plus the errno, not on the message text or the bare errno. Keying too coarsely suppresses a genuine second failure in a different file; keying on prose couples the guard to wording.

Throwing is not the cluster's answer. It remains available only under ADR-227's genuinely-fatal carve-out, decided per call and justified in that PR — never inferred from the return shape. withPlanningLock (#1884) is the one site that qualifies, and it already throws; its defect is that it throws the wrong error after swallowing the real one.

Detection, not propagation, where there is no exception. #1882 takes the out-of-band mechanism above like its siblings — the difference is only in how the condition is found. extractFrontmatter takes a string, does no I/O, and has no throw site, so there is nothing to catch: an opening --- with no closing fence is a structural check the function must make for itself, and having made it, it distinguishes malformed-truncated from well-formed-and-empty and emits the same deduplicated diagnostic. The check has to be written; the signal shape is not a new one.

Wiring clause. A reason that exists only inside an envelope no caller reads is not a delivered signal — it is an unreachable field. An in-band adopter MUST also expose the cause on the surface its callers actually use. loadConfig, the thin wrapper over loadConfigResolved, returns .config alone to roughly thirty call sites; adding reason to the envelope without a diagnostic on that path leaves every one of them exactly as blind as before.

Caller audit is mandatory per applier. Implemented as specified, neither mechanism can break a caller — no return type changes. The audit exists to prove the applier did implement it as specified, which is a different claim. The concrete hazard: src/state.cts carries a comment recording that a defensive try/catch around getMilestoneInfo was deliberately removed under the #2245 audit because that function "never throws". An applier who reaches for a throw here — the intuitive fix, and the one this amendment rules out — silently breaks that invariant. Each applying PR records its caller audit for that reason.

CI ratchet. scripts/lint-resolution-provenance.cjs's REGISTRY currently holds one verb (agent-skills). The config-loader seam is not registered, so nothing today would catch a regression of #1880's contract. #1880 registers it.

Test methodology. Assert the typed surface, not the diagnostic prose — CONTRIBUTING.md's Prohibited: Raw Text Matching on Test Outputs applies to stderr as much as to stdout, and tests/roadmap-parser.test.cjs already states the local convention for this call surface. Where the mechanism's only observable is a diagnostic, the applier exposes the typed surface (a frozen reason enum, or the dedup set) and asserts on that.

First appliers: #1880 (in-band), #1881 / #1882 / #1883 (out-of-band), #1884 (genuinely-fatal carve-out, already throwing) — epic #1879, Phase 0 = #2674.

Amendment — 2026-09-17: per-key provenance, and one encoder at the CLI boundary

This ADR's ConfigResolution { config, source, degraded, reason } is whole-config provenance: it says which layer supplied the object, and says nothing about where any individual key inside that object came from after merging. Epic #4633 is the bill for that silence. Four confirmed-bug issues (all four closed as duplicates of the epic on 2026-09-11) divide into two halves of one pipeline — resolve a value across layers, then hand it to a caller — and both halves are implemented more than once, so a consumer that needs the producing layer either re-derives it from contents (which this ADR's Decision 2 forbids) or discards it.

This amendment is the design lock for that epic (Phase 0 = #4671). It changes no code. It fixes the owner, the result type, the family boundaries, the encoding contract and the child boundaries so that the implementation children can be reviewed against a written contract rather than against each other. It stays in this file rather than opening a second ADR because per-key provenance is the same decision as Decision 2 applied one level down — a separate ADR would split ownership of one rule.

What is actually live on next

Measured on next at c9a5cc3e1, in a hermetic fixture (HOME redirected, .planning/config.json authored per case), not inferred from the issue text. The epic's own framing is corrected in two places, and the corrections make the seam argument stronger, not weaker.

Absorbed	Claim	Measured on next
#4071	~/.msd/defaults.json is dropped wholesale when a project config exists	Live. With a project config, research:false / model_profile:"quality" from the global file do not survive (research:true, model_profile:"balanced"); the file is only read by Branch D, which requires no .planning/ at all. _warnShadowedGlobalDefaults (#3532) prints that this happened — the defect is announced, not fixed
#4090	The evaluator discards which layer produced worktree.baseRef	Live. resolveEffectiveBaseRef returns string | null. A user/global head reaches evaluateWorktreeBaseDegrade as the bare string "head", indistinguishable from a project-local one
#4262	config-get --default emits a JSON string, not the JSON value	Live. --default '[]' → "[]", --default 5 → "5", --default true → "true", --default null → "null"
#4382	config-get without --raw double-encodes an already-JSON value	Not reproducible as stated. A present array emits a real JSON array, not a string containing JSON text. #4382's own reproduction uses --default, so it reports the same defect as #4262 from the consumer side. There is one encoding defect, on the --default arm only

Two further facts the epic does not state, both of which constrain the design:

• --default is already correct under --raw. --raw --default '[]' prints [] and --raw --default 5 prints 5, because the raw arm emits the argv string verbatim. The disagreement is confined to the JSON arm, where the same argv string is JSON-encoded as a string. This is why the remedy is a parser at the boundary and not a change to output().
• --raw cannot round-trip today, for present values, by construction. output()'s raw arm is String(value). Measured: [] → the empty string, [{path,depth}] → [object Object], ["codex","gemini"] → codex,gemini, 200000 → 200000 (indistinguishable from "200000"), project_code:"007" → 007 (decodes back as the number 7). See Decision 4.

Decision 1 — one resolution owner, and it returns the producing layer

A new leaf module, the Config Value Resolution Module (src/config-value-resolver.cts), owns per-key precedence for every configuration family. It is a new module rather than a function grafted onto config-loader.cts because the two answer different questions with different return types — "assemble the effective config object" versus "resolve one key and say which layer produced it" — and because the anti-divergence rule of Decision 5 needs a boundary it can name.

type ConfigLayer =
  | 'workstream' | 'root' | 'global-defaults' | 'schema-default' | 'builtin-default'  // family A
  | 'runtime-local' | 'runtime-shared' | 'runtime-user';                               // family B

interface ConfigValueResolution {
  found: boolean;
  value: unknown;                 // `undefined` if and only if `found === false`
  layer: ConfigLayer | null;      // `null` if and only if `found === false`
  reason: ConfigReason;           // config-loader's frozen CONFIG_REASON — not a second vocabulary
  composite?: Readonly<Record<string, ConfigLayer>>;  // per-leaf layer; present only for merged keys
}

function resolveConfigValue(key: string, opts: { cwd: string; family?: ConfigFamily }): ConfigValueResolution;

• Absence is { found:false, value:undefined, layer:null, reason:'not_configured' }. It is never represented by a falsy value, because a falsy value is a legitimate answer (below).
• Unusable input reuses CONFIG_REASON.CONFIG_UNPARSEABLE / CONFIG_UNREADABLE and the deduplicated diagnostic introduced by the 2026-07-26 amendment. A corrupt layer does not silently become an absent one, and the resolver introduces no new reason vocabulary — CONFIG_REASON is already frozen, and tests/config-loader.test.cjs already pins its values as the wire contract.
• Layer-file access belongs to this boundary. The resolver obtains each layer from config-loader.cts's existing per-layer read (_readConfigFile, promoted to an internal export), so "who may open a config layer file" and "who may decide precedence" are the same two modules. Every other module becomes a reader of a resolution, never a participant in one.
• Traversal is own-property only. Dotted paths walk with Object.prototype.hasOwnProperty.call, as cmdConfigGet already does, so __proto__ / constructor resolve as absent rather than to inherited values.
• Key eligibility is preserved, not widened. The resolver honours the existing VALID_CONFIG_KEYS / DYNAMIC_KEY_PATTERNS / federated-schema eligibility exactly as today. The epic's non-goals forbid expanding GLOBAL_DEFAULTS_RESOLUTION_KEYS or revisiting the loadConfig whitelist, and this amendment does neither.

loadConfig / loadConfigResolved keep their callers (the epic counts 45 direct call sites) and their shape. The owner is additive at introduction; adoption and deletion are Decision 5's job.

Decision 2 — two families, declared separately, with no invented precedence between them

The epic speaks of "layers" as though there were one ladder. There are two, they are read from different files by different code for different consumers, and merging their orderings would invent a precedence nobody decided.

Family	Layers (highest first)	Read from
A — MSD project configuration	workstream → root → global-defaults → schema-default → builtin-default	planningDir(cwd)/config.json, planningRoot(cwd)/config.json, ~/.msd/defaults.json, federated/capability configSchema default, CONFIG_DEFAULTS
B — runtime harness settings	runtime-local → runtime-shared → runtime-user	<cwd>/.claude/settings.local.json, <cwd>/.claude/settings.json, <userClaudeDir>/settings.json

A key belongs to exactly one family, declared in one table in the resolver. worktree.baseRef is family B despite its dotted, MSD-looking name — the value #4090 is about never appears in .planning/config.json. No ordering is declared between A and B; a caller that needs both asks twice and composes the answer itself, visibly.

Normalization. normalizeLegacyKeys runs per layer, before precedence, exactly where config-loader runs it today. Family B parses with parseJsonc, as resolveEffectiveBaseRef does. Normalization never crosses layers and never rewrites a file — the resolver is a read path and passes persist:false semantics all the way down.

Explicitly falsy values are configured values. false, 0, "", [], {} and a JSON null present in a layer all resolve found:true with that value and that layer. Only a key absent from every layer is found:false. This makes #4071's mechanism unrepresentable only when every key is correctly classified into its resolution family: a bad declaration can reintroduce the failure as a classification defect. Today's _globalBaseCfg uses ?? and || against 26 named keys, so a global false or 0 survives one branch and not another, and "is this key set?" is answered by the truthiness of its value in four different places.

Composite values. Some keys are objects assembled from more than one layer (effort, model_overrides, agent_tools, agent_skills). Merge-eligibility is declared per key in the resolver, not decided at a call site by whether a file happens to exist — which is precisely #4071's mechanism, where the existence of any project config suppresses the whole global file. For a declared-merge key:

• layer names the highest layer that contributed at least one leaf;
• composite maps each leaf key to the layer that produced it, at whatever depth the declaration says the merge is deep (effort.agent_overrides and effort.routing_tier_defaults are per-key deep today, per #3531 — that behaviour is preserved and becomes a declaration);
• a consumer that branches on origin reads composite[leaf]. It never re-derives provenance by re-reading a layer file, which is this ADR's Decision 2 restated for leaves.

Every other key replaces: the highest layer that has it wins outright.

Decision 3 — one parser and one encoder own the CLI boundary

cmdConfigSet already contains the only value parser at the config CLI boundary: true/false → boolean, null → JSON null, a finite Number(val) → number, a leading [/{ → JSON.parse with fall-through to string, everything else → string. It is extracted verbatim as parseConfigArgValue(raw: string): unknown and shared, unchanged, with config-get --default. Extracted, not copied — a second copy would be the defect this epic exists to close.

• null parses to the value null. Unsetting is a setter action, not a parse result. The two are conflated today only because cmdConfigSet happens to branch on parsedValue === null after parsing. That branch stays in the setter, where it is a documented "clear" action (#2046). The getter's --default null must emit JSON null and unset nothing. Any child that moves the unset decision into the parser has broken this contract.
• Per-key setter policy stays in the setter. project_code re-reading val verbatim so "007" does not collapse to 7, and every assertEnumValue / range validator, are setter key policies. The shared parser is type-directed only.
• One encoder. encodeConfigValue(value, { raw }) is the single emission path for every arm of cmdConfigGet: present key, root-inherited key (#2702), --default, schema default (#2256), and the masked-secret arm. Today those arms reach output() through two different helpers, and the --default one hands it a value of the wrong type.
• Masking stays ahead of encoding. isSecretKey(kp) → maskSecret(value) → encoder. The mask yields a string and is encoded as one; the encoder never sees the plaintext. emitResolvedDefault already established this for the schema-default arm and it becomes the rule for all of them.
• Both consumer kinds are audited by the children, not assumed. Structured consumers: msd-core/workflows/code-review.md (workflow.code_review_depth_overrides --default '[]'), ship.md (ship.pr_body_sections --default '[]'), plan-review-convergence.md (review.default_reviewers), pr-branch.md (planning.sub_repos). Shell-string consumers: src/review-lane-invocation.cts's configString(), which treats the literal four characters null as "unset" — a live contract on raw output — and the config-get … --raw command strings that src/runtime-artifact-conversion.cts bakes into generated runtime artifacts.

Decision 4 — the round-trip property is asserted in JSON mode; raw output is frozen (ruled 2026-09-20)

The epic asks for decode(encode(v)) === v "across --raw / --default / neither". Measured, that property cannot hold in raw mode while raw means String(value): [] and "" both print empty, [{…}] prints [object Object], and 5 and "5" are the same three bytes. The epic's requirement is therefore split rather than silently weakened:

1. JSON mode (no --raw) — the property holds for every supported type and every layer, including the --default and schema-default arms once they route through the parser. This is the property test the epic asks for, and the cell it is currently red in is --default.
2. Raw mode — the contract is a display and shell-interpolation contract, and it is frozen. String(value) rendering is preserved byte-for-byte and pinned by tests. Raw makes no round-trip claim, including for scalars: 5 and "5" collide, and "007" can be decoded as the number 7.

Making raw lossless — emitting compact JSON for non-scalars, say — is a user-visible output-contract change to a surface that live consumers parse by hand (configString() above; four workflow call sites; baked artifact command strings). It is out of scope for #4633, and needs its own issue and its own approval. No child may change raw's non-scalar rendering "while it is in there".

Ruled: freeze --raw as the display/shell-interpolation contract described above. A lossless --raw would need its own issue before any child that touches raw output is planned; none is filed.

Decision 5 — migration census, child boundaries, and the anti-divergence guard

Census. Every site that reads a configuration layer file directly or re-implements precedence, found by path-construction search over src/, bin/, hooks/, scripts/ at c9a5cc3e1.

Precedence implementations to delete or reduce to delegation:

Site	What it re-implements
src/capability-activation.cts resolveConfigKey	A full four-level walk (loadConfig result → workstream file → root file → schema default) returning {found, value} with no layer. The closest thing to the epic's owner that already exists, and the reason the owner must absorb these rather than become another walk beside them
src/config.cts resolveFromRootConfig + resolveSchemaDefault	cmdConfigGet's own workstream→root→schema cascade (#2702, #2256)
src/config-loader.cts _globalBaseCfg (Branch D)	The 26-key ?? / || projection of ~/.msd/defaults.json — #4071's site
src/config.cts buildNewProjectConfig	A project-creation merge of ~/.msd/defaults.json
src/install-model-override-resolver.cts	Install-time global+project merges (model_overrides, agent_tools, runtime/profile)
src/install-effort-resolver.cts	Install-time effort merge, deep per sub-field
src/worktree-base-ref.cts resolveEffectiveBaseRef	Family B's three-layer cascade, returning a bare string | null — #4090's site
src/model-resolver.cts projectExplicitlySetsOmit	A workstream→root two-layer walk over config.json for resolve_model_ids, re-implementing loadConfig's precedence order by hand specifically to avoid its normalization side effects

Single-layer readers that bypass precedence entirely (each reads one file and therefore silently ignores root inheritance, global defaults and schema defaults): src/estimate-cli.cts (workflow.smart_zone_tokens), src/gap-checker.cts (workflow.post_planning_gaps), src/check-command-router.cts (readWorkflowConfig), src/runtime-slash.cts (runtime), src/verify.cts (workflow.drift_threshold), src/phase.cts (workflow.auto_prune_state), hooks/msd-agent-isolation-guard.js and hooks/msd-cursor-subagent-start.js (both read ~/.msd/defaults.json directly), src/init.cts's readConfigJsonBoolean/readConfigJsonValue (single-layer reads of the workstream-aware planning dir only — no root fallback, no schema default). runtime-slash.cts records its reason for bypassing loadConfig — the normalize-and-write-back side effect — and that reason expired when persist:false shipped (#3648); a child adopting the owner there must delete the stale comment with the code.

Excluded, with reasons: src/config.cts setters, src/capability-writer.cts's pre-write parse check and src/planning-snapshot.cts's snapshot field are writes and probes, not resolutions; hooks/msd-config-reload.js and hooks/msd-context-monitor.js watch the file for change detection and display. None of them may grow a merge or a precedence branch; the guard below still watches them.

Child boundaries. Each is its own issue, opened and approved separately — this Phase-0 child's type: chore authorizes none of them.

Child	Scope	Epic criterion it closes
C1	Introduce the owner: module, typed result, family declarations, fast-check layer × type matrix over (absent/present) × (array, object, number, boolean, string, null) asserting value and layer; register the verb in scripts/lint-resolution-provenance.cjs's REGISTRY. No call sites change	"resolver's return type carries the producing layer"; "layer × type matrix"
C2	The encoding boundary: extract parseConfigArgValue, share it with --default, route every cmdConfigGet arm through one encoder, freeze raw. Failing-first regressions for #4262 and #4382	"one encoder owns --raw / --default / default output"; "encoder round-trip property"; "/msd-code-review runs in a project that has set no config keys at all"
C3	Family A adoption + deletion: the six family-A precedence implementations above reduced to delegation or deleted, then the single-layer readers. Failing-first regression for #4071	"one implementation of layer precedence; the other merge paths deleted"
C4	Family B adoption: resolveEffectiveBaseRef returns a resolution, evaluateWorktreeBaseDegrade branches on layer instead of on the bare value. Failing-first regression for #4090	"consumers that branch on it read it rather than re-infer it"
C5	The ratchet: local/no-adhoc-config-merge, allowlist drained to empty, and a deliberately reintroduced copy demonstrated going red	"local/no-adhoc-config-merge runs with an empty allowlist"

The epic's remaining criterion — a failing-first regression per absorbed issue — is carried by the child that owns each symptom: #4262 and #4382 in C2, #4071 in C3, #4090 in C4. Each writes the test first, watches it fail on the unfixed tree, and says so in its PR.

The guard (eslint-rules/no-adhoc-config-merge.cjs). Follows the no-adhoc-markdown-parsing / no-unconfined-path-join pattern already in the tree: a rule plus a JSON allowlist validated by scripts/lib/allowlist-ratchet.cjs, which fails on stale entries so the list can only shrink. It flags two shapes: (a) constructing a layer-file path — path.join(…, '.msd', 'defaults.json'), path.join(planningDir(…)|planningRoot(…), 'config.json'), path.join(…, '.claude', 'settings*.json') — outside the resolver boundary; (b) spread-merging two parsed config objects.

Two exemption kinds, kept apart in the file and not interchangeable:

• Resolver-internal, permanent: src/config-value-resolver.cts and src/config-loader.cts are the boundary and are exempt by construction.
• Temporary migration, each carrying its adopting child's issue number, each removed by that child. C5 lands only when the temporary section is empty. Write and probe sites (the exclusions above) are exempted by rule shape — they parse or stat without merging, so they never match — rather than by allowlist entry, so the list is not padded with entries that can never drain.

Validation. Hermetic fixtures with a redirected HOME and an authored .planning/ tree, plus the real published entry points (msd-core/bin/msd-tools.cjs, bin/install.js — the installer already imports both install-time resolvers), never a mocked CLI. C5 additionally demonstrates the guard failing: reintroduce one deleted merge, watch the rule go red, remove it again. A guard that has never been observed red is an assumption.

The #4588 boundary, restated

#4588 separately investigates what a current Claude Code harness actually honours when it forks a worktree. This amendment delivers provenance — the evaluator will know that a head came from the user/global layer. It does not assert what the harness does with that fact. C4 preserves today's isolationMode semantics (#3659, #48) unless #4588 changes them; if #4588's finding and the epic's expected evaluator behaviour conflict, that is resolved with the maintainer before C4 locks an assertion, not inside C4.

Limits of this amendment

• No runtime code, configuration behaviour or generated artifact changes here. Every symptom in #4071, #4090, #4262 and #4382 stays live until C2–C4 land.
• The child issues do not exist yet; C1–C5 are proposed boundaries, and each needs its own approval.
• Decision 4 freezes raw output (ruled 2026-09-20). A lossless raw mode would reverse a decision recorded here and needs its own issue before C2 is planned.