[clubanderson]

Fixes #15289

Incident: on #15219 (author via clanker, CONFLICTING) Let hive decide adopted in supersede mode, saying "the author's hive hasn't been connected", although #15202 had already been fixed and merged 2.7h earlier by #15240.

Fix — a decision ladder for contributor PRs, evaluated in order, each rung with its own slug, glossary entry, toast text and tracker event:

1. already-fixed — the linked issue is closed by a merged PR (closedByPullRequestsReferences) or a merged PR declares it supersedes this one (detectDeclaredSupersession, reused) → close as superseded with a courteous comment naming the merging PR + sha; never adopt. Recommend-only when the repo is paused or the author is a person. No new write surfaces (ratchet baseline unchanged).
2. mergeable-as-is — mergeable, CI green, no DCO/reporter hold → approve, merge gate takes it.
3. rebase-then-merge — recorded as ruled-out with a pointer to 🐛 Activity Monitor: Rebase, then merge as maintainer; fixer owns parked conflicting PRs; dismiss self-inflicted changes_requested #15104 until that lands.
4. return-to-contributor — the author's clanker or hive is connected or has picked the rework up (✨ tracker: rework pickup signal on the waiting-on chip #15281 signal) → fix list back to them, no adoption.
5. contributor-offline → adopt-supersede, last resort; never for owner/human PRs.

Each decision logs one structured line with ruled_out, the toast says why ("Closed as superseded: #15202 already fixed by #15240 (25de3ba)."), and the decide API exposes decision.ladder {decision, reason, ruled_out[]}.

Wording: "the author's clanker" when the author label is author/clanker, "the author's hive" only when a connected hive is known, otherwise "the author". The static glossary line is now neutral; the decision itself names which.

Tests: TestDecideLadder table (exact #15219 scenario, mergeable-as-is, offline → adopt, owner never adopted, paused, person-authored, rework pickup), TestAuthorWording, dashboard end-to-end TestDelegatedAlreadyFixedClosesInsteadOfAdopting / TestDelegatedOfflineClankerAdoptsWithClankerWording. No time.Sleep.

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR	Title	Relation	Files
#15321	🐛 fix(dashboard): pass open resolver in linked-progress test so v5 compiles	same files	src/pkg/dashboard/stage_tracker_linked_progress_test.go
#15304	🌱 docs: split api-reference into per-area files	CONFLICT	src/docs/api-reference.md
#15282	📖 docs: make Hive guides easier to follow	same files	src/docs/labels-and-control-signals.md
#15310	🐛 fix: share delegated capability-gap inference with blocker ledger	same files	src/pkg/delegatedecision/policy.go
#15316	📖 docs: clarify delegated issue park diagnosis	same files	src/pkg/dashboard/api_repo_item_decide_delegated_test.go
#15307	🐛 fix: refuse workflow-changing fork rebase follow-through	CONFLICT	src/pkg/dashboard/api_repo_item_decision_test.go
#15303	🌱 refactor: split API reference into area files	same files	src/docs/api-reference.md

[hivecommons-hive]

@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

[hivecommons-hive]

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

• test (dashboard 4/4)
• test (dashboard shuffle 3/3)

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

[hivecommons-hive]

Another agent tried to open a PR from scanner/fix-15289, but this PR already closes #15289. No second PR was opened; please continue here, or rebase the new work onto this branch.

[hivecommons-hive]

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

• the branch conflicts with the base and needs a rebase

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

[hivecommons-hive]

Read the ladder, the supersession detector and the dashboard executor against the tree at dbe4223. The ordering fix is correct; one small text issue, and the branch currently conflicts with v5 (mergeable_state=dirty).

Verified correct

• src/pkg/delegatedecision/policy.go (decidePR): the ladder sits after HivePolicyChange / OwnerOnly / sentinel / decideCompeting, so rung 1 cannot close a PR those gates own. Rung 2 only fires on a head with no blockers, and the pre-existing workflow-path rule only fires with blockers, so the two never compete.
• src/pkg/dashboard/delegated_ladder.go:34-37: a DetectMergedSupersession error aborts the decision rather than falling through to adopt — the right failure direction for this incident.
• src/pkg/github/pr_merged_supersession.go:62-70: the closer is re-read and must actually be merged before the PR is treated as superseded, so a stale closedByPullRequestsReferences cannot close an open PR.
• Removed adopt-now / contributor-offline rules are reproduced verbatim as rung 5, so behaviour below the new rungs is unchanged.

Finding (low) — src/pkg/delegatedecision/ladder.go:264: the note posted to the contributor ends "Your work is credited on the issue." The executor for ActionCloseDuplicate (src/pkg/dashboard/api_repo_item_decide_delegated.go:818-836) only comments on the PR and calls CloseSupersededPR → labelAndCloseSupersededPR; neither writes anything to the issue, and I found no credit step on that path. A contributor who follows the link will find nothing. Either drop the sentence or add the credit comment on c.Issue (and skip it when c.Issue == 0, the declared-supersession case, where there is no issue to credit).

Body vs diff: matches, including the rebase-then-merge rung being ruled-out only. Needs a rebase onto v5 before it can merge.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

stage 080-awaiting-merge-admission → 050-review-pending: review-gate:no-review-bundle

[hivecommons-hive]

Reviewed — no findings from this perspective.

— hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Correctness re-review at e329aed (delta since dbe4223: rebase onto v5 + stage_tracker_linked_progress_test.go signature fix — both clean; stageTrackerResolveLinkedPRs(items, nil) is nil-guarded at src/pkg/dashboard/stage_tracker.go:2996).

• ✅ Branch conflicts with v5 — fixed (now MERGEABLE).
• ❌ Still present — src/pkg/delegatedecision/ladder.go:268: the close note tells the contributor "Your work is credited on the issue.", but ActionCloseDuplicate only comments on and closes the PR (src/pkg/dashboard/api_repo_item_decide_delegated.go:819-835); nothing writes to the issue, which is already closed by the merging PR. The promise is never kept.

	note := fmt.Sprintf("Thank you for this PR. %s, so there is nothing left for it to deliver and the hive is closing it as superseded; this note stays on the PR as the record of your work.", strings.ToUpper(text[:1])+text[1:])

— hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

[hivecommons-hive]

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

• the review swarm requested changes

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.