Skip to content

📖 docs: explain webhook claim ledger and pending stage recovery - #14975

Merged
hivecommons-hive[bot] merged 2 commits into
hivecommons:v5from
thatguywob:docs/14972-webhook-claim-ledger
Oct 28, 2026
Merged

hivecommons-hive[bot] merged 2 commits into
hivecommons:v5from
thatguywob:docs/14972-webhook-claim-ledger

Conversation

@thatguywob

Copy link
Copy Markdown
Contributor

Closes #14972

Document the pull_request claim-ledger writer alongside the snapshot writers: triggering actions, claim release/merge semantics, persistence, immediate suppression, stage facts and API costs.

Explain the merged-delivery close trigger and per-cycle ledger-to-stage backfill from #14971, explicitly marked pending because that PR is still open against v5. Distinguish that stage repair from the existing scheduled close-on-merge backfill.

Validation: manually checked the descriptions against upstream/v5 and #14971 at commit 36ed2141d952a8c11a67e503678457a94236b89c, including action lists, guards, timeouts, log messages and source paths. Tests not run (docs only); repository instructions reserve tests and docs guards for CI.

— hive: backend=codex


🐝 Hive Agent: contributor | SHA: de64cb1ad

Document pull_request claim writes, their snapshot and stage effects, and the merge trigger and ledger backfill proposed in hivecommons#14971.

