docs(consumer-config-layering): ratify policy-floor precedence-inversion exception class (#649)

[kyle-sexton]

What

Ratifies the standards precedence inversion as a named, sanctioned exception class in the consumer-config layering contract — the disposition #649 recommended for that surface ("reads as defensible" / policy-floor).

• README (docs/conventions/consumer-config-layering/README.md): defines the policy-floor precedence-inversion class under Merge semantics (team layer wins a direct conflict; personal layers stay add/tighten-only; provenance reported — with a three-part qualification test and external prior art). Moves standards from an observed deviation to the ratified exemplar; reconciles the Deviations intro and the Implementers conformance cell.
• CHANGELOG: 1.1 entry.

Why a minor bump

Default precedence (user → team → local, additive-preferred) is unchanged for every surface; this only carves out a conditional inversion for one surface class. That is additive relaxation → minor per the contract's own SemVer note. The contract version lives solely in CHANGELOG.md; the Convention registry row in PLUGIN-PHILOSOPHY.md names-and-points without a version, so no lockstep drift.

Scope

Deliberately narrow: the policy-floor class + standards only. The other two deviations named in #649 are dispositioned via follow-up issues, each owning its own contract-row update:

• code-tidying: docs-prose lane uses undeclared wholesale replacement — decompose to per-key override (conformance, ruling #649) #701 code-tidying docs-prose lane → CORRECT (decompose to per-key override), status: ready.
• songwriting: template overrides use undeclared wholesale replacement — decomposability decision gates correct-vs-ratify (ruling #649) #703 songwriting template overrides → decomposability decision gates correct-vs-ratify, status: needs-decision (human-gated; not yet actionable).

Applied under operator momentum delegation; veto window open — conventions remain operator-owned and any veto reverts mechanically.

Closes #649

Related

• code-tidying: docs-prose lane uses undeclared wholesale replacement — decompose to per-key override (conformance, ruling #649) #701 — code-tidying docs-prose conformance correction (this PR does not close it).
• songwriting: template overrides use undeclared wholesale replacement — decomposability decision gates correct-vs-ratify (ruling #649) #703 — songwriting decomposability decision (human-gated; this PR does not close it).
• source-control: tracked config is single-layer — no ~/.claude user-global or *.local.* overlay, diverging from seam 2 #647 / feat(source-control): layer convention config across three layers #660 — source-control per-key deviation; confirmed by the ratified per-key path, already merged, unaffected.

[claude]

Claude finished @kyle-sexton's task in 1m 27s —— View job

---

PR Review — docs(consumer-config-layering): policy-floor exception class

• Load tools and initialize
• Read PR diff and changed files
• Analyze changes for correctness, consistency, and alignment with guidelines
• Post review findings

---

Summary

Clean, well-scoped documentation change. The policy-floor exception class is correctly defined, the three-part qualification test is explicit and verifiable, and the SemVer minor bump is justified. No bugs, no security concerns, no architectural issues.

---

README.md — docs/conventions/consumer-config-layering/README.md

New subsection — Sanctioned exception class (L74–L96):

The three-part qualification gate is tight and correct — policy-floor intent, add/tighten-only personal layers, and mandatory provenance reporting. The prior art list (managed settings, org rulesets, MDM managed prefs) is apt and gives implementers calibration for edge cases. Placement under "Merge semantics" is the right home since the class explicitly stays "additive on every other axis" — the inversion is scoped to conflict resolution only, not merge mode.

One observation worth noting: the word "materially" in condition 3 ("when a personal-layer rule materially shapes output") is intentionally not absolute — minor personal-layer additions wouldn't require provenance noise on every output. This is a reasonable design call, but implementers will need to exercise judgment on the threshold. Consider whether a sentence of guidance ("e.g., when a personal-layer rule changes a key value that would otherwise be set by the team floor") would help, or whether leaving it to per-surface declarations is sufficient.

Deviations section restructuring (L158–L168):

The three-tier structure (Ratified / Declared / Undeclared) is clean and correctly signals intent. The updated intro sentence — "Ratifying one — as #649 did for the policy-floor precedence-inversion class above — moves it from observed to sanctioned" — explains the state machine well for future readers.

Implementers table (L200):

The standards conformance cell correctly moves from "deviation" framing to "conforms via the policy-floor precedence-inversion class (ratified #649)." Consistent with the rest of the changes. Other rows (code-tidying, ai-briefing, etc.) are deliberately unchanged — the PR description correctly points those to #701 and #703.

---

CHANGELOG.md — docs/conventions/consumer-config-layering/CHANGELOG.md

v1.1 entry (L9–L18):

The minor bump is justified — default precedence for every existing surface is unchanged; this only carves out an exception class. The entry summary and bullet accurately describe the change. Format matches 1.0.

Both 1.0 and 1.1 share the same date (2026-07-20), which looks slightly unusual but is accurate — 1.0 was the initial extraction (#692 / bd8ec5f) and 1.1 is the ratification committed in the same calendar day. Not an error.

---

No blocking issues

All changes are internally consistent, scoped correctly, and accurate. The contract_version living only in CHANGELOG headings (not as a machine-readable field) is a pre-existing design decision, not introduced here.

Verdict: ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bd25aab780

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 20s —— View job

---

PR Review — docs(consumer-config-layering): policy-floor exception class

• Load tools and initialize
• Read PR diff and changed files at HEAD
• Analyze new commit vs previous review scope
• Post review findings

---

New commit: f971602 — scope standards ratification to precedence axis only

This commit addresses the Codex P2 finding from the prior review round: the previous bd25aab marked standards as fully conformant, which hid its still-unratified layer-location deviation (team/overlay layers at <standards_dir>/ rather than .claude/<name>). f971602 fixes this cleanly.

What changed (docs/conventions/consumer-config-layering/README.md):

1. Ratified section header tightened to "one axis only" — scopes the reader's expectations before they reach the content.

2. Ratified bullet (L164–L170) now explicitly states: "This ratification covers the precedence axis alone. standards also diverges on layer location (see Declared, below), which docs/governance: rule needed on three consumer-config layering deviations (standards inversion, code-tidying + songwriting wholesale replace) #649 did not rule on and which remains observed." The cross-reference to the Declared section below is correct — the reader finds the companion entry immediately on scanning down.

3. New Declared entry (L174–L178) for standards layer location is placed first in the Declared block (before autonomy and disk-hygiene), which is the right order — it pairs with the Ratified entry above it. The "Observed, not ratified" label is accurate and consistent with how other deviations are flagged.

4. Implementers table (L207) now carries two distinct states: precedence inversion ratified via policy-floor class (#649); layer location outside .claude/ still observed, not ratified. The cell is dense but accurate — an audit reader gets both axes without needing to cross-reference.

CHANGELOG — not modified in f971602, which is correct. The 1.1 entry describes the exception class ratification, and that description remains accurate. The scoping of what #649 did and did not rule on is structural/editorial, not a contract rule change. No version bump is warranted for a same-PR correction.

---

No new issues

The fix is precise and well-scoped. The Codex P2 concern is resolved without disturbing the precedence-axis ratification. The three-tier state machine (Ratified / Declared / Undeclared) remains coherent, and both axes of standards' divergence are now independently tracked and auditable.

Verdict: ready to merge.