feat: pilot the convention-doc migration on plugin-quality (Phase 2d)

.github/workflows/ci.yml

@@ -667,6 +667,28 @@ jobs:
           BASE_REF: ${{ github.base_ref }}
         run: scripts/sync-legacy-statusline-detect.sh --check-bump "origin/$BASE_REF"
 
+  resolve-convention-home-sync:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Fetch base
+        uses: ./.github/actions/checkout-with-base
+      - name: Verify resolve-convention-home cluster matches canonical
+        run: scripts/sync-resolve-convention-home.sh --check
+      - name: Run resolve-convention-home tests
+        run: bash plugins/claude-config/lib/resolve-convention-home.test.sh
+      - name: Run the plugin-quality pilot consumer-repo sim
+        run: bash scripts/pilot-plugin-quality-sim.test.sh
+      - name: Verify carrying plugins bumped when canonical changed
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: scripts/sync-resolve-convention-home.sh --check-bump "origin/$BASE_REF"
+
   resolve-convention-pattern-sync:
     runs-on: ubuntu-24.04
     timeout-minutes: 15
@@ -1797,6 +1819,7 @@ jobs:
       - spawn-noise-sync
       - check-retirements-sync
       - legacy-statusline-detect-sync
+      - resolve-convention-home-sync
       - resolve-convention-pattern-sync
       - index-regen-sync
       - standards-contract-sync

docs/conventions/config-cascade/README.md

