docs/governance: rule needed on three consumer-config layering deviations (standards inversion, code-tidying + songwriting wholesale replace)

[kyle-sexton]

Scope: repo governance · Requires: a maintainer judgment call — not autonomously resolvable

Decision needed

docs/MIGRATION-PLAYBOOK.md:234-237 requires additive-preferred layering: "a later layer adds to or refines earlier layers rather than silently replacing them… a plugin that genuinely must override does so per key, never by dropping the base layer wholesale."

Three fleet surfaces deviate. Each needs a ruling: ratify as a declared exception, or correct to conform.

1. standards — precedence inversion (declared, reasoned)

docs/conventions/standards/README.md:35-39:

Precedence inversion: layers are additive. Personal layers (user-global and overlay) may ADD new standards or TIGHTEN team ones; on a direct conflict, the team-tracked layer wins. When a personal-layer rule materially shapes a skill's output, the skill names the contributing layer (provenance), so reviewers can tell a team standard from a personal one.

Every other multi-layer surface lets the later (more personal) layer win. This one deliberately inverts so a personal file cannot loosen a team standard.

Reads as defensible — a standards floor should not be personally weakenable, and it is documented with provenance reporting. The question is whether it becomes a named exception class in the convention ("policy-floor surfaces invert") or stays a one-off.

2. code-tidying — wholesale replacement (undeclared)

plugins/code-tidying/skills/tidy/lanes/docs-prose.md:14:

a project lane at .claude/tidy-lanes/docs-prose.md overrides this file entirely

Also refuses a .local.* overlay outright (skills/setup/SKILL.md:110-112). A lane file is a prose ruleset rather than a keyed config, so "override entirely" may be the right semantics — but it is the exact thing the seam forbids, recorded nowhere.

3. songwriting — wholesale replacement (undeclared)

plugins/songwriting/skills/setup/SKILL.md:26-28,39-43 — first-match-wins with no merge; a consumer override freezes that template out of future plugin updates. The freeze behaviour is the sharper concern: it is a silent staleness trap, independent of the merge question.

What a resolution looks like

For each: ratify (record as a declared exception in the layering owner doc, with its rationale) or correct (file a conformance issue against the plugin). A ratified exception should say what class of surface it applies to, so the next plugin facing the same shape has a rule rather than a precedent to argue from.

Why this is human-gated

These are doctrine calls with no codebase-resolvable answer. Ruling on them changes what the convention means for every future surface, and #2 and #3 may be legitimate semantics the seam simply did not anticipate — correcting them could be the wrong move.

Related

• docs/governance: consumer-config layering has no Convention registry row — 11 of 15 surfaces diverge from the seam-2 precedence rule #648 — the layering owner doc; its deviations section records these three as observed, and stays non-final until this issue rules on them
• source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647 — source-control conformance; unaffected by these rulings

Blocked on nothing.

[kyle-sexton]

2-minute decision brief — three layering deviations, one ruling

Scope: repo governance · Requires: maintainer judgment (not codebase-resolvable) · Blocks: #648 stays non-final until this rules

Problem

Three consumer-config surfaces deviate from the additive-preferred layering convention, and this issue asks, per surface, whether to ratify each as a declared exception (recorded in the layering owner doc with rationale + the surface class it covers) or correct it to conform (file a conformance issue against the plugin). The three are not the same kind of deviation, so a single blanket verdict is the wrong shape — the real work is deciding where each one falls.

Today — the convention, and what each surface actually does

The rule (docs/MIGRATION-PLAYBOOK.md:234-237, verified):

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.

The sanctioned escape hatch is already exercised in-repo — #647. source-control has an unmergeable value (a subject_pattern regex — "two values cannot concatenate"), so it takes the convention's blessed path: per-key override, recorded explicitly as a deliberate deviation. That works precisely because the other keys still merge — the base layer is not dropped; only one key's value is replaced. This is the yardstick for #2 and #3 below.

• chore: initialize marketplace scaffold #1 standards (docs/conventions/standards/README.md:35-39, verified) — a declared precedence inversion. Personal layers may ADD or TIGHTEN team standards; on a direct conflict the team layer wins, with provenance reporting when a personal rule shapes output. Note the axis: this is still additive (add/tighten) — it deviates on precedence direction (who wins a conflict), a policy floor that cannot be personally weakened. It is not wholesale replacement.
• fix: correct plugin-system inaccuracies and harden references #2 code-tidying (plugins/code-tidying/skills/tidy/lanes/docs-prose.md:14, verified) — "a project lane at .claude/tidy-lanes/docs-prose.md overrides this file entirely." Undeclared wholesale replacement of a whole prose-ruleset lane. setup/SKILL.md:110-112 also refuses any .local.* overlay — the surface resolves a single file (project lane, else bundled), no personal layer at all.
• feat: markdown-formatter plugin (pilot migration) #3 songwriting (plugins/songwriting/skills/setup/SKILL.md:26-28,39-43, verified) — template overrides are first-match-wins with no merge; a consumer override "freezes that template… so later plugin improvements to that template stop reaching this repo." Undeclared. The skill body warns about the freeze cost but it is recorded nowhere as a governance deviation.

