repo: per-change version bump + top-insert CHANGELOG serialize concurrent same-plugin PRs (conflict by construction)

[kyle-sexton]

Lane: work (issue-execution loop, up to 2 concurrent per-issue subagents)
Category: operational (throughput friction)

Triggering example

Each plugin follows a per-change convention: every PR bumps that plugin's .claude-plugin/plugin.json version AND prepends a CHANGELOG.md entry. Two independent issues on the SAME plugin therefore both edit the version line (same line) and both insert at the top of the CHANGELOG — a guaranteed textual conflict. In this session:

• discovery: discovery: live absolute project-root injected into skill context can bleed into EXPLORE.md artifacts #409/PR#458 bumped 0.7.0 -> 0.7.1; discovery: setup skill cites marketplace-repo ADR by bare path — dead reference in installed plugin form #407/PR#461 then had to bump 0.7.0 -> 0.7.2 and note it stacks on fix(discovery): keep absolute project root out of persisted EXPLORE.md #458 with an expected rebase.
• repo-hygiene: fix(repo-hygiene): git-tree-reset runs clean -fdx even when reset --hard failed (partial destructive op) #394/PR#460 occupies the version file; siblings fix(repo-hygiene): git-tree-reset aborts with fatal: ambiguous argument '@{u}' on branches with deleted upstream #393/fix(repo-hygiene): git-tree-reset prints Applied* success lines even when git commands failed #395/fix(repo-hygiene): git-tree-reset dry-run doesn't validate @{u}, so dry-run success != apply success #396/feat(repo-hygiene): multi-repo clean/tree mode with skip-list + dirty guard #397 (which edit the same git-tree-reset.sh) must queue behind its merge rather than run in parallel.

Net effect: the "up to 2 concurrent subagents" model collapses to serialized-per-plugin whenever the ready queue clusters on one plugin, and the second PR to merge always needs a rebase on the version/CHANGELOG lines.

Observed vs expected

• Observed: Per-change version bump + top-insert CHANGELOG makes concurrent same-plugin PRs conflict by construction. Orchestrator must track plugin "occupancy" and avoid parallel same-plugin picks, reducing effective concurrency.
• Expected: Concurrent PRs on the same plugin should not conflict on bookkeeping-only lines.

Suggested fix (options)

