refactor: repo-wide coupling reduction pass (coupling:reduce)

[kyle-sexton]

No linked issue

Summary

One /coupling:reduce pass over the whole repository, run as nine scoped passes
(repo governance, docs/conventions, the automation layer, and six plugin
clusters). Structure only: every change is behavior-preserving and reversible by
a plain revert. No behavioral riders.

The headline result is how little was left to apply. This repository has already
adjudicated most of its coupling on the record, and the verify gate closed a
large share of the leads I started from: all eight broken intra-plugin citations
inventoried in docs/specs/docs-hygiene-sweep-unapplied-remediations.md, the
twelve detector-findings reaches into review:fanout privates, and the sweep's
only Tier 1 finding in .claude/rules/ are all already fixed. They are not
re-emitted here. What survived is concentrated in two shapes: addresses that
bind to a position rather than a name, and one rule stated twice with nothing
keeping the two statements in agreement.

Fix

Fifteen files carry reductions (~30 lines); the other twenty are the version and
CHANGELOG bookkeeping this repo's sweep convention requires.

Addresses that bind to a position rather than a name

• Two rotted file:line citations in docs/conventions. hook-observability
  cited lib/hook-utils.sh:26-30 for the dim-9 doctrine — that range is an
  unrelated comment about claude plugin disable|enable, and the quoted sentence
  sits ~23 lines further down. detector-findings pinned a hard-FAIL to
  check-skill.sh:414, a comment line inside the rationale block. Both now name
  their target instead of pinning its position.
• Five path citations that do not resolve from the base their own form implies,
  in claude-config, kindle-dedrm, review, source-control and
  mutation-testing. None renders as a broken link and none greps red. The
  sharpest is in claude-config: a passage arguing about claude-memory:audit's
  catalog wrote a bare reference/criteria.md, which resolves against the citing
  file's own directory onto audit-instructions' own catalog — a real file with
  no C6 — so a reader checking the claim finds it false rather than finding the
  path wrong. mutation-testing's reached the marketplace docs/ tree through
  ../../../../../, which resolves only in a checkout and is dead in an installed
  plugin, inside a file that instructs "if the contract cannot be fetched, do not
  write".

One rule stated twice, with the copies disagreeing

• hook-telemetry's Implementers table is a hand-maintained inventory of its own
  data/ directory and had drifted by a whole plugin: 35 schemas on disk, 33
  rows, disk-hygiene absent entirely despite owning two of them since
  2026-08-12 and being wired in its own hooks.json.
• Four collaborator handoffs in testing, planning and verification were
  stated once in the owning SKILL.md with a presence gate and a fallback, and
  once in a restating file with neither. In two of the three the ungated copy is
  the one that executes. Each restating site now mirrors its owner's wording.
• disk-hygiene's safety-model.md claimed --confirmed-large-scan was "the one
  valueless scan flag"; destructive_guard.py strips at most one each of that
  and --root-children, and the same document documents --root-children
  elsewhere. A safety surface contradicting both the parser and itself. Prose
  only; the parser is unchanged.

Cross-plugin reach removed

• session-flow's find-handoff corroborated a claude agents --json --all
  claim by citing claude-ops' skill-private lane-launcher.sh and its
  internal load_sessions symbol by path. session-flow declares no dependency
  on claude-ops, so that path is absent whenever session-flow installs alone.
  The citation was load-bearing for nothing — the same sentence already sources
  the claim first-hand from claude agents --help.

Verification

Clean-tree baseline was captured before any edit, so nothing below is
pre-existing red.

• scripts/affected-tests.sh --run — 16 shell suites pass.
• The 8 Python suites it selects but does not execute, run in their own lanes:
  source-control/babysit-prs 643 tests OK, disk-hygiene
test_guard_launch_monitor 23 OK, check-contract-clause-coverage 24 OK.
• scripts/check-changed-skills.sh origin/main — 8 skills checked, 0 failed;
  all base-ref trigger phrases preserved on both touched SKILL.md files.
