chore(source-control): document plugin as sole worktree-convention SSOT (#401)#1021
Conversation
…OT (#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.
kyle-sexton
added
do-not-merge
|
Claude finished @kyle-sexton's task in 1m 47s —— View job PR Review
This is a clean, well-scoped documentation-only PR. Four files changed; no logic is touched. Here's my full assessment: What the PR doesDeclares SSOT ownership inside the plugin, closing the gap left by the retired external
CorrectnessNo issues. Both added blocks accurately describe the existing machine-enforced policy (confirmed by the PR's own verification against Placement in each file is logical:
Version bump is appropriate. SecurityNo concerns. This is entirely inert text — no code execution, no credential handling, no trust delegation, no external URLs, no data egress paths introduced. The plugin-form safety checklist passes unchanged. Alignment with CLAUDE.md guidelines
Minor observation (no action required)
SummaryThe PR does exactly what it says, adds no risk, and is correctly scoped. The |
|
Claude finished @kyle-sexton's task in 1m 57s —— View job Security Review
No security issues found. This PR is entirely documentation and version metadata. All four changed files were audited:
No injection surfaces, no secrets or credential handling, no GitHub Actions workflow changes, no permission widening, no new external dependencies, and no supply-chain risk in scope. |
|
🔒 merge-drive lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, worker tier). Will fix clear branch-owned CI/bot findings, defer non-DEFER-FORBIDDEN items with reply+resolve, push, then re-check the merge gate. |
Resolve source-control CHANGELOG conflict by composing both sides: keep #1055's self-describing team-convention-file entry as [0.17.1] (shipped to main), and move the worktree-convention SSOT entry to a new [0.17.2] heading. Re-bump plugin.json 0.17.1 -> 0.17.2 (one increment past main's current value).
|
Claude finished @kyle-sexton's task in 1m 48s —— View job PR Review
This is a documentation-only PR that closes an SSOT gap. All four changed files were read and audited against the diff. What changed
CorrectnessNo issues with the content. Both added blocks accurately describe the existing machine-enforced policy, placement in each file is logical (declaration precedes the policy details in One discrepancy to note — PR body is stale. The PR description says "This PR bumps
|
| Criterion | Status |
|---|---|
| Repo-agnostic (no hardcoded paths/names) | ✓ |
Configurable via userConfig (no change to config surface) |
✓ |
Plugin-form-safe (no ../ reach-outs) |
✓ |
| Explicit semver version set | ✓ (0.17.2) |
| No PII / secrets | ✓ |
| Point-don't-copy (no restating of retired prose) | ✓ |
Summary
The code changes are clean and correct. Two items to address before merge:
- PR body — update the version reference from
0.17.0 → 0.17.1to0.17.1 → 0.17.2to reflect the actual change. do-not-mergelabel — if docs: document shell test-helper duplication and exit-code divergence as deliberate #853 has merged and the collision is fully resolved, this label can be lifted.
|
Claude finished @kyle-sexton's task in 44s —— View job Security Review
No security issues found. This PR is a pure documentation and version-metadata change. The four changed files were audited against the full vulnerability checklist:
Checklist — all items clear:
|
Third freshness merge. Resolve source-control plugin.json + CHANGELOG conflicts by composing both sides: keep #1029's [0.18.0] required-sections-scaffold entry, move the worktree-convention SSOT entry to a new [0.18.1] heading, re-bump plugin.json 0.18.0 -> 0.18.1 (one increment past main's current value).
|
Claude finished @kyle-sexton's task in 1m 33s —— View job PR Review
What changed (this synchronize)The branch has been kept current with main via merge commits since prior reviews. The current diff is
CorrectnessNo issues. All added content accurately describes the existing, machine-enforced state of the plugin. Version consistency:
CHANGELOG format: PR body is stale. The description says "This PR bumps SecurityNo concerns. All four changed files contain only inert documentation and version metadata:
CLAUDE.md alignment
SummaryClean, correct, documentation-only PR. Two items before merge:
|
|
Claude finished @kyle-sexton's task in 1m 25s —— View job Security Review
No security issues found. All four changed files were audited against the full vulnerability checklist. This PR is entirely documentation and version metadata.
Full checklist — all items clear:
|
Fourth freshness merge (post usage-limit pause). Resolve source-control plugin.json + CHANGELOG conflicts by composing both sides: keep #1032's [0.19.0] setup/pr-body entries, move the worktree-convention SSOT entry to a new [0.19.1] heading, re-bump plugin.json 0.19.0 -> 0.19.1 (one increment past main's current value).
|
Claude encountered an error after 1s —— View job I'll analyze this and get back to you. |
|
Claude encountered an error after 0s —— View job I'll analyze this and get back to you. |
kyle-sexton
added
needs-human
…layout-doc # Conflicts: # plugins/source-control/.claude-plugin/plugin.json # plugins/source-control/CHANGELOG.md
|
Claude finished @kyle-sexton's task in 1m 18s —— View job PR Review
This is a documentation-only PR that has been through multiple version-bump collision cycles; the content itself has not changed between review rounds. All four files were read against the current diff. What changed
CorrectnessNo issues. Both added blocks accurately describe the existing, machine-enforced policy.
Version consistency: CHANGELOG format: PR body is stale. The description says "bumps SecurityNo concerns. All four files are entirely inert documentation and version metadata:
CLAUDE.md alignment
Minor observation (no action required)
SummaryClean and correct. Two items before merge:
|
|
Claude finished @kyle-sexton's task in 1m 9s —— View job Security Review
No security issues found. This PR is entirely documentation and version metadata. All four changed files were audited against the full vulnerability checklist.
Checklist — all items clear:
|
|
Claude finished @kyle-sexton's task in 51s —— View job Security Review
No security issues found. All four changed files were audited against the full vulnerability checklist. This PR is entirely documentation and version metadata.
Checklist — all items clear:
|
|
Claude finished @kyle-sexton's task in 1m 1s —— View job PR Review
This is a documentation-only PR closing an SSOT gap for worktree conventions. All four changed files were read against the full diff. What changed
CorrectnessNo issues.
Version consistency: CHANGELOG format: PR body is stale: The description still references SecurityNo concerns. All four files are entirely inert documentation and version metadata:
CLAUDE.md alignment
SummaryClean, correct, and appropriately scoped. Two items before merge:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a8783bb714
ℹ️ 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".
…ing 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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017P1vVA8iViUTfQWjA9tgZG
|
Claude finished @kyle-sexton's task in 1m 57s —— View job PR Review
This review covers the full diff ( What changed
Codex P2 finding — addressed correctlyThe Codex reviewer flagged that the previous Commit
This is an accurate, appropriately scoped fix. The claim now matches what the code actually enforces. CorrectnessNo issues.
Version consistency: CHANGELOG format: SecurityNo concerns. All four changed files remain entirely inert documentation and version metadata. No executable content, no new permission surface, no external URLs, no PII, no workflow modifications. CLAUDE.md alignment
Minor note (no action required)The PR body still references SummaryThe Codex P2 finding is addressed correctly and completely. The PR is clean, correct, and appropriately scoped. The |
|
Claude finished @kyle-sexton's task in 1m 12s —— View job Security Review
No security issues found. All four changed files were audited against the full vulnerability checklist. This PR is entirely documentation and version metadata. The latest commit ( Diff summary
Checklist — all items clear
Note on Codex P2 findingThe Codex review flagged that |
1 participant
Summary
Plugin-side deliverable for #401. The retired external prose doc
~/.claude/docs/ghq-layout-sibling-pr-worktrees.md(dotfiles/chezmoi repo) prescribed a stalesibling-at-
ghq-level worktree layout and carried the babysit worktree-exemption policy. This PRcloses the SSOT gap named in the issue: it states, in the plugin itself, that the plugin — not any
external prose doc — is the canonical, sole source for both worktree conventions.
Nothing was actually missing or migrated. Verification (below) confirms the babysit exemption
policy is already fully captured and machine-enforced in the plugin, and that the "Codex-home
root" the issue flags is a per-user
babysit_worktree_rootconfig value, not plugin content —migrating that literal path into a user/machine/org-agnostic plugin would be wrong. This PR
clarifies canonical ownership; it does not restate the retired prose (point-don't-copy).
Fix
plugins/source-control/skills/babysit-prs/reference/worktrees.md— added a statement that thisfile is the canonical, sole source for the ephemeral babysit-worktree exemption, with the
load-bearing rationale a future maintainer could otherwise undo: rooting these worktrees outside
every repository's discoverable tree (plugin data dir by default) keeps ephemeral scratch out of
repository enumeration such as
ghq list; repointingbabysit_worktree_rootback under adiscoverable tree reintroduces that pollution.
plugins/source-control/skills/worktree/SKILL.md— added one sentence stating this skill ownsthe parallel-session external-root convention going forward (the discoverable replacement),
explicitly scoped to the external-root replacement, not the abandoned sibling layout.
Verification
reference/worktrees.mdPolicy alreadydocuments lease-scoped cleanup and "never request global open-PR cleanup" (lines 12-31), and the
operational runbook step 8 in
SKILL.md(line 433) says "Never globally prune open-PRworktrees."
scripts/prune_babysit_worktrees.pylines 189-194 machine-enforce it:--lease-tokenrequires
--pr, and--prune-open-cleanrequires both--prand--lease-token— so noglobal open-PR prune path exists.
babysit_worktree_root(userConfig in.claude-plugin/plugin.json) defaults to theworktrees/subdir of the plugin data dir. Thebabysit skill already migrated its root off
CODEX_HOMEto${CLAUDE_PLUGIN_DATA}(CHANGELOGline 735). Live grep:
CODEX_HOME|\.codex|\.agentsacross the whole babysit skill → zeromatches.
ghq-layout|sibling-pr-worktreeand.claude/docsworktree pointers across the plugin → no plugin reference (the onlyghq listhits are unrelated
repo-hygienetree-batch features)..markdownlint-cli2.jsonc) →0 error(s).per-tool worktree-root map + exemptions as output. Not missed — deferred.
Closes #401
Related
ghq-layout-sibling-pr-worktrees.mdand removal of its pointer from the user'sCLAUDE.md"Reference docs" list happen in the dotfiles/chezmoi repo — not reachable from this worktree.
(feat(source-control): setup writes a self-describing team convention file #1055 →
0.17.1, feat(source-control): configurable pr_body_required_sections scaffold + gate (#975) #1029 →0.18.0, setup skill: offer pr_body_required_sections in interview/write template #1032 →0.19.0, and later main advanced to0.26.2),each requiring a merge-only freshness re-merge and re-bump. PR docs: document shell test-helper duplication and exit-code divergence as deliberate #853 (the last open
source-control PR behind the hold) has merged, so the hold is lifted. Current state bumps
0.26.2 → 0.26.3with the CHANGELOG entry moved to[0.26.3]; everyplugin.json+CHANGELOG.mdconflict was resolved by composing both sides (kept main's entries and newerdescription, re-slotted the worktree-SSOT entry on top).
Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com