docs: reconcile cloud-fleet setup, freeze the renames map, add a retirement policy

[kyle-sexton]

Summary

Three documentation/doctrine changes that were contradicting reality or each other.

docs/CLOUD-FLEET-SETUP.md carried a per-repo fleet table whose rows had gone stale — the
standards row still read "settings + CLAUDE.md, no bootstrap hook" — and a second copy of the
per-repo bootstrap script that had drifted from what the fleet actually runs. The doc also framed
per-repo bootstrap adoption as work still to be scheduled.

The renames map contradiction. .claude-plugin/marketplace.json carries a 12-entry map;
docs/topics/shadowed-skill-renames/PLAN.md records the standing posture that no new entries are
added while the marketplace settles; but plugins/claude-config/README.md still described the map
as the live migration mechanism.

Plugin retirement was undocumented. docs/MIGRATION-PLAYBOOK.md codifies creation and update
delivery but says nothing about deleting a published plugin.

Fix

1. Fleet doc reconciled. The repo population was enumerated from the org rather than inherited
   from the stale table (gh repo list melodic-software --json name,isArchived → 15 non-archived
   repos; the three archived ones are medley-archive, melodic-main-archive,
   itinerary-planner). Each of the 15 was checked at origin/main via
   gh api repos/melodic-software/<repo>/contents/.claude plus its settings.json: adoption is
   universal — all 15 carry .claude/cloud-bootstrap.sh, register it as a startup|resume
   SessionStart hook, declare the melodic-software marketplace, and enable the catalog. The
   per-repo enumeration is retired rather than corrected (it restated state cheaper to read
   from the repos), leaving the toolchain-pin inventory, which is the one input to Step 1 that
   lives nowhere else. The embedded bootstrap script is replaced by a pointer to standards
   components/cloud-bootstrap plus the never-synced .claude/cloud-bootstrap.local.sh enrich
   seam — this repo no longer maintains a second copy. Step 1's rollout note now states plainly
   that the rollout kit's edit-Default-in-place supersedes standing up a separate named
   Melodic environment.
2. Renames map recorded as frozen-historical in docs/MIGRATION-PLAYBOOK.md under "Version
   pinning and update delivery": the existing twelve entries stay (removing one strands consumers
   whose settings still carry a pre-rename plugin id), no new entries are added, and later renames
   ship as clean breaking changes per the shadowed-skill-renames posture.
   plugins/claude-config/README.md now describes its entry as a historical migration aid rather
   than the go-forward mechanism.
3. Retirement policy added to docs/MIGRATION-PLAYBOOK.md: catalog entry and plugins/<name>/
   directory removed in one PR (scripts/check-plugin-manifest-presence.sh FORWARD/INVERSE checks
   force the symmetry), derived surfaces regenerated, the retirement recorded in the PR body
   because the CHANGELOG.md goes with the directory, plus consumer guidance (installed copies
   keep working from the version-keyed cache; drop the enabledPlugins entry; no tombstone or
   renames entry).

plugins/claude-config bumped 0.38.5 → 0.38.6 with a matching changelog entry, as the
README edit requires.

Verification

Run in the worktree, all green:

Command	Outcome
bash scripts/validate-plugins.sh	All plugin manifests and the catalog validated.
node scripts/validate-plugin-contracts.mjs	46 setup skills and 2566 plugin files checked
node scripts/generate-catalog.mjs --check	Catalog is in sync with the manifests.
node scripts/generate-cheatsheet.mjs --check	Cheat sheet is in sync with skill frontmatter.
bash scripts/check-plugin-manifest-presence.sh	every entry resolves; no unregistered directories
bash scripts/check-changelog-parity.sh --check	pass
bash scripts/check-changelog-parity.sh --check-bump origin/main	pass (0.38.6 entry present)
bash scripts/check-changelog-parity.sh --check-preserved origin/main	pass (73 headings compared)
bash scripts/check-changelog-parity.sh --check-order	pass (78 changelogs newest-first)
npx markdownlint-cli2 on the changed .md files	0 issues
lychee --offline --config lychee.toml on the changed files	0 Errors

CI on this branch is green across every required gate (hygiene, plugin-gate, review,
security-review, pr-issue-linkage, pr-title, do-not-merge, shell-portability-lint, and
the rest).

The retirement section's gate claims were read out of the scripts rather than assumed:
check-plugin-manifest-presence.sh's header documents the FORWARD/INVERSE pair, and
check-changelog-parity.sh --check-preserved explicitly continues when a changelog is absent
and its directory is gone — a removal, not an absorbed section — which is why the policy puts
the retirement note in the PR body rather than in a final changelog entry.

