You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
repo: per-change version bump + top-insert CHANGELOG serialize concurrent same-plugin PRs (conflict by construction) #464
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:
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)
Move version bumping to merge time (release step / CI) instead of per-PR, so PR branches never touch plugin.json.
Use a CHANGELOG fragment directory (e.g. changelog.d/<pr>.md, towncrier-style) assembled at release, so entries never collide.
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.
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.
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.
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.
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.jsonversionis 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):
changelog.d/<pr>.md fragments, each carrying a typed bump marker (patch / minor / major). Two concurrent PRs add two distinct files — no shared line.
PR branches stop touching plugin.jsonversion 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.jsonversion 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).
Gap-hunt input (control tower 7/19): add GitHub-native merge queue to the option set for concurrent same-plugin PR serialization — batching multiple PRs into one CI run with bisect-on-failure, scoped lanes so unrelated-plugin PRs don't serialize behind each other (docs.github.com merge-queue). Mechanism fits the version-bump collision class exactly (today's #489 was this class again). Vendor throughput multipliers (2-5x) are marketing-reported — evaluate on mechanism, not numbers.
Lane: work. Parking per rule 7 (decision the issue doesn't answer) — this rewrites a repo-wide convention that other lane rules already reference as pending ("until #464 lands"), so it's contract-shaped and hard-to-reverse, not a pick-and-implement.
Question: which mechanism replaces per-PR version-bump + top-insert CHANGELOG?
RECOMMENDED: Option 2 — CHANGELOG fragment directory (changelog.d/<pr>.md, towncrier-style), version bump deferred to release/merge time.
Pros: entries never collide (independent files); version bump moves off the PR hot path entirely, so same-plugin PRs stop conflicting by construction.
Cons: needs a release-time assembly step (script to compile fragments into CHANGELOG.md + bump version) that doesn't exist yet; every plugin's contributor-facing docs need the new file-per-PR convention documented.
Option 1 — version bump at merge/release time only.
Pros: simplest; no fragment-file convention to teach.
Cons: doesn't solve the CHANGELOG top-insert collision on its own; still needs some mechanism for the CHANGELOG entry itself (fragment dir or serialize), so it's really Option 2 plus this, not an alternative to it.
Cons: is the status quo the lane already works around (rule 3 same-plugin serialization) — codifying it doesn't fix the throughput loss, it just documents the workaround as permanent.
Moving to status: needs-decision and off status: ready (a ready item with 3 unresolved design options is a triage-label defect per rule 4b's spirit — flagging in #502 telemetry). No WIP branch — no code changes proposed pending the design call.
Every one resolved identically: take the higher version, stack both CHANGELOG entries newest-first. Mechanical, no judgment required — which is what makes it a serialization cost rather than a real merge.
What the data adds
The conflict rate scales with plugin heat, not PR size.session-flow took two hits in a few hours. A PR touching a hot plugin loses this race repeatedly regardless of what it changes.
The cost compounds. Each rebase forces a re-verification pass (edits intact, gates re-run, orphan sweeps) plus a force-push, and the force-push re-triggers the full CI suite. Three rebases meant roughly three full CI runs for one PR's content.
It interacts badly with auto-merge. Auto-merge was armed after rebase 2 and never fired, because main moved again before the checks cleared. Each new conflict re-opens the exposure window the arm was meant to close.
One near-miss worth noting. During rebase 1, chore(session-flow): guard the session-id !-injection with a fallback #1304 had independently shipped the same #1060 injection-guard fix this PR carried. git rebase correctly auto-dropped that commit as already-upstream — but a resolver taking "ours" wholesale on the CHANGELOG would have kept a duplicate bullet describing a fix already documented under a different version.
Not a new proposal
Recording evidence only; the direction stays this issue's own needs-decision. Worth noting that the resolution rule is fully mechanical (higher version wins; entries stack newest-first), so this is a strong candidate for scripting or a merge driver rather than reasoning — the deterministic-work-execution convention applies.
This was generated by AI (decide lane, operator-authorized frontier decision pass — human gates decided, not skips).
Decide brief — consolidated into #1746, the sharper tracker for the same root cause
Decision: close as duplicate/consolidated. This issue and #1746 describe one defect: the per-change version bump + top-insert CHANGELOG convention computes the next version from main rather than reserving it, so concurrent same-plugin branches conflict by construction. One decision should be made once, in one place.
#1746 survives because it carries the stronger evidence and the stricter failure mode: a measured 7-branch collision snapshot with reproduction script, plus the silent backwards-bump hazard (merge order can land main at 0.26.0 and then merge a 0.25.x behind it clean — non-monotonic version history with nothing rejecting it), which this issue's serialization framing does not capture.
Carrying this issue's contribution over so it is not lost: the remedy option space recorded here — (1) bump at merge time (CI/release step) instead of per-PR, (2) conflict-free changelog formats (per-entry files à la towncrier), (3) orchestrator-side same-plugin occupancy scheduling — plus the observed cost data (PR #1296 rebased three times in one session, all three conflicts pure bookkeeping, zero content conflicts) are the decision inputs for whoever settles #1746.
Activity
kyle-sexton commentedon Jul 19, 2026
Triage → needs-human (repo release-process design). Per-PR version bump (
plugin.json) + top-insertCHANGELOG.mdmakes 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 touchplugin.json; (2)changelog.d/<pr>.mdfragment 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 commentedon Jul 19, 2026
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:
kyle-sexton commentedon Jul 19, 2026
This was generated by AI during triage. · Category: operational (throughput friction) · Priority:
priority: high(week 2nd-priority: pipeline throughput). Routedneeds-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— plusscripts/and the repo's tags/releases.main, so a merged PR'splugin.jsonversionis the released version — merge is the only "release" moment.ci.yml'shook-utils-syncjob runsscripts/sync-hook-utils.sh --check-bump, which fails the PR if a shared lib changed but a carrying plugin'splugin.jsonversion did not. Perdocs/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.changelog.d); each plugin hand-maintains a Keep-a-ChangelogCHANGELOG.mdwith 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.dfragment directory, fixes only the CHANGELOG top-insert — it leaves theplugin.jsonversion-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-bumpgate, and (c) reverse the documented "a version bump inplugin.jsonis the only delivery vehicle / consumers update on bumps" model indocs/MIGRATION-PLAYBOOK.mdand 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):
changelog.d/<pr>.mdfragments, each carrying a typed bump marker (patch/minor/major). Two concurrent PRs add two distinct files — no shared line.plugin.jsonversionandCHANGELOG.md. An assembly step consumes the pending fragments, computes the next semver from the highest bump marker, writesplugin.json, prependsCHANGELOG.md, and deletes the consumed fragments.The fork the human must decide (different blast radius):
scripts/tool like the existinggenerate-catalog.mjs) — batches releases per plugin, no bot writes tomain, but changes delivery from per-merge to per-batch.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)
plugin.jsonversionorCHANGELOG.md; authors add onechangelog.d/<pr>.mdfragment with a bump marker.Acceptance criteria
plugin.jsonorCHANGELOG.md) and merge in either order with no rebase on bookkeeping lines.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-bumpgate, 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).kyle-sexton commentedon Jul 19, 2026
Gap-hunt input (control tower 7/19): add GitHub-native merge queue to the option set for concurrent same-plugin PR serialization — batching multiple PRs into one CI run with bisect-on-failure, scoped lanes so unrelated-plugin PRs don't serialize behind each other (docs.github.com merge-queue). Mechanism fits the version-bump collision class exactly (today's #489 was this class again). Vendor throughput multipliers (2-5x) are marketing-reported — evaluate on mechanism, not numbers.
29 remaining items
kyle-sexton commentedon Jul 22, 2026
Lane: work. Parking per rule 7 (decision the issue doesn't answer) — this rewrites a repo-wide convention that other lane rules already reference as pending ("until #464 lands"), so it's contract-shaped and hard-to-reverse, not a pick-and-implement.
Question: which mechanism replaces per-PR version-bump + top-insert CHANGELOG?
RECOMMENDED: Option 2 — CHANGELOG fragment directory (
changelog.d/<pr>.md, towncrier-style), version bump deferred to release/merge time.Option 1 — version bump at merge/release time only.
Option 3 — keep per-PR bumps, document + enforce occupancy (serialize same-plugin picks).
Moving to
status: needs-decisionand offstatus: ready(a ready item with 3 unresolved design options is a triage-label defect per rule 4b's spirit — flagging in #502 telemetry). No WIP branch — no code changes proposed pending the design call.fix(repo-hygiene): destructive-guard fail-open on Windows — shell-for…
feat(repo-hygiene): fleet batch mode for the caches/build/git/all tie…
feat(repo-hygiene): stash audit, worktree/no-upstream branch classes,…
feat(work-items): wire dispatch concurrency cap, drop inert batch cap (…
kyle-sexton commentedon Jul 25, 2026
Three fresh data points for this issue from a single session, all on one PR (#1296,
session-flow+implementation).PR #1296 was rebased three times in one session. Every conflict was pure version/CHANGELOG bookkeeping — zero content conflicts across all three:
session-flow0.15.0 -> 0.15.1)plugin.jsonversion + CHANGELOG top-insertimplementation0.9.0 -> 0.9.1)plugin.jsonversion + CHANGELOG top-insertsession-flow0.15.1 -> 0.15.2)plugin.jsonversion + CHANGELOG top-insertEvery one resolved identically: take the higher version, stack both CHANGELOG entries newest-first. Mechanical, no judgment required — which is what makes it a serialization cost rather than a real merge.
What the data adds
session-flowtook two hits in a few hours. A PR touching a hot plugin loses this race repeatedly regardless of what it changes.#1060injection-guard fix this PR carried.git rebasecorrectly auto-dropped that commit as already-upstream — but a resolver taking "ours" wholesale on the CHANGELOG would have kept a duplicate bullet describing a fix already documented under a different version.Not a new proposal
Recording evidence only; the direction stays this issue's own
needs-decision. Worth noting that the resolution rule is fully mechanical (higher version wins; entries stack newest-first), so this is a strong candidate for scripting or a merge driver rather than reasoning — the deterministic-work-execution convention applies.Origin: PR #1296 (handoff save-point taxonomy restructure), 2026-07-25.
refactor(session-flow): restructure the handoff save-point taxonomy (#…
feat(discovery)!: dispatch explore and research to purpose-built suba…
kyle-sexton commentedon Aug 12, 2026
This was generated by AI (decide lane, operator-authorized frontier decision pass — human gates decided, not skips).
Decide brief — consolidated into #1746, the sharper tracker for the same root cause
Decision: close as duplicate/consolidated. This issue and #1746 describe one defect: the per-change version bump + top-insert CHANGELOG convention computes the next version from
mainrather than reserving it, so concurrent same-plugin branches conflict by construction. One decision should be made once, in one place.#1746 survives because it carries the stronger evidence and the stricter failure mode: a measured 7-branch collision snapshot with reproduction script, plus the silent backwards-bump hazard (merge order can land
mainat0.26.0and then merge a0.25.xbehind it clean — non-monotonic version history with nothing rejecting it), which this issue's serialization framing does not capture.Carrying this issue's contribution over so it is not lost: the remedy option space recorded here — (1) bump at merge time (CI/release step) instead of per-PR, (2) conflict-free changelog formats (per-entry files à la towncrier), (3) orchestrator-side same-plugin occupancy scheduling — plus the observed cost data (PR #1296 rebased three times in one session, all three conflicts pure bookkeeping, zero content conflicts) are the decision inputs for whoever settles #1746.