Correction to the issue's framing: the freeze is not unique to #3. It is caused by wholesale replacement, so #2 has the identical freeze — a project lane that "overrides this file entirely" also stops bundled lane improvements from ever reaching that repo. #2 simply documents the cost less than #3 does. Treat the freeze as a property of wholesale-replace, not of songwriting.

Why #2 and #3 are not one class

• A code-tidying lane is decomposable: its Scope block is the part a project genuinely needs to retarget; the watch-for patterns (P-1..P-6) are generic and would concatenate fine. "Override entirely" is broader than the surface needs.
• A songwriting template is closer to gestalt — a single artifact with no independent keys to preserve. If that holds, overriding it necessarily drops the whole thing; the "per-key" hatch (source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647) literally cannot apply, because there are no other keys to keep merging.

That distinction decides everything: where an artifact can be decomposed, additive merge is the root fix for the freeze (non-overridden parts keep flowing from upstream). Where it genuinely cannot, the freeze is intrinsic and a staleness signal is the best available mitigation — not a band-aid, because there is no merge to fall back to.

External facts (illustrative, not load-bearing)

The policy-floor pattern behind #1 — a higher-authority layer that lower layers may extend but not weaken — is well established: Claude Code's own managed settings supersede user settings; GitHub org-enforced rulesets a repo cannot loosen; MDM managed preferences. This is prior art that strengthens ratifying #1, not correcting it. The merge-granularity question (#2/#3) is internal doctrine with no external authority to import.

---

Options

➤ Option 1 — Split by kind (RECOMMENDED). Ratify #1; correct #2; hold #3 on one sub-question.

• chore: initialize marketplace scaffold #1 → RATIFY as a named exception class ("policy-floor precedence inversion": personal layers may add/tighten, team wins direct conflict, provenance required). Near-zero cost — it is already documented with a reasoned rationale and provenance reporting. Correcting it would delete a defensible security property (a team standard a personal file cannot loosen), and the pattern has strong external prior art. This is the one high-confidence call.
• fix: correct plugin-system inaccuracies and harden references #2 → CORRECT. File a conformance issue against code-tidying: decompose the lane so a project overrides the Scope block per key (the exact source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647 path) while the generic watch-for patterns stay additive. This conforms and drains the freeze at its root, since upstream pattern improvements keep reaching the repo. No new exception class needed. (Its missing .local.* overlay is a separate single-layer gap, like source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647 — note it, don't fold it into the merge ruling.)
• feat: markdown-formatter plugin (pilot migration) #3 → the genuine remaining fork, on one factual question: are pat-pattison templates decomposable into overridable sections?
  • If yes → correct like fix: correct plugin-system inaccuracies and harden references #2 (per-section override, base sections keep flowing).
  • If no (truly gestalt) → ratify a distinct "whole-artifact override" class, but ratification is conditional on a mandatory staleness surface (version-stamp overrides; setup check reports "N versions behind upstream"), because the freeze is then intrinsic and silent staleness is a correctness defect in its own right.
  • Either way the undeclared status ends. Recommend the maintainer answer the decomposability question first, then apply the matching branch.

Why first: it matches the sanctioned in-repo precedent (#647 = declare + per-key), fixes the freeze at root wherever merge is possible instead of blessing it, ratifies only the one deviation (#1) that is genuinely a different axis and already earns its keep, and refuses to reward "deviate silently, get blessed later" for the two undeclared cases.

Option 2 — Ratify all three as declared exception classes, each with declare + (for the freeze) staleness obligations. Pro: closes the doctrine fastest and lets #648 finalize soonest. Con: rewards silent deviation — the exact drift this governance exists to stop; blesses #2's wholesale-replace when decomposition would fix the freeze at root (a band-aid); and stands up two permanent exception classes the fleet must forever audit where one (#3) may suffice.

Option 3 — Correct all three. Rejected: correcting #1 deletes a reasoned, documented policy-floor property with strong external prior art; it would force artificial per-key structure onto a deliberate precedence-inversion that is not even a merge-granularity problem. Only #2/#3 are plausibly correctable; #1 is not the same question.

Honest read

Ratifying #1 is close to settled. #2 leans correct (decomposable → additive fixes the freeze at root). #3 is the true human-gated call and turns on one empirical question (template decomposability) the maintainer is best placed to answer. Both Option 1 and Option 2 are defensible; the tie-breaker is whether this governance should reward declaration-after-the-fact (Option 2) or hold undeclared wholesale-replace to the same conform-or-declare-per-key bar that #647 already met (Option 1).

Cross-links

• docs/governance: consumer-config layering has no Convention registry row — 11 of 15 surfaces diverge from the seam-2 precedence rule #648 — layering owner doc; records these three as observed and explicitly leaves ratification to this issue; stays non-final until this rules. Whichever option lands, its deviations section is where a ratified class (or a filed correction) gets recorded.
• source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647 — source-control single-layer conformance fix; unaffected by these rulings. It is the precedent this brief leans on: unmergeable value → per-key override, declared. It ships independently.

[kyle-sexton]

Cross-note: PR #660 (closes #647) implements the three-layer source-control.md resolution WITH the per-key-merge deviation recorded in its body — it is held do-not-merge pending this decision. Your ruling here should confirm or override that deviation; the PR then merges as-is or adjusts.