One deviation from the brief, called out deliberately: the brief states standards PR #397 has
landed. It has not — gh pr view 397 --repo melodic-software/standards reports OPEN, and
components/cloud-bootstrap does not exist on standards main. The two links this doc now points
at therefore 404 until #397 merges, so a dated status blockquote says so and names the PR, and the
Step 2 pointer refers back to it so a reader following the link is not surprised. Link checking is
unaffected in CI (the online lane is advisory and weekly; the offline lane skips external URLs),
and the blockquote is a single deletable paragraph once #397 lands.

Also found, not fixed here (standards-repo concern): the cloud-bootstrap block in
distribution/sync-manifest.yml on the #397 branch comments that "dotfiles: no cloud-bootstrap
adoption yet", but melodic-software/dotfiles on main already carries
.claude/cloud-bootstrap.sh and registers it. Seven repos with a committed bootstrap have no
manifest row at all (dotfiles, knowledge-corpus, songwriting, claude-code-proxy,
codex-plugins, cursor-plugins, claude-lane-sandbox) — unmanaged copies that will drift. This
doc deliberately points at the manifest instead of restating the split, so it stays correct as
those rows land.

docs/CLOUD-SESSIONS.md was left untouched: it describes this repo's own bootstrap and the
pre-launch call, and nothing in it contradicts the reconciled fleet doc.

Related

No linked issue

🤖 Generated with Claude Code

https://claude.ai/code/session_012tKxg98B3QySqEPf8UqwX3

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 2m 49s —— View job

---

Code review complete

• Gather context (PR body, diff, repo CLAUDE.md/REVIEW.md)
• Apply skip gate (open, non-draft, meaningful review surface — proceeding)
• Review docs/CLOUD-FLEET-SETUP.md
• Review docs/MIGRATION-PLAYBOOK.md
• Review plugins/claude-config/README.md, CHANGELOG.md, plugin.json
• Post findings

This is a documentation-only reconciliation PR (REVIEW.md's security/atomicity checks don't apply here — no code, no multi-record writes). One finding posted inline.

