docs(config-cascade): rename consumer-config-layering seam → config-cascade

[kyle-sexton]

Summary

Renames the marketplace-wide consumer-config layering seam from the clunky three-noun
consumer-config-layering to config-cascade.

Name chosen via /naming:name-it-better (blind 3-lens fan-out): "cascade" (CSS @layer/!important)
is the one established term of art that natively carries both per-key override and a ratified
precedence-inversion — matching the seam's user→team→local + policy-floor model. Runner-ups:
config-layering, layer-cascade, config-precedence.

• git mv docs/conventions/consumer-config-layering → config-cascade.
• All live references updated (name + path): MIGRATION-PLAYBOOK, PLUGIN-PHILOSOPHY, loop-lane seam,
  code-tidying (SKILL + docs-prose lane), testing (README + run-e2e SKILL/context), .gitignore.
• Seam README records the former name (discoverability); CHANGELOG records the rename with no
  contract_version bump — name/path only, contract unchanged.
• code-tidying 0.7.1→0.7.2, testing 0.3.1→0.3.2 (patch) so consumers receive the corrected doc-URL.
• Historical topic docs / CHANGELOGs retain the former name as frozen record (bare-text mentions,
  not links).

Provenance context: the rename was gated (issue #1187) on whether the seam was legitimately
ratified. Finding: all 12 docs/conventions/* seams are PR-introduced across the repo's whole history;
consumer-config-layering (#692) is unremarkable. The shared kyle-sexton identity (human + agents)
makes metadata-level "human-ratified vs agent-accreted" undecidable — a repo-wide property, not a
disqualifier for this seam. The operator's direct direction this session is the ratification.

Test plan

• lychee --offline './**/*.md' — 0 errors (2754 links checked); no dead relative link to the old path.
• grep -rn '](.*conventions/consumer-config-layering' . — none (no dead relative links).
• scripts/check-changelog-parity.sh --check-bump origin/main — both bumped plugins have entries.
• Remaining consumer-config-layering mentions are historical bare-text only (topic PLANs, CHANGELOGs, .work/).

Related

• Closes conventions: rename consumer-config-layering seam -> config-cascade #1188
• Provenance context: conventions: audit provenance/ratification of docs/conventions/* seams (human vs agent-as-kyle-sexton) #1187 (audit finding recorded above)
• Follows feat(source-control): well-known default path for neutral convention SSOT (F1–F4) #1185 (well-known path, which dogfoods the docs/conventions/<concern>/ location)

🤖 Generated with Claude Code

[claude]

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

---

PR Review: docs(config-cascade): rename consumer-config-layering → config-cascade

Tasks

• Gather context (PR body, changed files)
• Read diff and key changed files
• Review for correctness, consistency, and alignment with CLAUDE.md
• Post findings

---

Summary

Clean, well-scoped rename. No correctness bugs or security issues. The approach is sound: git mv semantics, all live references updated, historical docs frozen with the old name, discoverability note added to the new README, CHANGELOG records the rename with no contract-version bump (correct — name/path only), and patch bumps on the two affected plugins so consumers receive corrected doc URLs on next update. One substantive observation, two minor notes.

---

Substantive observation

Existing installs will get a 404 on the raw-GitHub URLs until they upgrade

plugins/code-tidying/skills/tidy/SKILL.md and plugins/code-tidying/skills/tidy/lanes/docs-prose.md, along with their testing counterparts, embed raw-GitHub /main/ URLs:

https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/config-cascade/README.md

After this PR merges, any consumer running a cached copy of code-tidying ≤0.7.1 or testing ≤0.3.1 will attempt to fetch the old path (consumer-config-layering/README.md) and get a 404. The patch bumps (→0.7.2 / →0.3.2) are the right mitigation — new installs and updates get working links — but existing pinned installs are broken until they upgrade.

This is structurally inherent to embedding /main/ raw URLs and is probably acceptable as-is (the changelogs call it out explicitly), but it's worth documenting the expectation clearly for operators: if you're running either plugin, upgrade to pick up the corrected links.

---

Minor notes

1. plugins/testing/README.md bare-text reference has no link

Line 49:

it layers per the marketplace
config-cascade convention.

The old text also lacked a link, so this is not a regression. A relative link to docs/conventions/config-cascade/README.md would make this navigable, but it's a cosmetic improvement outside the rename scope.

2. docs/PLUGIN-PHILOSOPHY.md table label is slightly verbose

The registry row was changed to Config cascade — consumer-config layering and precedence. The old-name suffix aids discoverability, though Config cascade (consumer-config layering) or just Config cascade might be cleaner once the rename is established. Not a blocker — the current form is explicitly intentional for discoverability.

---

Verification against test plan claims

• grep -rn '](.*conventions/consumer-config-layering' . — confirmed 0 matches (no dead relative links in live files).
• Remaining bare-text mentions of consumer-config-layering are all in docs/topics/*/PLAN.md, design/design-resolution.md, historical plugin CHANGELOGs, and .work/ — all frozen records, consistent with the PR's stated policy.
• Both plugin CHANGELOGs have entries matching the version bumps. ✓
• The rename entry in docs/conventions/config-cascade/CHANGELOG.md correctly carries no contract_version bump. ✓

---

Verdict: Approve. The substantive note is informational — the patch bumps already mitigate it. No blocking issues.

[claude]

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

---

Security Review — PR #1190

• Gather PR diff and changed files
• Review plugin.json changes for supply-chain / version-pinning risk
• Review skill/context files for injection surfaces
• Review .gitignore change
• Review documentation files for embedded secrets or unsafe patterns
• Post findings

---

No security issues found.

This PR is a pure documentation rename operation — 15 files touched, all documentation or metadata. Reviewed against the full diff of origin/main...HEAD.

What was checked:

Area	Finding
.gitignore	Comment-only update (consumer-config-layering → config-cascade in an inline remark). No path exclusion logic changed.
plugin.json (code-tidying, testing)	Patch version bumps only (0.7.1→0.7.2, 0.3.1→0.3.2). No permissions, mcpServers, dependencies, or command declarations present or altered.
Skill .md files	Four raw.githubusercontent.com/…/main/… URL path segments updated. The main-branch reference is a pre-existing architectural pattern, not introduced by this PR — the PR merely renames the directory segment in the URL. No new remote trust surface opened.
Relative links in docs	Mechanical path updates (../consumer-config-layering/ → ../config-cascade/). No executable content, no template injection surfaces.
GitHub Actions workflows	No workflow files modified.
Secrets / credentials	None present in any changed file.

The raw.githubusercontent.com/…/main/… link pattern (mutable branch reference in skill files) is a pre-existing repo convention; it is out of scope for this PR's delta.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b840862941

ℹ️ 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 46s —— View job

---

PR Review: docs(config-cascade): rename consumer-config-layering → config-cascade

Tasks

• Gather context (PR body, changed files, prior reviews)
• Read diff and changed files (HEAD SHA: d094d1d)
• Review for correctness, consistency, and CLAUDE.md alignment
• Post findings

---

Summary

Two commits, scoped correctly. The rename commit (b840862) was already reviewed and approved by a prior Claude pass. This review focuses on the follow-up commit (d094d1df) that adds a compatibility tombstone at the old path in response to the Codex P2 finding. That commit is clean and closes the only open substantive concern.

---

Tombstone commit (d094d1df) — verdict: correct

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

The tombstone is minimal, self-explanatory, and contains exactly what cached installs need:

• Relative link to the new canonical path — navigable in-repo.
• Full raw URL for the new path — the form cached skill files actually fetch.
• Clear removal condition ("once the old plugin versions are no longer in circulation") — removes ambiguity about when it can be deleted.

No dead links, no circular references, no stale content from the 229-line original leaking through. The diff confirms the old full file was replaced in full.

---

Verification pass

Claim	Status
No dead relative links to the old path in live files	✓ — grep -rn '](.*conventions/consumer-config-layering' . returns zero matches in live files
Remaining bare-text consumer-config-layering mentions are all in historical frozen records	✓ — appears in testing 0.3.0 CHANGELOG entry, config-cascade CHANGELOG rename entry, and config-cascade README provenance note — all correct
Both plugin CHANGELOGs have entries for the version bumps	✓
config-cascade/CHANGELOG.md rename entry carries no contract_version bump	✓ — "Renamed" heading only, no SemVer entry
Skill file raw URLs point at config-cascade	✓ — all four updated in b840862
Tombstone raw URL in tombstone README matches skill file destination	✓ — both resolve to .../config-cascade/README.md

---

No new issues introduced

The tombstone raw URL uses the same /main/ branch reference pattern already present throughout the repo's skill files — not introduced by this PR, out of scope for this delta. The tombstone cleanly handles the window between old cached installs and the patch-bumped versions.

---

Verdict: Approve. The tombstone commit directly and correctly addresses the only open concern from prior reviews. No blocking issues.

[claude]

Claude finished @kyle-sexton's task in 51s —— View job

---

Security Review — PR #1190

Tasks

• Fetch PR diff
• Read changed files
• Review for injection, auth, secrets, Actions patterns, supply-chain risk
• Post findings

---

No security issues found.

This PR is a pure documentation rename — 16 files touched, all Markdown or JSON metadata. Reviewed against the full diff of origin/main...HEAD.

Area	Finding
.gitignore	Comment-only change. The active ignore pattern (.claude/**/*.local.*) is untouched.
plugin.json (code-tidying, testing)	Patch version bumps only (0.7.1→0.7.2, 0.3.1→0.3.2). No permissions, mcpServers, dependencies, or command declarations present or altered.
Skill / context .md files	Four raw.githubusercontent.com/…/main/… URL segments updated from consumer-config-layering to config-cascade. The mutable /main/ reference pattern is pre-existing and not introduced by this PR; no new remote trust surface opened.
Tombstone file (consumer-config-layering/README.md)	The new tombstone (permalink) embeds a hardcoded raw.githubusercontent.com/main/ back-link to this same repo. No external redirect, no SSRF vector, no open redirect.
Relative links in docs	Mechanical path updates (../consumer-config-layering/ → ../config-cascade/). No executable content, no template injection.
GitHub Actions workflows	No workflow files modified.
Secrets / credentials	None present in any changed file.