From 6f1dd810ee041998dec42d22d5f6f9a9bb6bb023 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 22 Jul 2026 12:23:45 -0400 Subject: [PATCH 1/2] chore(source-control): document plugin as sole worktree-convention SSOT (#401) Close the SSOT gap left by the retired external ghq-layout-sibling-pr-worktrees prose doc. The babysit worktree-exemption policy (lease-scoped cleanup, never a global open-PR prune) is already fully captured and machine-enforced by prune_babysit_worktrees.py, and the skill migrated its root off CODEX_HOME to ${CLAUDE_PLUGIN_DATA}; the Codex-home root was a per-user babysit_worktree_root config value, not plugin content to migrate. - babysit-prs/reference/worktrees.md: state the plugin is the canonical, sole source for the ephemeral babysit-worktree exemption; add the discoverable-tree rationale (rooting outside repos keeps scratch out of ghq list). - worktree/SKILL.md: state the skill owns the parallel-session external-root convention going forward. Version bump 0.17.0 -> 0.17.1 with matching CHANGELOG entry. --- plugins/source-control/.claude-plugin/plugin.json | 2 +- plugins/source-control/CHANGELOG.md | 13 +++++++++++++ .../skills/babysit-prs/reference/worktrees.md | 6 ++++++ plugins/source-control/skills/worktree/SKILL.md | 2 ++ 4 files changed, 22 insertions(+), 1 deletion(-) diff --git a/plugins/source-control/.claude-plugin/plugin.json b/plugins/source-control/.claude-plugin/plugin.json index d6fbba843..c4986b759 100644 --- a/plugins/source-control/.claude-plugin/plugin.json +++ b/plugins/source-control/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "source-control", - "version": "0.17.0", + "version": "0.17.1", "description": "Git and GitHub delivery workflow: /commit (Conventional Commits + Co-Authored-By trailer via safe heredoc mechanics), /pull-request (prep, create, CI monitoring, review-comment triage, merge, CI-log fetch), /babysit-prs (self-pacing fleet loop — safe by default; opt-in worker/autopilot tiers add gate-checked merge and thread resolution behind a deterministic Python engine), /worktree (create, status, cleanup, audit for parallel-session isolation), /setup (check the effective commit-subject / PR-title convention merged across its config layers and the babysit-prs config, or apply — interview the repo and write the convention config to a chosen layer), and /resolve-conflicts (intent-first merge/rebase conflict resolution with a semantic-conflict sweep — never --abort). The commit-subject / PR-title convention is configurable via a source-control.md config written by a re-runnable setup skill, layered across a ~/.claude user-global file, the tracked team file, and a gitignored .claude/source-control.local.md personal overlay merged per key; Conventional Commits is the default when no convention is declared.", "author": { "name": "Melodic Software", diff --git a/plugins/source-control/CHANGELOG.md b/plugins/source-control/CHANGELOG.md index 1d7e09bcd..4bc66f564 100644 --- a/plugins/source-control/CHANGELOG.md +++ b/plugins/source-control/CHANGELOG.md @@ -3,6 +3,19 @@ All notable changes to the `source-control` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.17.1] + +### Changed + +- **The plugin is now the canonical, sole source for the worktree conventions (#401).** The + `babysit-prs` skill's `reference/worktrees.md` states it owns the ephemeral babysit-worktree + exemption (lease-scoped cleanup, never a global open-PR prune — machine-enforced by + `prune_babysit_worktrees.py`) and that rooting those worktrees outside a repository's discoverable + tree keeps them out of enumeration such as `ghq list`; the `worktree` skill states it owns the + parallel-session external-root convention going forward. Both close the SSOT gap left by the + retired external `ghq-layout-sibling-pr-worktrees` prose doc (physical deletion of that doc is a + separate follow-up in the dotfiles repo). + ## [0.17.0] ### Added diff --git a/plugins/source-control/skills/babysit-prs/reference/worktrees.md b/plugins/source-control/skills/babysit-prs/reference/worktrees.md index 30c914453..601f3c5dd 100644 --- a/plugins/source-control/skills/babysit-prs/reference/worktrees.md +++ b/plugins/source-control/skills/babysit-prs/reference/worktrees.md @@ -9,6 +9,12 @@ key's resolved value and its unset fallback; `` defaults to the ` subdirectory of the plugin data directory, and `` is its `state/babysit-prs` subdirectory. +This file is the canonical, sole source for the babysit ephemeral-worktree convention — the +plugin owns it, not any external prose doc. Rooting these worktrees outside every repository's +discoverable tree (the plugin data directory by default) is deliberate: it keeps ephemeral +scratch out of repository enumeration such as `ghq list`. Repointing `babysit_worktree_root` +back under a discoverable tree reintroduces that pollution. + ## Policy - At the start of a queue run holding the queue lease, remove only unleased clean babysit diff --git a/plugins/source-control/skills/worktree/SKILL.md b/plugins/source-control/skills/worktree/SKILL.md index 418bee17e..77e492000 100644 --- a/plugins/source-control/skills/worktree/SKILL.md +++ b/plugins/source-control/skills/worktree/SKILL.md @@ -20,6 +20,8 @@ Orchestrate git worktree lifecycle from creation through cleanup. **Front-half** **Why this exists:** worktrees are the isolation mechanism for parallel code changes — multiple Claude Code sessions on different tasks without stepping on each other. In repos where branch protection blocks direct commits to main, every feature, fix, or refactor starts with a worktree or branch; this skill makes that seamless. +This skill is the canonical owner of the parallel-session worktree convention going forward — no external prose doc. Worktrees live at an external `worktree_root` (`/--`, outside every repository), never as siblings inside a repository's discoverable tree; the abandoned sibling-layout convention polluted repository enumeration and re-triggered the #400 double-load bug. + ## Adapting to your environment (graceful degrade) This skill is self-contained — every action runs on plain `git`, plus `gh` for PR cross-referencing where available. Where it mentions an adjacent capability (an issue tracker, a build/lint verifier, a session-start setup hook), treat it as optional: use it when your environment provides it, proceed without it otherwise. Project-specific conventions — branch naming, worktree layout, which gitignored files a fresh worktree needs — come from the consuming project's own `CLAUDE.md`, rules, and hooks; read them before creating or removing anything. From c4a942ae1703627ef6d7b53c2992b113d3545be5 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 12:24:44 -0400 Subject: [PATCH 2/2] docs(source-control): narrow worktree-root claim to the enforced nesting invariant The canonical-convention sentence promised worktrees never land under a repository-discovery root, but creation only rejects paths inside an existing repository. State the enforced invariant (nesting) as enforced and the discovery-root placement as convention the operator chooses. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_017P1vVA8iViUTfQWjA9tgZG --- plugins/source-control/skills/worktree/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/source-control/skills/worktree/SKILL.md b/plugins/source-control/skills/worktree/SKILL.md index 1608881c9..3c566160c 100644 --- a/plugins/source-control/skills/worktree/SKILL.md +++ b/plugins/source-control/skills/worktree/SKILL.md @@ -20,7 +20,7 @@ Orchestrate git worktree lifecycle from creation through cleanup. **Front-half** **Why this exists:** worktrees are the isolation mechanism for parallel code changes — multiple Claude Code sessions on different tasks without stepping on each other. In repos where branch protection blocks direct commits to main, every feature, fix, or refactor starts with a worktree or branch; this skill makes that seamless. -This skill is the canonical owner of the parallel-session worktree convention going forward — no external prose doc. Worktrees live at an external `worktree_root` (`/--`, outside every repository), never as siblings inside a repository's discoverable tree; the abandoned sibling-layout convention polluted repository enumeration and re-triggered the #400 double-load bug. +This skill is the canonical owner of the parallel-session worktree convention going forward — no external prose doc. Worktrees live at an external `worktree_root` (`/--`, outside every repository), never nested inside any repository's tree — that nesting invariant is what creation enforces (the abandoned sibling-layout convention re-triggered the #400 double-load bug). Keeping `worktree_root` clear of repository-discovery roots (such as a ghq root) is convention, not machine-checked: creation rejects only paths inside an existing repository, and a discovery-root placement would pollute repository enumeration the same way the sibling layout did — choose the root accordingly. ## Adapting to your environment (graceful degrade)