1. Move version bumping to merge time (release step / CI) instead of per-PR, so PR branches never touch plugin.json.
2. Use a CHANGELOG fragment directory (e.g. changelog.d/<pr>.md, towncrier-style) assembled at release, so entries never collide.
3. Keep per-PR bumps but document the occupancy rule so pickers serialize same-plugin work deliberately.
   Recommend (2) as the modern low-friction fix; (1) if a release step already exists.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human (repo release-process design). Per-PR version bump (plugin.json) + top-insert CHANGELOG.md makes concurrent same-plugin PRs conflict by construction, collapsing the "2 concurrent subagents" model to serialized-per-plugin. Three options: (1) move version bump to merge/release CI so PR branches never touch plugin.json; (2) changelog.d/<pr>.md fragment dir (towncrier-style) assembled at release; (3) keep per-PR bumps + document an occupancy rule so pickers serialize deliberately. Repo-infrastructure decision (affects the whole marketplace's concurrency). Reporter recommends (2). Priority: medium.

[kyle-sexton]

Maintainer decision (2026-07-19, batch-approved; relayed by planning session).

Merge-time bump + CHANGELOG generation. A CI job on merge to main detects changed plugin(s), derives the semver level from the Conventional-Commits squash subject (pr-title enforcement + squash-subject=title already guarantee the input), bumps plugin.json, prepends the CHANGELOG entry, and commits back. PR branches stop touching both bookkeeping surfaces — removes the collision class entirely (it bit twice today: #452/#456 both 0.9.1, #453/#457 both 0.7.1).

Implementation notes from the decision brief:

• chore:/docs: still bump (patch) — the version is the marketplace update-cache key, an unbumped plugin never delivers.
• Multi-plugin PRs fan out like the existing lib-bump gate; add a self-skip guard on the bot's own bump commit.
• Push-to-main identity: Actions GITHUB_TOKEN or a dedicated App — independent of source-control:babysit-prs: gh-bot.sh bot token generation fails, worker writes fall back to personal identity #450's babysit identity.
• Per-PR bumping in lane/skill instructions retires when this lands.
• Placement check (standards): reusable-execution logic belongs in melodic-software/ci-workflows per the cross-repo ownership convention — implementer resolves repo-local wrapper vs reusable workflow against the standards source, not by default.
• Changelog-fragment (towncrier) approach REJECTED: no release boundary exists in this continuous-delivery model to assemble at.
• Interim (already active): same-plugin PRs serialize; work-lane treats same-plugin issues as dependent.

[kyle-sexton]

This was generated by AI during triage. · Category: operational (throughput friction) · Priority: priority: high (week 2nd-priority: pipeline throughput). Routed needs-human + wayfind: design.

Repo state verified

Inspected every workflow in .github/workflows/ — ci.yml, claude-review.yml, do-not-merge.yml, link-check.yml, pr-issue-linkage.yml, pr-title.yml — plus scripts/ and the repo's tags/releases.

• No release-time assembly exists. No release/version/changelog workflow, no git tags, no GitHub releases. Consumers install from the repo at main, so a merged PR's plugin.json version is the released version — merge is the only "release" moment.
• Existing automation enforces the opposite of assembly. ci.yml's hook-utils-sync job runs scripts/sync-hook-utils.sh --check-bump, which fails the PR if a shared lib changed but a carrying plugin's plugin.json version did not. Per docs/MIGRATION-PLAYBOOK.md ("Version pinning and update delivery"), the version bump is the only delivery vehicle — the version is the update cache key, so an unbumped plugin never delivers its change. Version bumping is load-bearing delivery, not mere bookkeeping.
• No fragment tooling exists (no towncrier, no changelog.d); each plugin hand-maintains a Keep-a-Changelog CHANGELOG.md with top-insert entries.

Why this is needs-human, not a defaultable fix

The acceptance criterion requires both collision lines to stop colliding. The issue's recommended option (2), a changelog.d fragment directory, fixes only the CHANGELOG top-insert — it leaves the plugin.json version-line collision entirely untouched. The issue's own recommendation is incomplete against its own acceptance criterion.

The version line can stop colliding only if version computation leaves the PR for an assembly step — option (1). But there is no assembly moment to attach it to, and standing one up would (a) build a release pipeline that does not exist, (b) rework the --check-bump gate, and (c) reverse the documented "a version bump in plugin.json is the only delivery vehicle / consumers update on bumps" model in docs/MIGRATION-PLAYBOOK.md and CLAUDE.md — delaying delivery from per-merge to per-batch. That is a product-model decision (release cadence + delivery semantics) a human must own.

Option (3), the occupancy rule, is the only autonomously reachable option, but it prevents concurrency rather than removing the conflict — so it cannot satisfy the acceptance criterion, and defaulting a workaround needs explicit approval. No option is safely defaultable.

Recommended direction (for the human to ratify)

Combine both halves into one assembly step (towncrier's actual model):

1. changelog.d/<pr>.md fragments, each carrying a typed bump marker (patch / minor / major). Two concurrent PRs add two distinct files — no shared line.
2. PR branches stop touching plugin.json version and CHANGELOG.md. An assembly step consumes the pending fragments, computes the next semver from the highest bump marker, writes plugin.json, prepends CHANGELOG.md, and deletes the consumed fragments.

The fork the human must decide (different blast radius):

• Maintainer-run / scheduled assembly (a scripts/ tool like the existing generate-catalog.mjs) — batches releases per plugin, no bot writes to main, but changes delivery from per-merge to per-batch.
• Merge-triggered bot that pushes the assembled bump back to main — preserves per-merge delivery but touches branch protection and needs a push identity.

Both require reworking --check-bump (it must assert a fragment exists, not a version diff).

Behavioral contract (target state)

• PR branches never edit plugin.json version or CHANGELOG.md; authors add one changelog.d/<pr>.md fragment with a bump marker.
• Version + changelog assemble exactly once, at the chosen assembly moment, from the accumulated fragments — never on a PR branch.
• The bump gate verifies fragment presence instead of a version-line diff.

Acceptance criteria

• Two concurrent PRs on the same plugin touch zero shared lines (distinct fragment files; neither edits plugin.json or CHANGELOG.md) and merge in either order with no rebase on bookkeeping lines.
• Assembly produces the correct semver and a coherent changelog from N fragments.
• CI still fails a change that ships without its delivery marker (fragment), preserving the "no silent undelivered change" invariant.

Migration note

The current per-PR convention is documented in docs/MIGRATION-PLAYBOOK.md ("Version pinning and update delivery", the per-plugin changelog rule, and rule 10 "Version") and in CLAUDE.md ("Versioned"). Both assert the version bump is the delivery cache key — any move to batched assembly must update these in lockstep and reconcile the --check-bump gate, or delivery semantics silently drift. If the human prefers option (3) as an interim, document the same-plugin occupancy rule in the work-lane orchestration convention and state explicitly that it does not meet the acceptance criterion (it serializes rather than de-conflicts).