fix(source-control): name --keep-data in setup's uninstall guidance (0.55.6)

[kyle-sexton]

Closes #3131

Summary

/source-control:setup's babysit-config section warned operators not to uninstall the plugin in order to reconfigure it, citing the pluginConfigs entry that an uninstall drops — and stopped there. --keep-data appeared nowhere in the plugin (grep -rn 'keep-data' plugins/source-control/ returned zero hits before this change).

That left a real gap for the operator who uninstalls for one of the other legitimate reasons — troubleshooting, changing scopes, reinstalling a version. Uninstalling from the last remaining scope deletes ${CLAUDE_PLUGIN_DATA} by default, and this plugin keeps durable state there.

Fix

One paragraph added to skills/setup/SKILL.md's "Babysit config" section, after the reconfigure bullets. It names the flag, says what the directory holds, and — the part that took the most care — states the resolution rung each worktree root must fall through before it lands there.

What the directory actually holds, verified in-tree rather than assumed:

Path	Contents	Relocatable?
${CLAUDE_PLUGIN_DATA}/state/babysit-prs	queue state (babysit_state.py, queue-state.json), worker leases (manage_babysit_lease.py), feedback ledger (manage_feedback_ledger.py)	No userConfig key relocates it
${CLAUDE_PLUGIN_DATA}/worktrees	babysit worktrees; /source-control:worktree trees	Only at the last resolution rung — see below

"Left unset" is necessary but not sufficient for worktree_root. scripts/worktree-create.sh:20-32 resolves a root over five rungs, and the plugin option is rung 3, below the target repository's melodic.worktreeroot git config at rung 2. So /source-control:worktree create lands in the data directory only when neither resolves. babysit_worktree_root is the simpler case and does fall back there whenever it is unset. Stating only "unset" would have over-warned the operator who uses the recommended per-repo git key, and the paragraph now distinguishes the two.

The emphasis is on the losses that are actually irrecoverable. Babysit's own worktrees are ephemeral scratch that rebuild from GitHub; the state directory and a /source-control:worktree tree holding uncommitted work are not. An earlier draft had this backwards.

Follows docs/conventions/plugin-data-report-keying/README.md Rule 4 ("state the uninstall fragility where the artifact is the only copy").

Verification

Gate	Result
claude plugin validate plugins/source-control	Validation passed
scripts/check-changed-skills.sh (setup)	PASS — 0 errors, 1 pre-existing soft-target warning
scripts/check-changelog-parity.sh --check / --check-bump / --check-order / --check-preserved	PASS
scripts/sync-plugin-options-docs.py --check	up to date
scripts/check-skill-count-claims.sh --check	PASS
scripts/check-skill-leaf-names.sh --check	PASS
scripts/check-cross-plugin-source-drift.sh --check	PASS
markdownlint-cli2 (both changed markdown files)	0 issues
typos	clean

Doc claims re-fetched at rung 1, not taken from a repo snapshot. curl https://code.claude.com/docs/en/plugins-reference.md on 2026-08-23, 108305 bytes: "By default, uninstalling from the last remaining scope also deletes the plugin's ${CLAUDE_PLUGIN_DATA} directory. Use --keep-data to preserve it", and the plugin uninstall flag table carries --keep-data spelled exactly that way.

Rebased twice onto a moving main; now at 0.55.6. main landed #3108 during this work, which de-slopped every source-control instruction surface under the repo's zero-tolerance em dash policy and took 0.55.4; the worktree-claim change from #3104 / #2882 then took 0.55.5. The added prose is written em dash free to match the rewritten file it lands in (grep -c '—' over the changed SKILL.md returns 0). Left unrebased, the version collision would have failed check-changelog-parity.sh and the prose would have silently reintroduced the marks #3108 had just removed.