Hive-Run: hivecommons#14972
Hive-Plan: docs-currency-webhook-claim-ledger
Hive-Spec: hivecommons#14972#webhook-ledger-documentation
Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 28, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[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 danathar 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:

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

@kubestellar-prow kubestellar-prow Bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Oct 28, 2026
@hivecommons-hive hivecommons-hive Bot added author/clanker A contributor's own hive authored this PR under their login dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 28, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first two sections are accurate and worth landing; I'd split out the third.

Verified against v5 (at de64cb1)

  • Action list (opened…closed) matches src/pkg/github/webhook_pr_claims.go:96-102; the cover subset (opened, reopened, edited, ready_for_review) matches :229-232.
  • ApplyPRDelivery at :175; coverIssuesForWebhookPR at :270, two-minute bound webhookPRCoverTimeout at :237.
  • prClaimsHookFor, both log strings (:34, :39) and the FilterClaimedIssues re-filter (:63) are in src/cmd/hive/webhook_pr_claims.go.
  • runCloseOnMergeSweep is at src/cmd/hive/close_on_merge_sweep.go:99.

Concern — "Merge trigger and ledger-to-stage backfill (pending #14971)": this documents closeOnMergeForDelivery, reconcileLedgerCoverRecords and BackfillCoveredByLedger, none of which exist on v5. It is pinned to a specific commit of an open PR that is currently in mergeable_state=dirty (conflicts), so its shape may still change — and if #14971 is reworked or closed, webhooks.md ships operator-facing text describing behaviour the binary does not have, with nothing to flag the drift. The symbol names also won't be caught by the citation check since they aren't path:line references.

Suggestion: drop that subsection (and the closing "Until that PR lands…" paragraph) from this PR so the verified parts can merge now, and carry the #14971 text inside #14971 itself, where it will land in the same commit as the code and be deleted with it if the PR is abandoned. Alternatively, rebase this PR on top of #14971 once it merges.

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

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether the "Merge trigger and ledger-to-stage backfill (pending #14971)" section of src/docs/webhooks.md should land now, describing #14971 at commit 36ed214 while that PR is still open and conflicted, or be split out and carried by #14971 itself.

Checked the current-state parts of this doc against v5: ClaimLedger.ApplyPRDelivery (src/pkg/github/webhook_pr_claims.go:175), the action set at :98–101 and the cover subset at :231–232, webhookPRCoverTimeout = 2 * time.Minute (:237), coverIssuesForWebhookPR (:270, called from webhook_cache.go:509 inside HandleWebhookEvent), and prClaimsHookFor with both log messages and FilterClaimedIssues (src/cmd/hive/webhook_pr_claims.go:20–63). All of that matches the code; the new "PR claims and issue stages" section reads accurately to me.

The part I can't settle: the "Merge trigger and ledger-to-stage backfill (pending #14971)" subsection documents closeOnMergeForDelivery, reconcileLedgerCoverRecords and BackfillCoveredByLedger, none of which exist on v5 — they are #14971's implementation, pinned to commit 36ed2141d. #14971 is currently dirty (merge conflicts), so its final shape may differ from what this doc states, and the "Until that PR lands…" sentence becomes stale the moment it merges. Two reasonable options: land this now and accept a follow-up edit, or move that subsection into #14971 so docs and code land together. That's a sequencing call for the #14971 author/owner, not a defect in this PR.

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

@hivecommons-hive hivecommons-hive Bot added stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Needs a decision, not a merge:

Head: verdict requires_human @de64cb1, 57/57 checks green, DCO yes, soak 0s of 30m0s.

How to release it:

  • After reading the verdict, a trusted merger can submit a GitHub Approve review for the current head and the lane clears the hold on its next pass; /hive approve replies on a PR are acknowledged but not consumed. An ordinary contributor cannot release their own PR.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

@github-actions

Copy link
Copy Markdown
Contributor

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.

No conflicting open PRs or same-file overlaps were found.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

/hive decision supersede now: adopt #14975 in supersede mode, preserving the author's commits and sign-off; do not wait for the grace deadline

Rationale: the contributor is offline; adoption in supersede mode keeps the work moving (#13975).

Decided by the hive at @clubanderson's request as the owner's delegate under the owner-delegate policy (rule contributor-offline).

@hivecommons-hive hivecommons-hive Bot added the adoption/supersede Owner-delegate request: adopt now in supersede mode label Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@thatguywob the hive has adopted this PR (stage/074-adopted-by-hive): your hive has been offline since the nudge. It is being finished as #14980, which carries your commits (and sign-off) unchanged; the hive will rebase and fix CI there. This PR is closed automatically once #14980 merges. If you would rather finish it yourself, push a new head here and say so on #14980.

@hivecommons-hive hivecommons-hive Bot removed the adoption/supersede Owner-delegate request: adopt now in supersede mode label Oct 28, 2026
@hivecommons-hive hivecommons-hive Bot added stage/074-adopted-by-hive Contributor PR adopted: author unavailable after red CI; the hive is finishing it (takeover path) stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act and removed stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue stage/074-adopted-by-hive Contributor PR adopted: author unavailable after red CI; the hive is finishing it (takeover path) labels Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@thatguywob this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • build (linux/arm64, true, true, 75)
  • build (linux/arm64
  • true
  • 75)
  • merge

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Your relay could not take this as a fix-pr task (Hub is not the active polling slot); the hive will retry it from your relay fix queue.

Merge current v5 so the documented merge trigger and ledger-to-stage backfill ship with their implementation from hivecommons#14971. Remove the now-stale pending language.

The reported ARM64 build was canceled by a newer run of the closed adoption PR hivecommons#14980; no compiler or dependency failure was reported. Push this updated head to the original PR branch for fresh CI.

Signed-off-by: thatguywob <thatguywob@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act labels Oct 28, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed — no findings from this perspective.

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

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed — no findings from this perspective.

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

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed (intent-alignment, delta de64cb1 → 792066b) — previous finding resolved.

  • ✅ Fixed: the "pending / pinned to unmerged #14971" wording is gone from src/docs/webhooks.md; #14971 is now in v5 (294d0c7) and the new "Merge trigger and ledger-to-stage backfill" section matches head code (src/cmd/hive/webhook_pr_claims.go:23-84, src/cmd/hive/main.go:7220,10138-10152, src/pkg/github/stage_ledger_backfill.go:42-82, src/pkg/github/webhook_pr_claims.go:96-102,229-237).
  • ℹ️ Advisory: the PR title ("…and pending stage recovery") and body ("explicitly marked pending because that PR is still open") no longer describe the diff. Consider retitling to e.g. 📖 docs: explain webhook claim ledger and merge-triggered stage recovery before squash so the commit message isn't stale.

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

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed (style) at 792066b5c — prior finding resolved: the "pending #14971" caveat is gone from src/docs/webhooks.md:71-88 now that #14971 is on v5 (294d0c7), and every symbol the section cites exists at head (closeOnMergeForDelivery / closeOnMergeDeliveryTimeout = 2 * time.Minute in src/cmd/hive/webhook_pr_claims.go:62,84; reconcileLedgerCoverRecords called unconditionally after the SkipOptional guard in src/cmd/hive/main.go:7217-7220).

One low, non-blocking gap between body and diff: the PR description still says the section is "explicitly marked pending because that PR is still open against v5" and cites commit 36ed2141d. Since the body becomes the squash commit message, please update it to match the diff, e.g.:

Explain the merged-delivery close trigger and per-cycle ledger-to-stage backfill from #14971 (now merged into `v5`), distinguishing that stage repair from the existing scheduled close-on-merge backfill.

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

@hivecommons-hive hivecommons-hive Bot added stage/095-pre-merge-soak Lane admitted; the pre-merge soak window is running before the merge is attempted stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head stage/095-pre-merge-soak Lane admitted; the pre-merge soak window is running before the merge is attempted labels Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

stage 095-pre-merge-soak → 060-reviewed: required-check-pending:Sign-off survives the squash

@hivecommons-hive hivecommons-hive Bot added stage/095-pre-merge-soak Lane admitted; the pre-merge soak window is running before the merge is attempted stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) and removed stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) stage/095-pre-merge-soak Lane admitted; the pre-merge soak window is running before the merge is attempted labels Oct 28, 2026
@hivecommons-hive hivecommons-hive Bot added the stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) label Oct 28, 2026
@hivecommons-hive hivecommons-hive Bot added stage/095-pre-merge-soak Lane admitted; the pre-merge soak window is running before the merge is attempted and removed stage/060-reviewed Review swarm verdict approve; a gate is still pending (CI running, soak not started) labels Oct 28, 2026
@hivecommons-hive
hivecommons-hive Bot merged commit 92df64b into hivecommons:v5 Oct 28, 2026
86 of 97 checks passed
@hivecommons-hive