1 finding (🟡 Nit) — inline on docs/CLOUD-FLEET-SETUP.md line 167: Step 2's .claude/cloud-bootstrap.sh guidance ("do not author one") points at the standards components/cloud-bootstrap contract, which per this PR's own "Status" blockquote (line 66) is still unmerged (standards#397). Step 2 doesn't cross-reference that blockquote, so a reader onboarding a new repo today following it literally hits a dead end (author nothing, but the canonical source 404s). Small ask: restate or link the interim guidance ("hand-author until #397 merges") in Step 2 itself.

Everything else checked out:

• The retirement-policy claims in docs/MIGRATION-PLAYBOOK.md about scripts/check-plugin-manifest-presence.sh (FORWARD/INVERSE symmetry) and scripts/check-changelog-parity.sh --check-preserved (directory-gone exemption) match the actual script logic — read directly, not taken on faith.
• The renames map is independently confirmed to have exactly 12 entries in .claude-plugin/marketplace.json, including claude-config-audit → claude-config, matching the "frozen-historical" framing added to the playbook and the README update.
• plugins/claude-config/plugin.json version bump (0.38.5 → 0.38.6) is matched by a CHANGELOG.md entry consistent with the file's existing format; the catalog entry in marketplace.json carries no version field, so no regeneration was needed there.
• No dangling cross-references found: nothing else in the repo (prompts/cloud-bootstrap-rollout.md, docs/CLOUD-SESSIONS.md) links to the specific table/heading this PR retired from CLOUD-FLEET-SETUP.md.
• The PR body's own called-out deviation (standards PR feat(repo-hygiene): multi-repo clean/tree mode with skip-list + dirty guard #397 not actually merged, contra the brief) is accurate and disclosed with a dated blockquote in the doc, as claimed.

Not independently re-run: the PR's listed verification commands (validate-plugins.sh, generate-catalog.mjs --check, check-changelog-parity.sh, markdownlint-cli2, lychee) — these are author-claimed and unverified by me; my Bash tool calls to re-run them were blocked pending approval in this session, so I verified the underlying script logic by reading source instead of executing it.

[claude]

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

---

Claude finished the security review

• Gather context (PR body, changed files list)
• Invoke /review:security-review per custom instructions
• Post findings / summary

Security review — no findings

Read the full diff (git diff origin/main...HEAD) against the 5 changed files. This PR is documentation-only:

• docs/CLOUD-FLEET-SETUP.md — removes a stale per-repo fleet table and an embedded copy of cloud-bootstrap.sh, replacing both with pointers to the canonical script in the standards repo (components/cloud-bootstrap). No script logic is added or modified here — the shell script content is deleted, not changed.
• docs/MIGRATION-PLAYBOOK.md — adds prose sections documenting the frozen renames map policy and a plugin-retirement policy. No code.
• plugins/claude-config/.claude-plugin/plugin.json — version bump 0.38.5 → 0.38.6.
• plugins/claude-config/CHANGELOG.md — changelog entry for the bump.
• plugins/claude-config/README.md — prose update describing the renames map as historical rather than go-forward.

No GitHub Actions workflows, scripts, permission configs, or executable code are touched. There's no injection surface, no auth/access-control logic, no secret/token handling, and no permissions:/trigger changes in this diff. This trips the skip gate ("change has no security-relevant surface after reading the diff") in review:security-review's criteria.

Result: no security issues found.

[github-actions]

Last security-reviewed head: 439cca3f30870add418e323821967062eb3a871f. 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 4 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

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

---

Code review — /review:code-review (code-review lane)

• Gather context (PR body, changed files, /review:code-review skill instructions)
• Run skip-gate checks
• Read diff against origin/main for the 5 changed files (via gh pr diff)
• Check CLAUDE.md / REVIEW.md for repo-specific criteria (root CLAUDE.md is empty in this repo; REVIEW.md scopes this lane to correctness/design/conventions/error-handling/observability/tests/docs, security out)
• Review each file for correctness, maintainability, consistency
• Cross-check the doc's factual claims against the scripts/files it cites
• Post findings

Result: no blocking findings

This is documentation-only (3 doc/README edits + a version bump + matching changelog entry). I read the full diff and cross-checked its factual claims against the actual repo state rather than taking the PR body at face value:

• .claude-plugin/marketplace.json's renames map has exactly 12 entries — matches the "twelve entries stay" claim in docs/MIGRATION-PLAYBOOK.md.
• scripts/check-plugin-manifest-presence.sh's header does document the FORWARD (catalog → missing manifest) and INVERSE (directory → no catalog entry) pair exactly as the new "Retiring a published plugin" section describes.
• scripts/check-changelog-parity.sh --check-preserved (lines ~520-533) does continue — i.e. exempts the gate — when a changelog is absent from HEAD and its directory is also gone, confirming the "removal, not absorbed section" reasoning behind putting the retirement note in the PR body instead of a final changelog entry.
• docs/topics/shadowed-skill-renames/PLAN.md does state "no renames-map entries" / "NO renames-map entries while the marketplace is settling" — matches the frozen-historical framing added to the playbook and to plugins/claude-config/README.md.
• The "fifteen non-archived" repo count in the rewritten docs/CLOUD-FLEET-SETUP.md reconciles exactly against the 15 rows the deleted per-repo table used to carry — internally consistent, not an arbitrary new number.
• The #bootstrap-adoption-2026-08-16 anchor referenced from Step 2 matches the new heading's GitHub slug, and the version-bump + changelog pairing (0.38.5 → 0.38.6) is present and newest-first as this repo's changelog convention requires. No stale internal links to the removed "Fleet audit" / "per-repo templates" headings remain anywhere else in the repo.

One item worth noting for transparency rather than as a new finding: an earlier automated review on this PR flagged that Step 2's "do not author one" guidance for .claude/cloud-bootstrap.sh (docs/CLOUD-FLEET-SETUP.md line 167) left no actionable fallback for onboarding a repo before standards#397 merges. The second commit on this branch (d277b68) addressed that by cross-referencing the Status blockquote from Step 2 — one of the two remediations that review itself suggested — so I'm not re-filing it as a blocking finding, just noting it's been responded to rather than silently dropped.

I did not independently re-run markdownlint-cli2, lychee, or the validation/gate scripts the PR body lists (tool approval in this lane doesn't extend to executing them) — treat those as author-claimed and unverified by me, per this lane's own instructions not to restate a PR author's claimed verification as independently confirmed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 439cca3f30

ℹ️ 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 3m 15s —— View job

---

Code review complete

• Gather context (PR body, diff, custom instructions)
• Invoke /review:code-review procedure
• Read diff against origin/main for the 5 changed files
• Review each file for correctness/maintainability/consistency
• Post inline findings and summary

This PR has been reviewed by this lane three times already at earlier SHAs. This push (synchronize) added two new commits since the last full review round: d277b68 (already covered by the prior 22:36 review) and 87e782f, which is new. 87e782f only touches docs/CLOUD-FLEET-SETUP.md (−7/+1), so I scoped this pass to that delta.

1 finding (🟡) — posted inline on docs/CLOUD-FLEET-SETUP.md:169:

Commit 87e782f deletes the "Status (2026-08-16)" blockquote and its Step 2 cross-reference, on the claim that standards#397 has merged. I could not independently verify that claim — both gh pr view 397 --repo melodic-software/standards and a WebFetch on the PR required approval unavailable in this session, so per this lane's rule against restating author-claimed verification as confirmed, I'm flagging it rather than treating it as settled. This matters because it's exactly the spot two earlier review rounds (mine and Codex's) flagged as a dead end: if standards#397 is in fact still open, this commit removed the only interim fallback guidance those rounds asked for, so a reader hits 404s with no caveat at all — a regression versus the previously-reviewed state. The PR's own body notes CI's link checkers won't catch this either way (offline lychee skips external URLs, online lychee is weekly/advisory). Worth a maintainer confirming gh pr view 397 --repo melodic-software/standards --json state,mergedAt before merge; if merged, this is a non-issue.

Everything else in this delta is clean: no dangling references to the removed blockquote or its #bootstrap-adoption-2026-08-16 anchor remain anywhere in the repo, and the surrounding prose in both hunks reads correctly after the deletions.

Not re-filed as new findings (still open from earlier rounds, unchanged by this push, so not re-verified here): Codex's P2 on docs/CLOUD-FLEET-SETUP.md:174 that this repo's own .claude/cloud-bootstrap.sh doesn't actually invoke .claude/cloud-bootstrap.local.sh yet — confirmed still true (grep for cloud-bootstrap.local only matches the doc, not the script), but that's pre-existing content from the earlier commits, not something 87e782f touched.

Not independently re-run: the PR's listed verification commands (validate-plugins.sh, generate-catalog.mjs --check, markdownlint-cli2, lychee, etc.) — gh/network Bash calls were blocked pending approval in this session, so these remain author-claimed and unverified by me.
(branch)

[claude]

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

---

Code review — /review:code-review (code-review lane)

• Gather context (PR body, prior review comments, /review:code-review skill instructions)
• Identify delta since last full review round (commit 87e782f)
• Review new commit 06952df
• Post findings

This PR has been reviewed by this lane multiple times already. This push (synchronize) added one new commit since the last full round: 06952df (docs(cloud-fleet): keep Step 2 actionable pre-row and scope the enrich seam honestly), a +7/-2 edit confined to docs/CLOUD-FLEET-SETUP.md. I scoped this pass to that delta.

1 finding (🟡) — posted inline on docs/CLOUD-FLEET-SETUP.md:169-171:

The commit's new interim guidance ("a repo onboarding before its manifest row lands copies the component file verbatim") is a real fix for the "do not author one, no fallback" gap two earlier rounds flagged — but the fallback itself presumes components/cloud-bootstrap already exists on standards main (i.e. standards#397 has merged). The doc no longer carries any caveat about #397's status at all (the "Status" blockquote that used to flag this was removed in 87e782f), so if #397 is in fact still open, this interim path is also a dead end with nothing in the doc warning a reader. I could not independently verify #397's current state — gh pr view and WebFetch both require approval unavailable in this lane, the same limitation two earlier review rounds on this PR hit. Worth a maintainer confirming before merge; if #397 is confirmed merged, this is a non-issue.

Resolved, not re-filed: Codex's earlier P2 (docs/CLOUD-FLEET-SETUP.md:174) that this repo's own .claude/cloud-bootstrap.sh doesn't invoke .claude/cloud-bootstrap.local.sh — this commit fixes it directly. I confirmed this repo's committed .claude/cloud-bootstrap.sh has no reference to cloud-bootstrap.local.sh and no such file exists here, and the new prose now correctly scopes the seam to managed targets only, stating plainly that this locally-owned repo "has no cloud-bootstrap.local.sh and needs none."

Not independently re-run: the PR's listed verification commands (validate-plugins.sh, generate-catalog.mjs --check, markdownlint-cli2, lychee, etc.) — gh/network Bash and WebFetch calls were blocked pending approval in this session, so these remain author-claimed and unverified by me.
(branch)