Independent review. A fresh-context reviewer checked the diff against the issue's acceptance criteria with the author's rationale withheld. It raised one blocker (the worktree_root conditional was false in both directions — it over-warned past melodic.worktreeroot and under-warned by omitting /worktree create trees from the consequence) and two should-fixes (state described as "lane and lease state", which misattributes loop-lane telemetry that actually lives in a GitHub tracking issue and survives an uninstall; and a "neither has another copy" claim that contradicted the plugin's own reference/worktrees.md). All three are fixed above; the reviewer's nits on length and antecedent are applied too.

Related

• Closes source-control/setup: uninstall guidance omits --keep-data (destroys babysit worktrees and lease state) #3131 — F3 from the /plugin-quality:audit packet. The other findings in that packet are out of scope here and tracked separately.
• Refs Cross-plugin: hook-utils skip latch silences 9 formatters, overlay-ignore guard unreachable, plugin-quality seal premise false #3128 — F1 from the same run, shared with work-items.
• Refs source-control/worktree: reap helper uninstalls without --keep-data, deleting other plugins' data directories #3212 — filed from this work, and materially more dangerous than the gap this PR closes. scripts/reap-project-plugin-records.sh:238 runs claude plugin uninstall "$id" -s project without --keep-data, non-interactively, for every plugin id with a project-scope record keyed to a worktree being torn down (/source-control:worktree cleanup Step 4b). For any plugin whose project-scope record was its last remaining scope, that call deletes that plugin's ${CLAUDE_PLUGIN_DATA}. Verified directly against the script. It is other plugins' data and a code change rather than prose, so it sits outside source-control/setup: uninstall guidance omits --keep-data (destroys babysit worktrees and lease state) #3131's prose-only acceptance criteria and is tracked on its own rather than folded in here.
• One adjacent surface deliberately left alone. plugins/source-control/README.md:337-338 carries a parallel uninstall warning, but it sits inside the BEGIN GENERATED block emitted by scripts/sync-plugin-options-docs.py:100-101 and shared verbatim by every plugin README in the marketplace — a hand-edit is clobbered on the next sync, and editing it here would have been the mistake. Adding --keep-data to the generator is a one-line change that fixes roughly forty READMEs at once; it is left out of this PR because it changes every plugin's README rather than source-control's, not because it needs a decision.

---

Generated by Claude Code

[claude]

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

---

Security review — /review:security-review

• Gather context (PR diff, description, changed files)
• Run /review:security-review per instructions
• Post findings

Skip gate: no security-relevant surface. This PR touches only three files:

• plugins/source-control/.claude-plugin/plugin.json — version bump (0.55.4 → 0.55.5)
• plugins/source-control/CHANGELOG.md — changelog entry
• plugins/source-control/skills/setup/SKILL.md — one added prose paragraph documenting claude plugin uninstall --keep-data in the babysit-config guidance

There is no executable code, no GitHub Actions workflow, no auth/authz logic, no injection surface, and no secret/token handling in this diff — it's a documentation-only change. No security findings to report.

[claude]

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

---

Claude's Review

Tasks

• Gather context (PR diff, changed files, CLAUDE.md)
• Understand the request (invoke /review:code-review)
• Read changed files in full
• Verify technical claims against source (worktree-create.sh resolution order, babysit_worktree_root fallback, reference/worktrees.md, plugin-data-report-keying Rule 4, README generated block)
• Post findings as inline PR comments (none needed — no issues found)
• Post summary review comment

Summary

This is a documentation-only fix (SKILL.md + CHANGELOG.md + version bump), and it holds up well under verification. I independently checked every factual claim in the added paragraph against the code it describes rather than taking the PR body at its word:

• Resolution order (worktree-create.sh:20-32) confirms melodic.worktreeroot (rung 2) outranks the worktree_root plugin option (rung 3), with the plugin data dir at rung 4 — matches the new paragraph's claim exactly.
• babysit_worktree_root resolution table in skills/babysit-prs/SKILL.md:306 confirms it falls straight back to ${CLAUDE_PLUGIN_DATA}/worktrees with no intervening git-config rung, correctly distinguished from the more conditional worktree_root case in the new text.
• Irrecoverability framing is accurate: reference/worktrees.md:3 states babysit worktrees are "ephemeral scratch, not durable state," while nothing in the babysit-prs reference set describes the queue state, worker leases, or feedback ledger as reconstructible from GitHub — so scoping the "no other copy" warning to the state dir and /worktree trees (not babysit's own worktrees) is correct.
• Rule 4 citation matches docs/conventions/plugin-data-report-keying/README.md:153-158 verbatim in spirit.
• README scope-out is correct: the parallel warning at README.md:337-338 sits inside the sync-plugin-options-docs.py generated block, so leaving it alone here (rather than hand-editing a generated section) is the right call.
• House style: no em dashes in the added prose, consistent with the plugin's zero-tolerance policy noted in the 0.55.4 changelog entry.
• CHANGELOG/version bump: 0.55.5 entry format matches prior entries; plugin.json version bump is consistent.

No bugs, factual errors, or style violations found in the diff. One very minor observation, not a blocker: the PR title metadata (... (0.55.4)) is stale relative to the actual commit/CHANGELOG version (0.55.5) — likely just an artifact of the version bump happening after the PR was opened, not a diff issue.

Nice work tracing the multi-rung resolution logic precisely rather than over-warning — the distinction between babysit_worktree_root's simple fallback and worktree_root's conditional one is exactly the kind of detail that's easy to get wrong in prose.

[github-actions]

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

[claude]

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

---

Security review — /review:security-review

• Gather context (PR diff, description, changed files)
• Run /review:security-review per instructions
• Post findings

Skip gate: no security-relevant surface. Confirmed via gh pr diff 3211, this update only touches:

• plugins/source-control/.claude-plugin/plugin.json — version bump (0.55.5 → 0.55.6)
• plugins/source-control/CHANGELOG.md — new [0.55.6] changelog entry
• plugins/source-control/skills/setup/SKILL.md — the same added prose paragraph (documenting claude plugin uninstall --keep-data in the babysit-config guidance), unchanged since the prior review

No executable code, no GitHub Actions workflow, no auth/authz logic, no injection surface, and no secret/token handling — this diff is documentation-only (prose, a changelog entry, and a version bump). The prior security review at 33f77fde reached the same conclusion for the identical SKILL.md prose; the delta since then is only the CHANGELOG entry and version bump, neither of which is security-relevant. No security findings to report.

[claude]

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

---

Claude's Review

Tasks

• Gather context (PR diff, description, changed files)
• Invoke /review:code-review and follow its instructions
• Read changed files in full
• Post findings as inline PR comments (none — no new content to review)
• Post summary review comment

Summary

Skip gate: this head already has a successful review from this lane that still applies. I diffed the current head (6509033, plugin.json now at 0.55.6) against the previously-reviewed SHA (33f77fde, reviewed at 0.55.5):

git diff 33f77fde9456a1c6c71a23f4578e0bc604c8af76..HEAD -- plugins/source-control/skills/setup/SKILL.md

returns no output — the added paragraph in skills/setup/SKILL.md is byte-identical to what a prior pass on this same PR already reviewed and approved. The only changes since then are:

• plugin.json: version bump 0.55.5 → 0.55.6, forced by a rebase onto main that landed an unrelated 0.55.5 (source-control: worktrees created outside worktree-create.sh carry no lock, so concurrent sessions reach into each other's trees with no claim to check #2882, worktree-claim gate) in between, pushing this PR's entry up a patch version.
• CHANGELOG.md: renumbered heading to match, entry body unchanged.

I independently re-verified the core technical claim rather than taking that on faith: scripts/worktree-create.sh:18-29 confirms the root-resolution order the added paragraph describes — melodic.worktreeroot git config (rung 2) outranks the worktree_root plugin option (rung 3), with the plugin data directory as the last rung (4) before refusal. This matches the SKILL.md text exactly.

No findings. Nothing in this push changes the reviewable surface beyond a mechanical version renumber from rebasing.

[kyle-sexton]

Superseded by #3216. This PR conflicts with origin/main after source-control 0.55.5 landed (#3104). #3216 is the same prose fix rebased onto current main at 0.55.6.