[FEATURE] Define precedence when CLAUDE.local.md conflicts with project CLAUDE.md instead of arbitrary selection

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This request does NOT contain sensitive information

Problem

CLAUDE.local.md is offered as a layer above project CLAUDE.md, and the scope table in the memory docs orders the layers managed → user → project → local. But the layering carries no resolution rule when two layers state contradicting things:

If two rules contradict each other, Claude may pick one arbitrarily.

All discovered files are concatenated into context rather than overriding each other.

It loads alongside CLAUDE.md and is treated the same way.

So a correction written in CLAUDE.local.md sits beside the text it corrects rather than superseding it, and which one Claude uses is undefined.

Settings files use the same layer names with defined precedence — "user → project → local, later overrides earlier." One hierarchy resolves deterministically; the parallel one, with the same layer vocabulary, does not. Hierarchical permission systems generally resolve this the same way settings do: the nearest / most-specific layer wins, predictably.

Use Case

A repo in heavy early development. The checked-in CLAUDE.md holds genuinely useful standing directives — conventions, workflows, commands — that stay valid. Its description of repo shape goes stale within days as services are added and tooling changes. Both kinds of content live in one team-owned file, and they age at completely different rates.

Onboarding is where this bites hardest. I hit this while getting oriented in an unfamiliar repo. The checked-in CLAUDE.md described an area of the codebase as not yet built; on disk, entire subfolder trees were already there. A new developer reading that file to build a mental model gets a wrong one, with no basis to suspect it — and Claude, reading the same file, states the same wrong thing confidently. The artifact meant to accelerate orientation actively misdirects it, and the assistant reinforces rather than corrects, because it treats the stale description as equal in standing to a local correction.

CLAUDE.local.md is the natural place to correct just the stale parts, and that is exactly what it's being used for. It doesn't reliably work, because the correction doesn't outrank what it corrects. In one session this produced a concrete failure: a command form that no longer exists in the installed build was taken from the checked-in file while the correct form sat in CLAUDE.local.md, in the same context.

Worth pre-empting the obvious answer — "just fix the shared file." That isn't available here:

• It's team-owned and version-controlled. Rewriting shared project instructions isn't a change an individual contributor makes unilaterally; it goes through the team like any other shared asset. Someone still finding their way around the repo is the least well-placed person to be authoring its canonical description.
• Even with sign-off, the shape sections would need re-editing continuously while the repo churns — the churn rate is the whole problem, and it doesn't slow down because one person fixed one section. A per-developer override layer is the right shape for that, which is what CLAUDE.local.md appears to be for.

Existing options don't cover it:

• claudeMdExcludes is all-or-nothing. Dropping the file to escape the stale shape also discards the directives that are correct and useful.
• Mirroring the shared file into CLAUDE.local.md forks it, so later upstream edits are silently missed — the failure mode the shared file exists to prevent.

Proposed Solution

In rough order of preference:

1. Defined precedence for directly conflicting content — nearest layer wins, matching settings-file semantics and the existing scope ordering.
2. A way to mark a local section as authoritative over the same topic in a lower layer — e.g. frontmatter naming a superseded heading — for cases where whole-file precedence is too blunt.
3. Failing either, make it explicit in the docs that CLAUDE.local.md does not override and should not be relied on to correct a stale shared file, so users pick a different strategy instead of a silently unreliable one.

Option 3 alone would be a real improvement: the current docs describe the layer hierarchy and the arbitrary-pick behavior in separate places, and the natural reading of "local instructions" is that they take precedence locally.

Additional Context

Surfaced while investigating a separate model-behavior report. The docs are clear that CLAUDE.md is context rather than enforced configuration, and that hooks are the enforcement mechanism — that's understood and not what this asks about. The request is narrower: when two loaded memory layers conflict, make the winner deterministic rather than arbitrary.