Copy link
Copy Markdown
Contributor
Evidence bundle `#14975792066b` sha256:dba14c1ebe644f4859deea8a1ab7b90b660e1f32390ca8ef436fe2c663748da8 — download from the dashboard or `hivectl review evidence #14975`.

1 similar comment
@hivecommons-hive

Copy link
Copy Markdown
Contributor
Evidence bundle `#14975792066b` sha256:dba14c1ebe644f4859deea8a1ab7b90b660e1f32390ca8ef436fe2c663748da8 — download from the dashboard or `hivectl review evidence #14975`.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Merged by hive contributor-lane auto-merge: CI green for ≥30m, reviewer verdict approve, @thatguywob holds the trusted tier in this hive's contributor registry.

@hivecommons-hive hivecommons-hive Bot removed role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/095-pre-merge-soak Lane admitted; the pre-merge soak window is running before the merge is attempted labels Oct 28, 2026
hivecommons-hive Bot pushed a commit that referenced this pull request Oct 28, 2026
…als out of the merge gate (#15011)

* Close superseded hive PRs automatically and re-stage adopted originals out of the merge gate

A hive-authored PR whose closing targets are all closed, one of them by a
different merged PR, and whose head conflicts with the base (or whose files
that PR already covers) is now closed by the hive itself as hive/superseded
with a notice naming the superseding PR: in the self-authored auto-merge
lane before any review is dispatched, in the supersession sweep when the
rebase is refused for a conflict, and in close-on-merge of the superseding
PR. New knob governor.auto_close_superseded (default on); human-authored PRs
are never auto-closed.

A contributor PR adopted in supersede mode leaves stage/085-needs-decision
in the adopting pass when the park was only the review swarm's
requires_human verdict, renders in the CI/Review column with an
'Adopted -> #N' pill, and the duplicate-fix sweep no longer closes the
superseding App PR as a duplicate of the PR it supersedes.

Evidence: #14965 (closed by #14957 for #14952), #14975 -> #14980,
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
#14947 -> #14977.

* Move changelog fragment to repo-root changelog.d

Signed-off-by: Andrew Anderson <andy@clubanderson.com>

---------

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/clanker A contributor's own hive authored this PR under their login dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Review backlog (docs-currency): webhooks.md never documents the pull_request→claim-ledger write or the new merge trigger / ledger backfill

1 participant