docs/governance: consumer-config layering has no Convention registry row — 11 of 15 surfaces diverge from the seam-2 precedence rule

[kyle-sexton]

Scope: repo governance (docs/) · Source: read-only fleet census of consumer-tracked config surfaces

Problem

docs/MIGRATION-PLAYBOOK.md:234-237 fixes the resolution order for every tracked consumer-config surface:

Resolve user-global → team (project) → local overlay, additive-preferred: a later layer adds to or refines earlier layers rather than silently replacing them. The first-party precedent concatenates; a plugin that genuinely must override does so per key, never by dropping the base layer wholesale.

docs/PLUGIN-PHILOSOPHY.md:257 states how conformance is enforced:

Fleet audits check conformance per row.

Per row — and this rule has no row. The Convention registry (docs/PLUGIN-PHILOSOPHY.md:260-274) has eleven rows; none covers consumer-config layering or precedence. No row means no fleet audit, and the result is measurable drift.

Evidence — 15 consumer-tracked config surfaces

Conformance	Surfaces
Conforms	toolchain ecosystems (reference/resolution-ladder.md:31-35 — per-key additive, exact), codebase-health, autonomy (extends with an org layer), disk-hygiene (plus a documented --policy replace branch)
Declared deviation	standards — docs/conventions/standards/README.md:35-39 documents a deliberate inversion (personal layers may add or tighten; team wins a direct conflict) with provenance reporting
Undeclared deviation	code-tidying (skills/tidy/lanes/docs-prose.md:14 — a project lane "overrides this file entirely"), songwriting (first-match-wins, freezes the template) — wholesale replacement, which the seam forbids, with no deviation record
Single-layer — no user-global, no local overlay	8 surfaces including source-control, topic-docs, standards.yaml, repo-fleet-hygiene, ai-briefing, work-items (×2), out-of-scope
Precedence undocumented	3 surfaces — a direct violation of docs/PLUGIN-PHILOSOPHY.md:191-194 ("document precedence")

Further divergence across the same 15: four different .local.* gitignore spellings, five different formats for a schema/version pin, and three distinct idioms for an enable/disable toggle. No cross-cutting document enumerates these surfaces — a grep across README.md, CLAUDE.md, AGENTS.md, and docs/ found no fleet-level index.

Scope

1. New owner doc carrying the cross-concern layering axis only: layer set and paths, precedence order, .local.* naming, the recommended consumer .gitignore line, and the runtime resolution algorithm. Follows the canonical config-contract shape (template: docs/conventions/hook-telemetry/) — README.md + CHANGELOG.md, a ## Versioning section delegating the number to the CHANGELOG, and an implementers table.
2. Registry row in docs/PLUGIN-PHILOSOPHY.md, so fleet audits gain a row to check.
3. docs/MIGRATION-PLAYBOOK.md seam 2 points at the owner doc for the layering rules rather than restating them (melodic-software/standards conventions/engineering/reference-dont-duplicate.md:3).
4. Record observed deviations as observed — standards' declared inversion and the two undeclared wholesale-replace cases go in the doc's deviations section as findings. Ratifying them is explicitly out of scope here (see the linked decision issue) so this work stays mechanical.
5. Implementers table naming each of the 15 surfaces and its current conformance state, so the gap is tracked rather than the doctrine pretending it is closed — the idiom already used at docs/PLUGIN-PHILOSOPHY.md:203-204.

Deliberate boundary

The owner doc governs layering and precedence only — not keys, not schema. Per-concern schema stays in docs/conventions/<concern>/ per docs/MIGRATION-PLAYBOOK.md:209-217. A doc owning schema too would collide with "One owner doc per shared concern" (docs/PLUGIN-PHILOSOPHY.md:256); one owning only the cross-cutting axis does not.

Out of scope

• Ratifying or correcting the three deviations — separate decision issue, human-gated.
• Migrating the eight single-layer surfaces. Each is its own PR against its own plugin; source-control is the first and is filed separately.
• Schema enforcement in CI. Five schemas exist in this repo and are validated by nothing at runtime or in CI (ecosystem.schema.json, topic-docs.schema.json, standards.schema.json, the autonomy guardrails security binding schema, and disk-hygiene's closed key set). Worth its own issue.

Constraints

• AGENTS.md and REVIEW.md are upstream-managed by melodic-software/standards (distribution/sync-manifest.yml:171-184) — read-only here, and no inbound link to the new doc may be added from either. docs/ is not managed.
• Config-contract owner docs name neighbours in backticks rather than relative links; docs/conventions/ecosystem-commands/ is the lone exception.

Related

• docs/governance: rule needed on three consumer-config layering deviations (standards inversion, code-tidying + songwriting wholesale replace) #649 — the deviation rulings deliberately excluded from this scope
• source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647 — first per-plugin conformance migration (source-control); ships independently of this issue
• toolchain: publisher org/repo/branch URL propagates into consumer-tracked .claude/ecosystems/*.yaml headers #410, verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423, planning: branch-name grammar hardcoded to Conventional Commits types, no consumer seam #415 — symptoms of the same missing registry row