@@ -297,7 +297,7 @@ convention home, layers → `team, via pointer line`, conformance → the retire
 | `ai-slop` | `.claude/ai-slop.json` | all three | conforms; per-key override, resolved by `/ai-slop:audit` (user-global, team, `.claude/ai-slop.local.json` overlay). Four list keys are additive-by-replacement rather than merged (`vocab_add` / `vocab_remove` tune the shipped word list, `phrase_add` / `phrase_remove` the shipped model-era phrase roster; the later layer's list wins per key). No policy-floor class: every key is a taste dial over prose style, and a personal overlay that silences a rule weakens nothing another surface depends on. Keys owned by `/ai-slop:setup`; `_comment` is an allowed free-text annotation, not drift |
 | `rendered-views` | `.claude/rendered-views.md` | all three | conforms; per-key override on `medium`, no policy-floor class (taste dial, the `ai-slop` precedent). Keys owned by [`rendered-views`](../rendered-views/README.md), which also partitions them from plugin `userConfig` dials (never keys in this surface; a layer declaring one is reported as an inert unknown key). Resolved by `visualization:visualize` (wave-1 exemplar) |
 | `testing` (`run-e2e`) | `.claude/testing/e2e.md` | all three | conforms; per-key override on `recording` / `browser_mode`, keys owned by `/testing:run-e2e` |
-| `plugin-quality` | `.claude/plugin-quality.md` | all three | conforms; per-key override (repo-map entries merge per plugin name), keys owned by the plugin's `reference/config.md` |
+| `plugin-quality` | convention doc at the consumer's convention home, `<home>/plugin-quality/README.md` (the pointer line binds `<home>`) | team, via pointer line | migrated (expression-doctrine pilot, ADR 0018): conformance is retirement record `plugin-quality-r001` (dual-read window while the retired `.claude/plugin-quality.md` persists — WARN-visible, the file reads as authority until cleaned); overlay layer retired by `plugin-quality-r002`, user-global layer retired prose-only (machine scope, outside the manifest); keys owned by the plugin's `reference/config.md` |
 | `claude-config` (`audit-pass`) | `.claude/audit-pass.md` | all three | conforms; per-key override (suppression entries merge per `finding_id`), plus policy-floor inversion — the team layer wins a direct conflict, since a personal overlay suppressing a finding the team never accepted is the weakening this class prevents. Keys owned by [`finding-suppression`](../finding-suppression/README.md) |
 | `overengineering` | `.claude/overengineering.md` | all three | conforms; per-key override, plus policy-floor inversion on two key groups — the protected-categories set and the suppression entries (which merge per `finding_id`). On both, the team layer wins a direct conflict, personal layers may extend or tighten only, and a personal contribution is named in the report: a gitignored overlay emptying the protected set would defeat the plugin's FLAG-FOR-HUMAN cap on security-class artifacts, and a personal-only suppression is the same weakening `audit-pass` prevents above. Narrowing or emptying the protected set stays available on the tracked layer, spelled one category at a time so the diff names each protection dropped. The threshold and observation-window keys take ordinary refinement. Keys owned by the plugin's `reference/consumer-config.md`; suppression-entry keys by [`finding-suppression`](../finding-suppression/README.md) |
 

docs/conventions/retired-conventions/README.md

@@ -296,9 +296,11 @@ the row states the manifest as it exists on `main`.
 | Plugin | Manifest record count | First record date |
 |---|---|---|
 | `source-control` | 1 | 2026-07-23 |
+| `plugin-quality` | 2 | 2026-09-01 |
 
-Row shape for a plugin adding itself: `` `<plugin>` `` \| count \| `YYYY-MM-DD`. The pilot surface
-for the convention-doc expression form is `plugin-quality`'s `.claude/plugin-quality.md` (ADR 0018).
+Row shape for a plugin adding itself: `` `<plugin>` `` \| count \| `YYYY-MM-DD`. The convention-doc
+expression-form pilot was `plugin-quality`'s `.claude/plugin-quality.md` (ADR 0018), retired by that
+plugin's first two records.
 
 ## Deferred
 

plugins/claude-config/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "claude-config",
-  "version": "0.40.29",
+  "version": "0.40.30",
   "description": "Nine configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-permission-state (the permission rules actually in effect \u2014 every settings scope merged with per-rule provenance, what auto mode drops on entry, config written where nothing reads it, and which managed intents are enforced versus loosenable), draft-auto-mode-rules (interview and draft a paste-ready autoMode classifier block; prints only, never writes), audit-instructions (locally-owned instruction surfaces vs current model capability \u2014 proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-prompting-postures (the additive lane \u2014 posture guidance the prompting guide says a component's purpose needs but the component does not carry), audit-pass (one coordinated, ordered, resumable pass over a named target \u2014 three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate \u2014 delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).",
   "author": {
     "name": "Melodic Software",

plugins/claude-config/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to the `claude-config` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.40.30]
+
+### Changed
+
+- Phase 2d pilot wiring. `lib/resolve-convention-home.sh` gains its sync cluster (`scripts/sync-resolve-convention-home.sh`, first carrier: plugin-quality) and its shared-source header note now cites the cross-plugin source registry instead of the pre-carrier placeholder wording.
+
 ## [0.40.29]
 
 ### Changed

plugins/claude-config/lib/resolve-convention-home.sh

@@ -60,10 +60,11 @@
 #      region; an unterminated or nested region; an invalid pointer path; a
 #      pointer whose target directory is missing
 #
-# Shared source: this is the canonical copy (claude-config). It is NOT yet
-# registered in scripts/cross-plugin-source-registry.txt and has no sync
-# script; the first consuming plugin adds both in the same change that copies
-# it. Bash 3.2-compatible on purpose: no associative arrays, no mapfile, no jq.
+# Shared source: this file is the canonical copy (claude-config) and is synced
+# byte-identical into the plugins that carry it by
+# scripts/sync-resolve-convention-home.sh, registered in
+# scripts/cross-plugin-source-registry.txt. Bash 3.2-compatible on purpose: no
+# associative arrays, no mapfile, no jq.
 
 set -uo pipefail
 # The grammar's character class is ASCII by definition; a collating locale

plugins/plugin-quality/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "plugin-quality",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Post-use behavioral audit of Claude Code plugin components: a six-step audit workflow (evidence capture, grounded mapping in a fresh subagent, blindspot pass, interactive contract lock, presence-gated review seams, work-item emit with draft+confirm) over any skill, agent, hook, command, or config you have actually used — zone-informed by context-guard snapshots when present, conservative when not.",
   "author": {
     "name": "Melodic Software",

plugins/plugin-quality/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to the `plugin-quality` plugin.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.6]
+
+### Changed
+
+- Convention-doc migration pilot (Phase 2d, ADR 0018). The team config surface moves from the dedicated `.claude/plugin-quality.md` cascade to a topic doc at the consumer's convention home (`<home>/plugin-quality/README.md`), bound by the config-cascade pointer line and resolved via the bundled `lib/resolve-convention-home.sh`. Ships `retirements.yaml` (`plugin-quality-r001` migrate for the tracked file, `plugin-quality-r002` delete for the overlay) with the synced `lib/check-retirements.sh`; setup `check` reports the resolver outcomes distinctly and the retirement findings, `apply` converges the pointer-line region and the topic doc with per-record gated cleanup. The retired user-global and overlay layers are no longer read anywhere, and their presence WARNs rather than being silently ignored; the dual-read window (old tracked file present) reads the file as authority with a visible WARN until cleaned.
+
 ## [0.7.5]
 
 ### Changed

plugins/plugin-quality/README.md

@@ -21,11 +21,16 @@ their repo mid-session.
 - **Reference corpus** (`skills/audit/references/`), the recurring-concerns checklist plus five
   component-type lenses (hook, skill, agent, command, config). Extending coverage = one file +
   one index row; the hub never grows.
-- **Config surface** (`reference/config.md`). `.claude/plugin-quality.md` (sink, zone behavior,
-  repo-map overrides) layered per the config-cascade convention, with a documented sink ladder
-  and markdown item schema.
+- **Config surface** (`reference/config.md`). A convention doc at the consumer's convention home
+  (`<home>/plugin-quality/README.md`, bound by the config-cascade pointer line; sink, zone
+  behavior, repo-map overrides), with a documented sink ladder and markdown item schema. The
+  retired dedicated-file layers are declared in `retirements.yaml` and detected by the shared
+  `check-retirements.sh` helper, with a WARN-visible dual-read while the old tracked file
+  persists.
 - **Setup skill** (`skills/setup`). `check` (gh + ACTING account, context-guard seam → dispatch
-  mode, config layers with per-key provenance) / `apply` (writes only the tracked config).
+  mode, convention-home binding + effective config with provenance, retired-convention
+  leftovers) / `apply` (converges the pointer-line region and the topic doc, plus gated
+  retirement cleanup).
 
 ## Context-gate (context-guard integration)
 
@@ -53,8 +58,8 @@ install is required; it just makes long-session audits smarter about their own d
 ```
 
 Zero config works: conservative dispatch, sink resolved by inference or interview at emit time.
-Run `/plugin-quality:setup check` to see the seams; `setup apply` to pin a sink in the tracked
-config.
+Run `/plugin-quality:setup check` to see the seams; `setup apply` to bind the convention home
+and pin a sink in the topic doc there.
 
 ## Requirements