• scripts/check-changelog-parity.sh --check and --check-bump origin/main — pass.
• scripts/validate-plugins.sh — all 71 manifests and the catalog validate.
• scripts/check-purged-em-dashes.sh — pass.
• markdownlint-cli2 over the 25 changed markdown files — 0 issues.
• typos, editorconfig-checker — clean. All 10 bumped manifests parse.
• scripts/check-cross-plugin-source-drift.sh — exit 0. Its DIFFERS rows are
  discovery output for unregistered clusters; the one touching a file in this diff
  (skills/audit/context/persist-findings.md) was verified to differ identically
  on origin/main, so it is pre-existing and not introduced here.

Related

The route lane is the substantive half of this pass and is deliberately not
applied — cross-file and architectural findings inform a human by design. The
three highest-ranked, each independently confirmed:

• The loop-lane inline rate-limit floor has no gate and has already drifted.
  docs/conventions/loop-lane/README.md §6 mandates a byte-identical floor across
  babysit-loop, work-loop and attend-queue. Nothing enforces it:
  check-cross-plugin-source-drift.sh excludes SKILL.md by name and clusters
  only on identical path-within-plugin, so it is blind twice over. The three lane
  bodies are still identical to each other but have all diverged from the
  rate-limit-guard reader contract they claim to match, broken by two
  uncoordinated de-slop commits (dff09429, 67466227) neither of which touched
  the source. A fifth copy in prompts/loops/ sits on the other side of the split.
  Three separate scan agents reached this independently. The repo already ships the
  fix for the structurally identical sibling case
  (plugins/plugin-quality/scripts/zones-inline-drift.test.sh for context-guard).
• A telemetry precursor block is hand-copied into 12 hook payload scripts across
  10 plugins, and only one carries the actionlint: membership guard silently skips lint on 8.3 short paths + cd-failure reads as clean + abs-path leak in telemetry #1133 absolute-path-leak fix. In
  typos-format the unfixed value reaches the tool invocation, not just telemetry.
  The smallest mechanism is one rung away: a helper in lib/hook-utils.sh, which
  the existing hook-utils-sync CI lane already propagates to all 17 carriers.
• knowledge's intra-plugin shared vendor/ carries ADR 0019's
  delivery-by-version invariant with nothing enforcing it. Seven --check-bump
  lanes cover the cross-plugin clusters; none covers the intra-plugin case, and two
  commits have already shipped vendored-source changes with the manifest version
  unchanged.

Also routed: the findings-file cell-escaping algorithm implemented three times
with one implementation behaviorally wrong on already-escaped input; the
CLAUDE_CONFIG_DIR/HOME resolver hand-copied 8× in two mutually incompatible
forms; two live scripts/check-*.sh gates wired into no workflow; and the review
skip-actors bot list restated at 5 sites with cursor[bot] already missing from one.

Full ranked ledger with evidence: .work/coupling/coupling-ledger.md (memory
tier, never committed).

Refs ADR 0018, ADR 0019, docs/conventions/seam-phrasing, docs/conventions/loop-lane.

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 4m 0s —— View job

---

Reviewing PR #3457

• Gather context (diff, changed files, CLAUDE.md/AGENTS.md conventions)
• Invoke /review:code-review and follow its instructions
• Post inline findings (if any)
• Post summary review comment

Summary

This is a structure-only citation/coupling-reduction pass across 15 content files plus 20 version-bump/changelog bookkeeping files. I independently verified every fix claimed in the PR body against the actual target files rather than trusting the description, and all of them check out:

• docs/conventions/hook-observability/README.md — lib/hook-utils.sh's # --- Prerequisite visibility --- section does carry the quoted dim-9 doctrine sentence verbatim; the old :26-30 line pin was indeed stale.
• docs/conventions/detector-findings/README.md — confirmed check-skill.sh no longer has a stable line 414 anchor for the trigger-phrase hard-FAIL; the new unpinned description matches the actual check (err "dropped trigger keyword(s) ..." around line 462).
• docs/conventions/hook-telemetry/README.md — counted: 35 *.schema.json files on disk in docs/conventions/hook-telemetry/data/, and the Implementers table now has exactly 35 rows, with disk-hygiene (destructive-guard, guard-launch-monitor) present and correctly wired in that plugin's hooks.json.
• plugins/claude-config/README.md + .../conflict-criteria.md — confirmed plugins/claude-config/reference/ doesn't exist (old link was dead) and that claude-memory:audit's own reference/criteria.md (not claude-config's) is where C6 actually lives — the pre-fix text's bare path silently resolved to a real, wrong file, exactly as described as the sharpest case in the PR body.
• plugins/kindle-dedrm/README.md — skills/manage/scripts/status.sh and skills/manage/references/versions.md exist at the corrected paths, and skills/manage/SKILL.md already addresses both the same way.
• plugins/mutation-testing/.../persist-findings.md — the ../../../../../docs/... relative escape is replaced with the same raw.githubusercontent.com/melodic-software/claude-code-plugins/main/... absolute form the file already uses for its detector-findings contract citation two lines away.
• plugins/review/skills/fanout/SKILL.md and plugins/source-control/reference/review-discipline.md — both ${CLAUDE_PLUGIN_ROOT}-anchored forms match the sibling-citation convention already used elsewhere in the same files.
• plugins/session-flow/.../rung-1-known-location.md — confirmed session-flow's manifest declares no dependency on claude-ops, so the removed path (claude-ops' skill-private lane-launcher.sh/load_sessions) was genuinely dead weight; the sentence still sources the claim first-hand from claude agents --help.
• Four collaborator-handoff fixes (planning interview loop, testing run-e2e, verification confirm ×2) — each restating site's new gate+fallback wording is a verbatim match to its owning SKILL.md's existing wording (e.g. verification/skills/confirm/SKILL.md:112 vs the fixed :147, planning/.../interview/SKILL.md:70/138 vs the fixed context/loop.md:70).
• plugins/disk-hygiene/.../safety-model.md — destructive_guard.py strips at most one each of --confirmed-large-scan and --root-children (confirmed in scripts/destructive_guard.py), and the doc already documents --root-children elsewhere in the same file, so the old "the one valueless scan flag" line was self-contradictory. Fix is prose-only; parser untouched, as claimed.

All ten touched .claude-plugin/plugin.json version bumps are single patch increments with a matching new top CHANGELOG.md entry in the correct Fixed/Changed category, consistent with this repo's changelog-parity convention.

I could not execute scripts/affected-tests.sh --run myself in this sandbox (Bash approval was not available for it), so I'm not independently re-confirming the PR's listed suite-pass counts — those remain author-claimed. Everything else above I verified by reading the actual referenced files/scripts, not by trusting the PR description.

No findings. I found no incorrect fix, no broken link introduced, no citation that resolves to the wrong target, and no changelog/version mismatch. This is a clean, well-scoped, behavior-preserving pass — nothing here rises to the high-signal bar for a blocking or flagged comment.

[claude]

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

---

Security review complete

• Gather context (PR diff, changed files, repo instructions)
• Invoke /review:security-review and follow its instructions
• Post findings / summary

Skip gate hit: no security-relevant surface.

I reviewed the full diff (gh pr diff 3457, 35 files, +130/-30) against origin/main. Every change is one of:

• Prose edits in docs/conventions/** and plugin README.md/reference files — fixing rotted file:line citations, unresolvable relative paths, and restated-but-drifted collaborator handoffs to match their owning SKILL.md.
• plugin.json version bumps (patch only) and matching CHANGELOG.md entries.

No scripts, hooks, GitHub Actions workflows, permission grants, authentication/authorization logic, or data-handling code are touched. There is no injection surface, no credential/token handling, and no trust-boundary change — this is a documentation-coupling reduction pass (per the PR description) with zero behavioral riders.

Per the skill's skip gate ("Change has no security-relevant surface after reading the diff") — stopping here with no findings.

[github-actions]

Last security-reviewed head: d838000f4bb10aca332b0e8b990183c16b491ed5. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d838000f4b

ℹ️ 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 encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[github-actions]

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/33148127354
• Failure class: rate-limit
• Last SDK result: {"subtype":"success","is_error":true,"num_turns":1,"duration_ms":439,"total_cost_usd":0,"api_error_status":429,"class":"rate-limit"}

Re-run the job, or workflow_dispatch this workflow with the PR number, to retry the review. A new push re-triggers this lane only if the caller's pull_request triggers include synchronize (the canonical caller omits it).
An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator (auth).