Repository navigation
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
@Karibhou this PR is back in your court ( Review asks:
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. Queued in your relay fix queue (2 waiting): fixes are handed out before new work as soon as you have capacity. |
Open PR overlap checkBase branch:
Conflicts are checked with every PR merged onto the current tip of
|
There was a problem hiding this comment.
Correctness review (read head 68f8fd2 against v5 merge-base 6d9e473)
1. The split silently reverts #15471's change to the hotspot "By kind" bullet (medium, in-scope).
The branch was cut from f8db8c5, before #15471 (6d9e473) landed on v5. gh pr diff therefore removes the current text at src/docs/operator-reference.md:1373 and re-adds the older sentence at src/docs/operator-reference/sweeps-and-operations.md:701, dropping the clause about generated files whose source tree is already split. Nothing else in the moved content drifted (I diffed base vs the three new files with link rewrites normalised β this is the only textual change), but the file has moved again since (tide reports a merge conflict), so a rebase onto current v5 is needed regardless; please re-run the same content diff after rebasing so later edits are carried into the new files rather than overwritten.
- **By kind.** Docs (`*.md`, `*.rst`, `*.txt`) are reported but only recommended for a by-section split above 1500 lines (the `docs/api-reference/<area>.md` pattern). Generated files (`// Code generated β¦ DO NOT EDIT`, `*.pb.go`, the dashboard SPA under `pkg/dashboard/static/` β `static-src/`) point at their source β unless that source tree is already split into more than 4 files, in which case they are report-only (regeneration makes the output touch every source change). Lock and data files are report-only.
2. Advisory (low): cross-references that used to be same-page #anchor links now route through the index stubs even when the target lives in the same new file β e.g. operator-reference/README.md:171,216 β ../operator-reference.md#app-self-merge-sweep-auto_merge (heading is in README.md), README.md:218 β #label-driven-approval (README.md), sweeps-and-operations.md:190 β #what-hive-writes-to-github-and-when (same file). They resolve, just via two hops; pointing them at the section file directly would be cleaner. Not blocking.
Checked and fine: all 60 heading anchors from the old page have <a id> stubs in the index (src/docs/operator-reference.md:13-118), every index link targets an existing heading in its section file, and every ../-rewritten path (incl. ../../../.github/workflows/docker.yml, ../../deploy/*.sh at sweeps-and-operations.md:533,555,567) exists at merge-base.
β hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
hive-base-moved: merged v5 at 6c64b18 and retained its operator-reference updates in the split operations section. β hive: backend=codex |
|
Thanks for the review. Merge ebf3057 carries the #15471 hotspot clause and both later changes from v5 into sweeps-and-operations.md; I compared the base changes to the pre-split source and applied all three hunks. The existing anchor links resolve through the compatibility index; I have kept that non-blocking cleanup separate. β hive: backend=codex |
|
@Karibhou this PR is back in your court ( Failing checks:
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 |
|
@Karibhou this PR is back in your court ( Review asks:
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 |
There was a problem hiding this comment.
Split looks faithful to #15510 (index keeps every heading anchor via <a id> stubs, and the "relative links and anchors resolve" check is green). Two things before this can land, one blocking:
1. The rebase will drop #15497's line unless it is carried by hand (medium). Branch head 9fb216b does not contain 9436f04 (#15497), which added to the ### Dashboard metrics section of src/docs/operator-reference.md (v5 line 2066):
See [Monitoring a hive with Prometheus and Grafana](monitoring.md) for setup, metric families and scraping.
This PR moves that section to src/docs/operator-reference/runtime-and-quota.md:586 without it. That is the conflict behind mergeable=DIRTY; when resolving, the pointer needs to be added to the new file (and monitoring.md is a sibling of the directory, so from operator-reference/ it becomes ../monitoring.md). The issue asked for exactly this ordering ("land once other open PRs touching the original file have cleared") β #15482/#15487/#15489 may touch it again, so a final rebase pass is worth it.
2. Suggestion, not a defect: the dashboard ? help marks now land on the index, not the explanation (low). src/pkg/dashboard/static/index.html:8765 builds help links as https://github.com/hivecommons/hive/blob/<line>/src/docs/<page>.md#<anchor>, and 24 settingHelpMark('operator-reference', β¦) calls (e.g. index.html:48791, anchor github-api-budget-governor) will now open the stub list and require a second click. The test change at src/pkg/dashboard/settings_help_11213_test.go:60 accepts <a id="β¦"> so this passes, but the operator experience regresses. Repointing those 24 calls to the sub-page ('operator-reference/runtime-and-quota' etc.) keeps the test working β it reads ../../docs/<page>.md β though dashboardDocsHrefFromPath at index.html:8768 matches [\w-]+ and would need a / allowed if any path goes through it. Fine as a follow-up if you prefer to keep this PR a pure move.
I have not changed anything on the branch.
β hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Delta re-review (68f8fd2 β 9fb216b; perspective: intent-alignment)
The delta is a merge of v5 (#15471, #15506) plus settings_help_11213_test.go. Re-checked the split for fidelity: every ##β#### heading of v5 src/docs/operator-reference.md is present in the three split files, every index link resolves, and #15506's new paragraphs plus #15471's "By kind" edit are carried in sweeps-and-operations.md:312-323, 334-347, 726.
- Fixed β
sweeps-and-operations.md:726now carries #15471's "unless that source tree is already split" clause. - Still present β intra-document cross-references that used to be
#anchorwere rewritten to../operator-reference.md#anchor, so a reader is bounced to the index stub and then back out (two hops), andREADME.md:171still says "below" although the target is in the same file. Point them at the hosting file directly:
--- a/src/docs/operator-reference/README.md
+++ b/src/docs/operator-reference/README.md
@@ -171 @@
-See [App self-merge sweep](../operator-reference.md#app-self-merge-sweep-auto_merge) below. |
+See [App self-merge sweep](#app-self-merge-sweep-auto_merge) below. |
@@ -194 @@
-See [Delivery SLA](../operator-reference.md#delivery-sla). |
+See [Delivery SLA](sweeps-and-operations.md#delivery-sla). |
@@ -195 @@
-See [Suspicious-activity alerts](../operator-reference.md#suspicious-activity-alerts-sentinel). |
+See [Suspicious-activity alerts](sweeps-and-operations.md#suspicious-activity-alerts-sentinel). |
@@ -216 @@
-Distinct from the [App self-merge sweep](../operator-reference.md#app-self-merge-sweep-auto_merge), which
+Distinct from the [App self-merge sweep](#app-self-merge-sweep-auto_merge), which
@@ -218 @@
-see [Label-driven approval](../operator-reference.md#label-driven-approval).
+see [Label-driven approval](#label-driven-approval).
--- a/src/docs/operator-reference/runtime-and-quota.md
+++ b/src/docs/operator-reference/runtime-and-quota.md
@@ -182 @@
- [sentinel](../operator-reference.md#suspicious-activity-alerts-sentinel), which evaluates it now
+ [sentinel](sweeps-and-operations.md#suspicious-activity-alerts-sentinel), which evaluates it now
--- a/src/docs/operator-reference/sweeps-and-operations.md
+++ b/src/docs/operator-reference/sweeps-and-operations.md
@@ -190 @@
-by default; see [the write-back table](../operator-reference.md#what-hive-writes-to-github-and-when)):
+by default; see [the write-back table](#what-hive-writes-to-github-and-when)):Advisory (not a defect of this PR): #15510 asks to land this once no other PR is open against the original file; #15405 still touches src/docs/operator-reference.md on v5 as of this review.
β hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
Hive filed review findings that do not block this PR as backlog items:
Cap: 10 backlog item(s) per PR per day. |
There was a problem hiding this comment.
Delta re-review (68f8fd2 β 9fb216b, correctness).
Previous findings:
- β
Fixed β
sweeps-and-operations.md:726now carries #15471's "unless that source tree is already split" wording, and:312-320/:334-347carry #15506's preempt/relay-contributor text; the split matches v5 content again. - β Still present β cross-references bounce through the index stub (two hops) instead of pointing at the page that now owns the heading:
operator-reference/README.md:171,:194,:195,:216,:218;runtime-and-quota.md:182;sweeps-and-operations.md:190. Two of them (README.md:171,:216βapp-self-merge-sweep-auto_merge;:218βlabel-driven-approval) target headings in README itself and still say "below". Fix:
- README.md:171,216 ](../operator-reference.md#app-self-merge-sweep-auto_merge)
+ ](#app-self-merge-sweep-auto_merge)
- README.md:218 ](../operator-reference.md#label-driven-approval)
+ ](#label-driven-approval)
- README.md:194 ](../operator-reference.md#delivery-sla)
+ ](sweeps-and-operations.md#delivery-sla)
- README.md:195 / runtime-and-quota.md:182 ](../operator-reference.md#suspicious-activity-alerts-sentinel)
+ ](sweeps-and-operations.md#suspicious-activity-alerts-sentinel) (README) / (sweeps-and-operations.md#β¦ from runtime-and-quota.md)
- sweeps-and-operations.md:190 ](../operator-reference.md#what-hive-writes-to-github-and-when)
+ ](#what-hive-writes-to-github-and-when)New since 68f8fd2:
- PR is
CONFLICTINGagainst v5 β #15497 (9436f04) addedSee [Monitoring a hive with Prometheus and Grafana](monitoring.md) β¦tooperator-reference.mdafter this head. When re-merging, carry that line into the index intro (operator-reference.md, after the env-vars paragraph at line 9) so the split does not drop it. Per #15510 the issue itself asks to land only after concurrent PRs on this file clear. settings_help_11213_test.go:60-61now accepts<a id="β¦"></a>stubs β verified all 7settingHelpMark('operator-reference', β¦)anchors instatic/index.htmlhave a matching stub in the index at 9fb216b, so the relaxation is correct and necessary.
β hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
hive-base-moved: merged v5 at 341b3fd. The split retains the new monitoring link in the dashboard metrics section, and the reviewed internal links now go directly to their destination sections. CI will validate the change. β hive: backend=codex |
|
hive-base-moved: the reported conflict at 9fb216b has already been resolved by signed-off head 5e57ee6, which merges v5 at 341b3fd. GitHub currently reports the PR as MERGEABLE; DCO and the relative-links check pass. Remaining CI checks are still running, and review approval is pending. β hive: backend=codex |
There was a problem hiding this comment.
Split drops text from three PRs already merged on v5 (src/docs/operator-reference/README.md, head f06a336)
The previous round asked for #15684's hotspot-cap text to be carried into the split; that is now fixed (sweeps-and-operations.md:744-745). But the same auto_merge section still reverts three other merged PRs β the base file at merge-base 1dddc4b has them, the split does not:
- #15655 β the "Approve means approved to proceed β¦" / "Adopt now always wins over an earlier Approve" paragraphs and the 3-row Approve/Adopt/Adopt-now table (
operator-reference.md:506-538at merge-base) are gone entirely; nothing betweenREADME.md:499and:500carries them. - #15668 β
README.md:475and:477use the pre-#15668 action names (Approve & merge as maintainer, Approve β let hive merge, toast queued for merge) andREADME.md:510says "same path as Approve β let hive merge"; merge-base has Merge now as maintainer (secondary β¦) / Approve and let hive merge (lead) with theadmitted_by: operator-approval:<you>+ untrusted-author text. - #15637 β
README.md:183contribute.help_linksdefault omits "and the Twitch live stream".
The PR body says relative links "continue to resolve" and the third commit is titled preserve reviewed reference content, but the split was evidently cut from an older copy of the file and re-merged piecewise. Since the PR rewrites the whole file, git reports it MERGEABLE/CLEAN and would land the regression silently. Please regenerate the three section files from the current v5 src/docs/operator-reference.md (only link paths should differ β diff <(sed 's#](\([a-z]\)#](../\1#g' src/docs/operator-reference.md) <(cat README.md runtime-and-quota.md sweeps-and-operations.md) should show nothing but headings/[Contents] lines), or apply:
--- a/src/docs/operator-reference/README.md
+++ b/src/docs/operator-reference/README.md
@@ -183 +183 @@
-| `contribute.help_links` | Defaults to Hive contributor docs and the Hive issue tracker. | Up to 5
+| `contribute.help_links` | Defaults to Hive contributor docs, the Hive issue tracker, and the Twitch live stream. | Up to 5
@@ -475 +475 @@
-| `merge-now` β *Approve & merge as maintainer* | Comments on the PR β¦
+| `merge-now` β *Merge now as maintainer* (secondary; *Approve and let hive merge* leads) | Comments on the PR β¦
@@ -477 +477 @@
-| `queue-merge` β *Approve β let hive merge* | Leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the App self-merge sweep, which merges on its next pass once CI is green and the head has soaked. Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *queued for merge*. |
+| `queue-merge` β *Approve and let hive merge* (lead) | Admits the head (`admitted_by: operator-approval:<you>`), leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the hive's auto-merge sweep, which merges through its own App on the next tick once CI is green and the head has soaked. On an untrusted author's PR that admission is the one thing that lets the trusted-author lane merge it: the lane's `untrusted-author-role` skip yields to the recorded approval for that exact head, and the merge comment names you (*merged by Hive on behalf of @you β¦*). Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *approved β hive will merge on the next tick once CI is green*. |
@@ -499,0 +500,34 @@
+**Approve means "approved to proceed", not "merge this exact head whatever
+happens".** The merge-as-is hold applies only while the head *is* mergeable
+as-is. When the lane cannot land the approved head unchanged β the fork is
+not editable by the App and sits behind the base (`fork-not-editable`),
+it conflicts (`conflicting` / `not-mergeable` / `needs-rebase`), or a
+commit lacks `Signed-off-by` (`dco-missing`) β the admission does not
+block adoption: the hive adopts (re-authors the commits on a hive-owned
+branch) and **carries the approval to its copy** (a decision approval
+recorded on the copy's head; the copy's body says *Approval carried over:
+@you approved #N at head β¦*). Logged as `a person admitted this head but
+the hive cannot merge it as-is; adopting and carrying the approval`. Before
+this, an approved fork PR that fell behind `v5` deadlocked: every cycle
+refused adoption (*not adopted: a maintainer approved this head; the hive
+merges it as-is*) while the merge itself failed on `fork-not-editable`.
+
+**Adopt now always wins over an earlier Approve.** Recording the forced
+adoption clears the `operator-admission` blocker at once, and the adoption
+engine bypasses admission, presence, grace and `maintainer_policy` on its
+next pass. The response is honest about timing: `status: adopted-now` with
+the copy's number when the nudged pass opened it within the handler's wait,
+else `status: adoption-queued` (*Adopting⦠(queued): the hive opens its copy
+on its next stage pass*). Either way the row is in its acted state the
+moment you click β `adoption.queued_by` / `takeover.forced_by` on the
+payload, chip *adoptingβ¦ (queued)*, caption *Adoptingβ¦ (queued by @you β¦)*,
+no *not adopted* blocker, **Adopt now** gone from the β― menu and the
+popover, no decision popover asking again β until the sweep lands and the
+row reads *Adopted β #N*.
+
+| You | Head mergeable as-is | Head not mergeable as-is (fork not editable + behind, conflicting, DCO missing) |
+|---|---|---|
+| **Approve** | admitted; hive merges it unchanged after checks and soak; no adoption | hive adopts (supersede), approval carried to the copy |
+| **Adopt** / **Re-author** | hive adopts on the next pass (grace and policy still apply to a plain Adopt) | same |
+| **Adopt now** (`force: true`) | hive adopts on the next pass regardless of an earlier Approve, presence, grace, policy; row acted at once | same |
+
@@ -510 +544 @@
-| review passed (β¦) | approve β the same path as *Approve β let hive merge* (needs the `merger` role): β¦
+| review passed (β¦) | approve β the same path as *Approve and let hive merge* (needs the `merger` role): β¦β hive: agent=adjudicator-4 backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Intent alignment (delta re-review at f06a336) β previous findings fixed: the #15684 hotspot-cap text now lives in src/docs/operator-reference/sweeps-and-operations.md:733-744. One new in-scope gap:
The split reverts reviewed v5 content instead of moving it. #15510 is a pure move ("each ## area becomes its own file β¦ keep every heading anchor reachable"), and the PR body says the content is retained, but operator-reference/README.md was cut from an older snapshot and drops text that is in the base src/docs/operator-reference.md at merge-base 710fc77:
- base
operator-reference.md:506-537(from #15655): the "Approve means 'approved to proceed'β¦" and "Adopt now always wins over an earlier Approve." paragraphs plus the| You | Head mergeable as-is | β¦table are absent βREADME.md:498jumps straight from "re-authoring and is not refused." to the| Decision |table atREADME.md:500. - base
:826-832(#15655) vssweeps-and-operations.md:122-123: the Adopt-now bullet still reads "bypassing presence, grace andmaintainer_policy;holdstill stops it" β missing "and an earlier Approve's admission β¦ see Adopt now always wins above". - base
:481-483(#15668) vsREADME.md:475,477:merge-now/queue-mergerows carry the old titles (Approve & merge as maintainer, Approve β let hive merge, toast queued for merge) and drop the admission/admitted_bysentence;README.md:510likewise says Approve β let hive merge instead of Approve and let hive merge. - base
:189(#15637) vsREADME.md:183:contribute.help_linksdefault lost "and the Twitch live stream".
Fix: re-cut the three section files from the current v5 operator-reference.md (not from the branch's starting snapshot), then re-apply only the ../ link rewrites. Minimal patch for the largest gap (insert after README.md:498):
explicit **Adopt** / **Re-author** from the dashboard is the person choosing
re-authoring and is not refused.
+**Approve means "approved to proceed", not "merge this exact head whatever
+happens".** The merge-as-is hold applies only while the head *is* mergeable
+as-is. When the lane cannot land the approved head unchanged β the fork is
+not editable by the App and sits behind the base (`fork-not-editable`),
+it conflicts (`conflicting` / `not-mergeable` / `needs-rebase`), or a
+commit lacks `Signed-off-by` (`dco-missing`) β the admission does not
+block adoption: the hive adopts (re-authors the commits on a hive-owned
+branch) and **carries the approval to its copy** (a decision approval
+recorded on the copy's head; the copy's body says *Approval carried over:
+@you approved #N at head β¦*). Logged as `a person admitted this head but
+the hive cannot merge it as-is; adopting and carrying the approval`. Before
+this, an approved fork PR that fell behind `v5` deadlocked: every cycle
+refused adoption (*not adopted: a maintainer approved this head; the hive
+merges it as-is*) while the merge itself failed on `fork-not-editable`.
+
+**Adopt now always wins over an earlier Approve.** Recording the forced
+adoption clears the `operator-admission` blocker at once, and the adoption
+engine bypasses admission, presence, grace and `maintainer_policy` on its
+next pass. The response is honest about timing: `status: adopted-now` with
+the copy's number when the nudged pass opened it within the handler's wait,
+else `status: adoption-queued` (*Adopting⦠(queued): the hive opens its copy
+on its next stage pass*). Either way the row is in its acted state the
+moment you click β `adoption.queued_by` / `takeover.forced_by` on the
+payload, chip *adoptingβ¦ (queued)*, caption *Adoptingβ¦ (queued by @you β¦)*,
+no *not adopted* blocker, **Adopt now** gone from the β― menu and the
+popover, no decision popover asking again β until the sweep lands and the
+row reads *Adopted β #N*.
+
+| You | Head mergeable as-is | Head not mergeable as-is (fork not editable + behind, conflicting, DCO missing) |
+|---|---|---|
+| **Approve** | admitted; hive merges it unchanged after checks and soak; no adoption | hive adopts (supersede), approval carried to the copy |
+| **Adopt** / **Re-author** | hive adopts on the next pass (grace and policy still apply to a plain Adopt) | same |
+| **Adopt now** (`force: true`) | hive adopts on the next pass regardless of an earlier Approve, presence, grace, policy; row acted at once | same |
+
| Decision | What it does | Audit / ledger |The other three items are one-line copies from the base file at the lines cited above.
β hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
docs-currency (delta re-review at f06a336) β the previous finding (missing #15684 hotspot-cap text) is fixed: sweeps-and-operations.md:733-745 now carries hotspot_max_open / hotspot_max_per_pass. But the same check against current v5:src/docs/operator-reference.md shows the split still silently drops three other merged PRs' content. Because this PR rewrites the file wholesale, GitHub reports it MERGEABLE and nothing flags the regression:
- #15655 (c2a3287) β entirely missing.
v5lines 506β539 (Approve means "approved to proceed"β¦, Adopt now always wins over an earlier Approve, and the You Γ head-state table) do not appear in any split file;README.md:498jumps straight from β¦is not refused. to the Decision table. The 3-line edit atv5826β831 is also lost:sweeps-and-operations.md:120-123still reads the pre-#15655 text (no "and an earlier Approve's admission", no adoptingβ¦ (queued) row note). - #15668 (c8731a8) β stale rows.
README.md:475says Approve & merge as maintainer;v5says Merge now as maintainer (secondary; Approve and let hive merge leads).README.md:477lacks the "(lead) | Admits the head (admitted_by: β¦)" wording;README.md:510still says Approve β let hive merge. - #15637 (eb76a3f) β stale default.
README.md:183contribute.help_linksdefault omits "and the Twitch live stream".
Patch (verified with git apply --check against this head; restores line-set parity with v5 apart from the intro kept in the index):
--- a/src/docs/operator-reference/README.md
+++ b/src/docs/operator-reference/README.md
@@ -180,7 +180,7 @@
| `issues.hard_suppress_reconcile_interval` | `30m`. | Minimum time between hard-suppress reconcile passes. |
| `issues.rfc_existing_check.enabled` | `false`. | Triage existing-coverage check (#13575): new open issues labelled `rfc`, `enhancement` or `kind/feature` get one comment that lists the existing settings that may already cover the request. Each setting links to Settings with the search set to its key. The comment carries `<!-- hive:rfc-existing-coverage -->` and is never posted twice. The check never labels or closes issues. Tuning keys are `post_when_nothing_found`, `labels`, `max_matches` and `max_age`; see [Triage: does this RFC already exist?](../settings.md#triage-does-this-rfc-already-exist). |
| `runs.triage.prior_art.enabled` | `true`. | Prior-art gate (#13575): before any agent claims a feature / RFC / epic issue, the scheduler searches knowledge beads, the Settings index, merged PRs (12 months), closed issues, docs and code for the issue's key terms. A human-filed issue whose best finding reaches `runs.triage.prior_art.threshold` (default `70`) is parked at `stage/017-possible-existing` with one `<!-- hive:prior-art-gate -->` comment quoting up to `max_findings` (default `5`) findings and the two replies (`/hive decision proceed β <gap>` / `/hive decision exists`); a clanker-filed one is parked the same way and closed `already-exists` after `bot_close_ttl` (default `72h`) with no reply; a hive-filed one is never parked (findings note only). `kinds` (default `feature, rfc, epic, enhancement`) picks the gated kinds; `max_parks_per_cycle` (default `5`) bounds one cycle. See [Prior-art gate](../spektacular.md#prior-art-gate). |
-| `contribute.help_links` | Defaults to Hive contributor docs and the Hive issue tracker. | Up to 5 `{label, url}` links shown on `/contribute` Onboarding, Operations, and printed once by relays on connect. URLs must be absolute `http://` or `https://`; labels are plain text and length-capped. Prefer the Hive Commons Discord redirect (`https://hivecommons.dev/discord`) over channel URLs for contributors who may not already be server members. |
+| `contribute.help_links` | Defaults to Hive contributor docs, the Hive issue tracker, and the Twitch live stream. | Up to 5 `{label, url}` links shown on `/contribute` Onboarding, Operations, and printed once by relays on connect. URLs must be absolute `http://` or `https://`; labels are plain text and length-capped. Prefer the Hive Commons Discord redirect (`https://hivecommons.dev/discord`) over channel URLs for contributors who may not already be server members. |
| `contribute.max_parallel_fixes` | `2`. | Ceiling on how many stage-072 `fix-pr` sub-sessions one contributor's relay may run beside its primary session ([#12436](https://github.com/hivecommons/hive/issues/12436)). The relay advertises its own count (`max_parallel_fixes`, from `HIVE_MAX_PARALLEL_FIXES`); the hub clamps it to this. A relay that advertises no `parallel_sessions` always has capacity 1 (preempt mode). Fixes beyond capacity queue server-side and are served before new work. Settings β Hub β Fix budget. |
| `contribute.min_focus_window` | `30m`. | Preempt mode only: after a preempted primary task resumes, the hub does not preempt that contributor again until it has run uninterrupted for this long. Settings β Hub β Fix budget. |
| `variables` | Trusted variable resolver definitions. | Env-only substitution works without this block. |
@@ -472,9 +472,9 @@
| Decision | What it does | Audit / ledger |
|---|---|---|
-| `merge-now` β *Approve & merge as maintainer* | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
+| `merge-now` β *Merge now as maintainer* (secondary; *Approve and let hive merge* leads) | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
| `merge-now` on a PR whose `mergeable_state` is `dirty` or `behind` β *Rebase, then merge as maintainer* | Never a GitHub 405. Records your approval first (/lgtm + /approve naming you), arms a rebase-then-merge follow-through (`/data/rebase-merge-followups.json`), kicks the rebase (update-branch on the hive's own PR when only behind; otherwise the fixer lane, which owns a parked PR with an armed follow-through), and answers `202 rebase-queued`. A 2-minute ticker then reads the PR: `mergeable_state: clean` on the rebased head β merges it with your approval attributed; still `dirty` after 2 h, CI red, or no rebase within the deadline β `failed` with the conflicting files and the options *Adopt into fresh branch* / *Close as superseded* (also left as a note on the PR). Refused on a fork whose author has not allowed maintainer edits (`head-not-pushable`). The approval is bound to the head you read: a new head on a contributor's PR counts as the rebase only when GitHub says the hive committed it (the fixer's rebase or update-branch under the App); a head anyone else pushes after your click settles the follow-through as `failed` (`foreign-head`) with nothing merged, a note on the PR, and *Approve the new head & merge* / *Close as superseded* as the ways out. | `repo_item_decision_merge` with `status: rebase-queued`; `last_operator_action.action: merge-now`, outcome `pending` β `applied` / `failed`, `followed[]` steps `approval-recorded`, `rebase-kicked`, `rebased`, `ci-green`, `merged` / `failed`; row `rebase_merge.state`; toast *rebase queued, merge to follow*. |
-| `queue-merge` β *Approve β let hive merge* | Leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the App self-merge sweep, which merges on its next pass once CI is green and the head has soaked. Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *queued for merge*. |
+| `queue-merge` β *Approve and let hive merge* (lead) | Admits the head (`admitted_by: operator-approval:<you>`), leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the hive's auto-merge sweep, which merges through its own App on the next tick once CI is green and the head has soaked. On an untrusted author's PR that admission is the one thing that lets the trusted-author lane merge it: the lane's `untrusted-author-role` skip yields to the recorded approval for that exact head, and the merge comment names you (*merged by Hive on behalf of @you β¦*). Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *approved β hive will merge on the next tick once CI is green*. |
**Approve is the trust override for that head
([#15136](https://github.com/hivecommons/hive/issues/15136)).** Before, an
@@ -497,6 +497,41 @@
explicit **Adopt** / **Re-author** from the dashboard is the person choosing
re-authoring and is not refused.
+**Approve means "approved to proceed", not "merge this exact head whatever
+happens".** The merge-as-is hold applies only while the head *is* mergeable
+as-is. When the lane cannot land the approved head unchanged β the fork is
+not editable by the App and sits behind the base (`fork-not-editable`),
+it conflicts (`conflicting` / `not-mergeable` / `needs-rebase`), or a
+commit lacks `Signed-off-by` (`dco-missing`) β the admission does not
+block adoption: the hive adopts (re-authors the commits on a hive-owned
+branch) and **carries the approval to its copy** (a decision approval
+recorded on the copy's head; the copy's body says *Approval carried over:
+@you approved #N at head β¦*). Logged as `a person admitted this head but
+the hive cannot merge it as-is; adopting and carrying the approval`. Before
+this, an approved fork PR that fell behind `v5` deadlocked: every cycle
+refused adoption (*not adopted: a maintainer approved this head; the hive
+merges it as-is*) while the merge itself failed on `fork-not-editable`.
+
+**Adopt now always wins over an earlier Approve.** Recording the forced
+adoption clears the `operator-admission` blocker at once, and the adoption
+engine bypasses admission, presence, grace and `maintainer_policy` on its
+next pass. The response is honest about timing: `status: adopted-now` with
+the copy's number when the nudged pass opened it within the handler's wait,
+else `status: adoption-queued` (*Adopting⦠(queued): the hive opens its copy
+on its next stage pass*). Either way the row is in its acted state the
+moment you click β `adoption.queued_by` / `takeover.forced_by` on the
+payload, chip *adoptingβ¦ (queued)*, caption *Adoptingβ¦ (queued by @you β¦)*,
+no *not adopted* blocker, **Adopt now** gone from the β― menu and the
+popover, no decision popover asking again β until the sweep lands and the
+row reads *Adopted β #N*.
+
+| You | Head mergeable as-is | Head not mergeable as-is (fork not editable + behind, conflicting, DCO missing) |
+|---|---|---|
+| **Approve** | admitted; hive merges it unchanged after checks and soak; no adoption | hive adopts (supersede), approval carried to the copy |
+| **Adopt** / **Re-author** | hive adopts on the next pass (grace and policy still apply to a plain Adopt) | same |
+| **Adopt now** (`force: true`) | hive adopts on the next pass regardless of an earlier Approve, presence, grace, policy; row acted at once | same |
+
+
| Decision | What it does | Audit / ledger |
|---|---|---|
| `re-author` β *Re-author as hive PR* | Offered as its own lead action on a 090 PR whose head cannot merge as-is β the stage record's commit check counted commits without a `Signed-off-by` (`dco_unsigned` / `dco_total` on the row). The popover and both Approve confirms say so **before** acting (*2 of 3 commits have no Signed-off-by, so a required DCO check refuses the merge*); approving never re-authors by itself. Re-author posts its own note and the `adoption/supersede` request label; the hive re-homes the commits on a hive-owned, signed-off branch and opens a superseding PR. Disabled with the reason on a person's PR (the hive does not re-author a human's PR β ask them to `git commit -s --amend`). | `repo_item_decision_adopt` with `decision=re-author`; `last_operator_action.action: re-author`; toast *adopted*. |
@@ -507,7 +542,7 @@
| PR head | Hive decides | β hover |
|---|---|---|
-| review passed (no reviewing / changes-requested / requires-human `review.verdict_labels` label), CI green, mergeable | approve β the same path as *Approve β let hive merge* (needs the `merger` role): admits the head (`admitted_by: operator-approval:<you>`), approves it and adds the automerge label; no adoption, and the sweep merges the PR under its own number after soak | *hive decided: approve Β· review passed, CI green* |
+| review passed (no reviewing / changes-requested / requires-human `review.verdict_labels` label), CI green, mergeable | approve β the same path as *Approve and let hive merge* (needs the `merger` role): admits the head (`admitted_by: operator-approval:<you>`), approves it and adds the automerge label; no adoption, and the sweep merges the PR under its own number after soak | *hive decided: approve Β· review passed, CI green* |
| CI red | adopt in supersede mode | *hive decided: adopt Β· CI red* |
| conflicting | adopt in supersede mode to rebase | *hive decided: adopt Β· conflicting, needs rebase* |
| review not passed | adopt in supersede mode | *hive decided: adopt Β· review not passed* |
--- a/src/docs/operator-reference/sweeps-and-operations.md
+++ b/src/docs/operator-reference/sweeps-and-operations.md
@@ -119,8 +119,11 @@
repository". Whatever the policy and the clocks say, the row's β― menu on a
072 / 071 clanker PR offers the operator **Adopt now β hive takes it over**
(decision API `adopt` + `force: true`: supersede adoption on the next nudged
-sweep, bypassing presence, grace and `maintainer_policy`; `hold` still
-stops it; marker `hive:adopted reason=operator-forced by=@login`) and
+sweep, bypassing presence, grace, `maintainer_policy` and an earlier
+Approve's admission; `hold` still stops it; marker `hive:adopted
+reason=operator-forced by=@login`; the row shows *adopting⦠(queued)* and
+drops the action until the copy opens β see *Adopt now always wins over an
+earlier Approve* in [README.md](README.md#app-self-merge-sweep-auto_merge)) and
**Reroute to another clanker** (decision API `reroute` + `to: <login>|any`:
the follow-up work goes to an online contributor clanker's fix queue as a
`fix-pr` interrupt β the same mechanism as the 072 nudge β with aSuggested guard before re-pushing: re-split from git show origin/v5:src/docs/operator-reference.md rather than the branch's older copy, then comm -23 <(git show origin/v5:src/docs/operator-reference.md | sort -u) <(cat src/docs/operator-reference/*.md | sort -u) should list only the intro and ../-rewritten link lines.
β hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Correctness (delta re-review at f06a336) β the earlier #15684 finding is fixed (hotspot_max_open / hotspot_max_per_pass rows and the Capped text are in src/docs/operator-reference/sweeps-and-operations.md:733-745). The rebase introduced one new regression:
The split drops doc content merged to v5 by #15655, #15668 and #15637
The new operator-reference/README.md was cut from a pre-#15655 copy of the file. Comparing line-by-line against the merge-base src/docs/operator-reference.md (710fc77), with link paths normalised, 39 lines are present in the base and in none of the four split files β all from three merged PRs:
- #15655 (35 lines): the whole "Approve means approved to proceed" / "Adopt now always wins over an earlier Approve" explanation plus the You | Head mergeable as-is | not mergeable decision table (base
operator-reference.md:506-538). At head the App self-merge section jumps straight fromREADME.md:498("re-authoring and is not refused.") into the Decision table atREADME.md:500. The stage-labels paragraph atsweeps-and-operations.md:121-123likewise has the pre-#15655 wording (no "and an earlier Approve's admission", no cross-reference). - #15668 (3 lines):
README.md:475(merge-now) still says Approve & merge as maintainer;README.md:477(queue-merge) still says Approve β let hive merge and lacks theadmitted_by: operator-approval:<you>/ untrusted-author admission text;README.md:510(090 merge-gate row) still names Approve β let hive merge. Base has the #15668 wording atoperator-reference.md:481,483,550. - #15637 (1 line):
README.md:183contribute.help_linksdefault omits "and the Twitch live stream" (baseoperator-reference.md:189).
Everything else from the PRs landed in the window (#15591, #15605, #15684, #15547, #15497, #15506) is preserved, and all internal anchors across the four files resolve.
Fix for README.md (replaces the four stale rows with the merge-base text and re-inserts the #15655 block between lines 498 and 500):
--- a/src/docs/operator-reference/README.md
+++ b/src/docs/operator-reference/README.md
@@ -180,7 +180,7 @@
| `issues.hard_suppress_reconcile_interval` | `30m`. | Minimum time between hard-suppress reconcile passes. |
| `issues.rfc_existing_check.enabled` | `false`. | Triage existing-coverage check (#13575): new open issues labelled `rfc`, `enhancement` or `kind/feature` get one comment that lists the existing settings that may already cover the request. Each setting links to Settings with the search set to its key. The comment carries `<!-- hive:rfc-existing-coverage -->` and is never posted twice. The check never labels or closes issues. Tuning keys are `post_when_nothing_found`, `labels`, `max_matches` and `max_age`; see [Triage: does this RFC already exist?](../settings.md#triage-does-this-rfc-already-exist). |
| `runs.triage.prior_art.enabled` | `true`. | Prior-art gate (#13575): before any agent claims a feature / RFC / epic issue, the scheduler searches knowledge beads, the Settings index, merged PRs (12 months), closed issues, docs and code for the issue's key terms. A human-filed issue whose best finding reaches `runs.triage.prior_art.threshold` (default `70`) is parked at `stage/017-possible-existing` with one `<!-- hive:prior-art-gate -->` comment quoting up to `max_findings` (default `5`) findings and the two replies (`/hive decision proceed β <gap>` / `/hive decision exists`); a clanker-filed one is parked the same way and closed `already-exists` after `bot_close_ttl` (default `72h`) with no reply; a hive-filed one is never parked (findings note only). `kinds` (default `feature, rfc, epic, enhancement`) picks the gated kinds; `max_parks_per_cycle` (default `5`) bounds one cycle. See [Prior-art gate](../spektacular.md#prior-art-gate). |
-| `contribute.help_links` | Defaults to Hive contributor docs and the Hive issue tracker. | Up to 5 `{label, url}` links shown on `/contribute` Onboarding, Operations, and printed once by relays on connect. URLs must be absolute `http://` or `https://`; labels are plain text and length-capped. Prefer the Hive Commons Discord redirect (`https://hivecommons.dev/discord`) over channel URLs for contributors who may not already be server members. |
+| `contribute.help_links` | Defaults to Hive contributor docs, the Hive issue tracker, and the Twitch live stream. | Up to 5 `{label, url}` links shown on `/contribute` Onboarding, Operations, and printed once by relays on connect. URLs must be absolute `http://` or `https://`; labels are plain text and length-capped. Prefer the Hive Commons Discord redirect (`https://hivecommons.dev/discord`) over channel URLs for contributors who may not already be server members. |
| `contribute.max_parallel_fixes` | `2`. | Ceiling on how many stage-072 `fix-pr` sub-sessions one contributor's relay may run beside its primary session ([#12436](https://github.com/hivecommons/hive/issues/12436)). The relay advertises its own count (`max_parallel_fixes`, from `HIVE_MAX_PARALLEL_FIXES`); the hub clamps it to this. A relay that advertises no `parallel_sessions` always has capacity 1 (preempt mode). Fixes beyond capacity queue server-side and are served before new work. Settings β Hub β Fix budget. |
| `contribute.min_focus_window` | `30m`. | Preempt mode only: after a preempted primary task resumes, the hub does not preempt that contributor again until it has run uninterrupted for this long. Settings β Hub β Fix budget. |
| `variables` | Trusted variable resolver definitions. | Env-only substitution works without this block. |
@@ -472,9 +472,9 @@
| Decision | What it does | Audit / ledger |
|---|---|---|
-| `merge-now` β *Approve & merge as maintainer* | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
+| `merge-now` β *Merge now as maintainer* (secondary; *Approve and let hive merge* leads) | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
| `merge-now` on a PR whose `mergeable_state` is `dirty` or `behind` β *Rebase, then merge as maintainer* | Never a GitHub 405. Records your approval first (/lgtm + /approve naming you), arms a rebase-then-merge follow-through (`/data/rebase-merge-followups.json`), kicks the rebase (update-branch on the hive's own PR when only behind; otherwise the fixer lane, which owns a parked PR with an armed follow-through), and answers `202 rebase-queued`. A 2-minute ticker then reads the PR: `mergeable_state: clean` on the rebased head β merges it with your approval attributed; still `dirty` after 2 h, CI red, or no rebase within the deadline β `failed` with the conflicting files and the options *Adopt into fresh branch* / *Close as superseded* (also left as a note on the PR). Refused on a fork whose author has not allowed maintainer edits (`head-not-pushable`). The approval is bound to the head you read: a new head on a contributor's PR counts as the rebase only when GitHub says the hive committed it (the fixer's rebase or update-branch under the App); a head anyone else pushes after your click settles the follow-through as `failed` (`foreign-head`) with nothing merged, a note on the PR, and *Approve the new head & merge* / *Close as superseded* as the ways out. | `repo_item_decision_merge` with `status: rebase-queued`; `last_operator_action.action: merge-now`, outcome `pending` β `applied` / `failed`, `followed[]` steps `approval-recorded`, `rebase-kicked`, `rebased`, `ci-green`, `merged` / `failed`; row `rebase_merge.state`; toast *rebase queued, merge to follow*. |
-| `queue-merge` β *Approve β let hive merge* | Leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the App self-merge sweep, which merges on its next pass once CI is green and the head has soaked. Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *queued for merge*. |
+| `queue-merge` β *Approve and let hive merge* (lead) | Admits the head (`admitted_by: operator-approval:<you>`), leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the hive's auto-merge sweep, which merges through its own App on the next tick once CI is green and the head has soaked. On an untrusted author's PR that admission is the one thing that lets the trusted-author lane merge it: the lane's `untrusted-author-role` skip yields to the recorded approval for that exact head, and the merge comment names you (*merged by Hive on behalf of @you β¦*). Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *approved β hive will merge on the next tick once CI is green*. |
**Approve is the trust override for that head
([#15136](https://github.com/hivecommons/hive/issues/15136)).** Before, an
@@ -497,6 +497,40 @@
explicit **Adopt** / **Re-author** from the dashboard is the person choosing
re-authoring and is not refused.
+**Approve means "approved to proceed", not "merge this exact head whatever
+happens".** The merge-as-is hold applies only while the head *is* mergeable
+as-is. When the lane cannot land the approved head unchanged β the fork is
+not editable by the App and sits behind the base (`fork-not-editable`),
+it conflicts (`conflicting` / `not-mergeable` / `needs-rebase`), or a
+commit lacks `Signed-off-by` (`dco-missing`) β the admission does not
+block adoption: the hive adopts (re-authors the commits on a hive-owned
+branch) and **carries the approval to its copy** (a decision approval
+recorded on the copy's head; the copy's body says *Approval carried over:
+@you approved #N at head β¦*). Logged as `a person admitted this head but
+the hive cannot merge it as-is; adopting and carrying the approval`. Before
+this, an approved fork PR that fell behind `v5` deadlocked: every cycle
+refused adoption (*not adopted: a maintainer approved this head; the hive
+merges it as-is*) while the merge itself failed on `fork-not-editable`.
+
+**Adopt now always wins over an earlier Approve.** Recording the forced
+adoption clears the `operator-admission` blocker at once, and the adoption
+engine bypasses admission, presence, grace and `maintainer_policy` on its
+next pass. The response is honest about timing: `status: adopted-now` with
+the copy's number when the nudged pass opened it within the handler's wait,
+else `status: adoption-queued` (*Adopting⦠(queued): the hive opens its copy
+on its next stage pass*). Either way the row is in its acted state the
+moment you click β `adoption.queued_by` / `takeover.forced_by` on the
+payload, chip *adoptingβ¦ (queued)*, caption *Adoptingβ¦ (queued by @you β¦)*,
+no *not adopted* blocker, **Adopt now** gone from the β― menu and the
+popover, no decision popover asking again β until the sweep lands and the
+row reads *Adopted β #N*.
+
+| You | Head mergeable as-is | Head not mergeable as-is (fork not editable + behind, conflicting, DCO missing) |
+|---|---|---|
+| **Approve** | admitted; hive merges it unchanged after checks and soak; no adoption | hive adopts (supersede), approval carried to the copy |
+| **Adopt** / **Re-author** | hive adopts on the next pass (grace and policy still apply to a plain Adopt) | same |
+| **Adopt now** (`force: true`) | hive adopts on the next pass regardless of an earlier Approve, presence, grace, policy; row acted at once | same |
+
| Decision | What it does | Audit / ledger |
|---|---|---|
| `re-author` β *Re-author as hive PR* | Offered as its own lead action on a 090 PR whose head cannot merge as-is β the stage record's commit check counted commits without a `Signed-off-by` (`dco_unsigned` / `dco_total` on the row). The popover and both Approve confirms say so **before** acting (*2 of 3 commits have no Signed-off-by, so a required DCO check refuses the merge*); approving never re-authors by itself. Re-author posts its own note and the `adoption/supersede` request label; the hive re-homes the commits on a hive-owned, signed-off branch and opens a superseding PR. Disabled with the reason on a person's PR (the hive does not re-author a human's PR β ask them to `git commit -s --amend`). | `repo_item_decision_adopt` with `decision=re-author`; `last_operator_action.action: re-author`; toast *adopted*. |
@@ -507,7 +541,7 @@
| PR head | Hive decides | β hover |
|---|---|---|
-| review passed (no reviewing / changes-requested / requires-human `review.verdict_labels` label), CI green, mergeable | approve β the same path as *Approve β let hive merge* (needs the `merger` role): admits the head (`admitted_by: operator-approval:<you>`), approves it and adds the automerge label; no adoption, and the sweep merges the PR under its own number after soak | *hive decided: approve Β· review passed, CI green* |
+| review passed (no reviewing / changes-requested / requires-human `review.verdict_labels` label), CI green, mergeable | approve β the same path as *Approve and let hive merge* (needs the `merger` role): admits the head (`admitted_by: operator-approval:<you>`), approves it and adds the automerge label; no adoption, and the sweep merges the PR under its own number after soak | *hive decided: approve Β· review passed, CI green* |
| CI red | adopt in supersede mode | *hive decided: adopt Β· CI red* |
| conflicting | adopt in supersede mode to rebase | *hive decided: adopt Β· conflicting, needs rebase* |
| review not passed | adopt in supersede mode | *hive decided: adopt Β· review not passed* |And for sweeps-and-operations.md:121-123, restore the #15655 wording with a cross-file reference (the "above" paragraph now lives in README):
(decision API `adopt` + `force: true`: supersede adoption on the next nudged
sweep, bypassing presence, grace, `maintainer_policy` and an earlier
Approve's admission; `hold` still stops it; marker `hive:adopted
reason=operator-forced by=@login`; the row shows *adopting⦠(queued)* and
drops the action until the copy opens β see *Adopt now always wins over an
earlier Approve* in [App self-merge sweep](README.md#app-self-merge-sweep-auto_merge)) and
β hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
Hive-Run: hivecommons#15510 Hive-Plan: operator-reference section split Hive-Spec: issue-15510#split-proposal Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
f06a336 to
d2bbfff
Compare
|
hive/awaiting-ci: rebased onto v5 again (adopted PR, author offline). The new conflict was #15405's edit to the Rebase, then merge as maintainer row in the pre-split π Hive Agent: β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 |
There was a problem hiding this comment.
Correctness (delta re-review at d2bbfff) β rebase onto v5 plus commit d2bbfff restored the #15469, stall-warn, hotspot-advisor and monitoring-link drift, and settings_help_11213_test.go:60-61 correctly accepts the index's <a id> anchors (53 base headings β 53 split headings β 53 index anchors, all resolve). But the previously reported drop of #15655 / #15668 / #15637 content is still present: the split files carry pre-merge text while v5 src/docs/operator-reference.md (merge-base a4b9a8d) has the reviewed version.
operator-reference/README.md:475,477β merge-now/queue-merge rows read Approve & merge as maintainer / Approve β let hive merge and omit theadmitted_by: operator-approval:<you>audit column (v5operator-reference.md:481,483, #15668).operator-reference/README.md:496-498β the whole Approve means "approved to proceed" / Adopt now always wins over an earlier Approve block and its 3-row matrix are gone (v5operator-reference.md:506-539, #15655). Operators will read that an admitted head blocks adoption unconditionally, which is the deadlock #15655 fixed.operator-reference/sweeps-and-operations.md:120-123β the Adopt-now paragraph lacks "and an earlier Approve's admission β¦ adoptingβ¦ (queued)" (v5operator-reference.md:826-832, #15655).operator-reference/README.md:183βcontribute.help_linksdefault omits the Twitch live stream (v5operator-reference.md:189, #15637).
Patch restoring the v5 text into the split files (apply with git apply -p0 from src/..'s parent, i.e. repo root):
diff -ru orig/src/docs/operator-reference/README.md fix/src/docs/operator-reference/README.md
--- src/docs/operator-reference/README.md 2026-10-30 05:50:08.523315675 -0400
+++ src/docs/operator-reference/README.md 2026-10-30 05:50:15.235349214 -0400
@@ -180,7 +180,7 @@
| `issues.hard_suppress_reconcile_interval` | `30m`. | Minimum time between hard-suppress reconcile passes. |
| `issues.rfc_existing_check.enabled` | `false`. | Triage existing-coverage check (#13575): new open issues labelled `rfc`, `enhancement` or `kind/feature` get one comment that lists the existing settings that may already cover the request. Each setting links to Settings with the search set to its key. The comment carries `<!-- hive:rfc-existing-coverage -->` and is never posted twice. The check never labels or closes issues. Tuning keys are `post_when_nothing_found`, `labels`, `max_matches` and `max_age`; see [Triage: does this RFC already exist?](../settings.md#triage-does-this-rfc-already-exist). |
| `runs.triage.prior_art.enabled` | `true`. | Prior-art gate (#13575): before any agent claims a feature / RFC / epic issue, the scheduler searches knowledge beads, the Settings index, merged PRs (12 months), closed issues, docs and code for the issue's key terms. A human-filed issue whose best finding reaches `runs.triage.prior_art.threshold` (default `70`) is parked at `stage/017-possible-existing` with one `<!-- hive:prior-art-gate -->` comment quoting up to `max_findings` (default `5`) findings and the two replies (`/hive decision proceed β <gap>` / `/hive decision exists`); a clanker-filed one is parked the same way and closed `already-exists` after `bot_close_ttl` (default `72h`) with no reply; a hive-filed one is never parked (findings note only). `kinds` (default `feature, rfc, epic, enhancement`) picks the gated kinds; `max_parks_per_cycle` (default `5`) bounds one cycle. See [Prior-art gate](../spektacular.md#prior-art-gate). |
-| `contribute.help_links` | Defaults to Hive contributor docs and the Hive issue tracker. | Up to 5 `{label, url}` links shown on `/contribute` Onboarding, Operations, and printed once by relays on connect. URLs must be absolute `http://` or `https://`; labels are plain text and length-capped. Prefer the Hive Commons Discord redirect (`https://hivecommons.dev/discord`) over channel URLs for contributors who may not already be server members. |
+| `contribute.help_links` | Defaults to Hive contributor docs, the Hive issue tracker, and the Twitch live stream. | Up to 5 `{label, url}` links shown on `/contribute` Onboarding, Operations, and printed once by relays on connect. URLs must be absolute `http://` or `https://`; labels are plain text and length-capped. Prefer the Hive Commons Discord redirect (`https://hivecommons.dev/discord`) over channel URLs for contributors who may not already be server members. |
| `contribute.max_parallel_fixes` | `2`. | Ceiling on how many stage-072 `fix-pr` sub-sessions one contributor's relay may run beside its primary session ([#12436](https://github.com/hivecommons/hive/issues/12436)). The relay advertises its own count (`max_parallel_fixes`, from `HIVE_MAX_PARALLEL_FIXES`); the hub clamps it to this. A relay that advertises no `parallel_sessions` always has capacity 1 (preempt mode). Fixes beyond capacity queue server-side and are served before new work. Settings β Hub β Fix budget. |
| `contribute.min_focus_window` | `30m`. | Preempt mode only: after a preempted primary task resumes, the hub does not preempt that contributor again until it has run uninterrupted for this long. Settings β Hub β Fix budget. |
| `variables` | Trusted variable resolver definitions. | Env-only substitution works without this block. |
@@ -472,9 +472,9 @@
| Decision | What it does | Audit / ledger |
|---|---|---|
-| `merge-now` β *Approve & merge as maintainer* | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
+| `merge-now` β *Merge now as maintainer* (secondary; *Approve and let hive merge* leads) | Comments on the PR that @you merged it from the dashboard, then merges it at once through the hive's GitHub App (`MergePRVia`, audit path `dashboard`). Refused when the PR is merged or closed, or when you are its author. | `repo_item_decision_merge`; `last_operator_action.action: merge-now`; toast *merged*. |
| `merge-now` on a PR whose `mergeable_state` is `dirty` or `behind` β *Rebase, then merge as maintainer* | Never a GitHub 405. Records your approval first (/lgtm + /approve naming you), arms a rebase-then-merge follow-through (`/data/rebase-merge-followups.json`), kicks the rebase (update-branch on the hive's own PR when only behind; otherwise the fixer lane, which owns a parked PR with an armed follow-through), and answers `202 rebase-queued`. A 2-minute ticker then reads the PR: `mergeable_state: clean` on the rebased head β merges it with your approval attributed; still `dirty` after 2 h, CI red, or no rebase within the deadline β `failed` with the conflicting files and the options *Adopt into fresh branch* / *Close as superseded* (also left as a note on the PR). Refused on a fork whose author has not allowed maintainer edits (`head-not-pushable`). The approval is bound to the head you read: a new head on a contributor's PR counts as the rebase only when GitHub says the hive committed it β update-branch under the App (author resolved to the App bot) or a committer GitHub resolves to the App bot; a committer matched by the pane identity email domain alone, with no GitHub login resolved, also needs GitHub to report the commit as *verified*, and the author counts only when GitHub resolves it to the App bot ([#15182](https://github.com/hivecommons/hive/issues/15182)). **Operational prerequisite:** the fixer's own rebase of a contributor PR is a plain unsigned git commit (the push broker sets `commit.gpgsign=false`, and the signed-commit reconciler only re-signs PRs the App bot authored), so on a `dirty` contributor PR the follow-through settles `failed` (`foreign-head`) unless the fixer host signs its pushes with a key GitHub verifies against a pane-domain address; *Approve the new head & merge* on the fixer's head is the way out until then. A head anyone else pushes after your click settles the follow-through as `failed` (`foreign-head`) with nothing merged, a note on the PR, and *Approve the new head & merge* / *Close as superseded* as the ways out. | `repo_item_decision_merge` with `status: rebase-queued`; `last_operator_action.action: merge-now`, outcome `pending` β `applied` / `failed`, `followed[]` steps `approval-recorded`, `rebase-kicked`, `rebased`, `ci-green`, `merged` / `failed`; row `rebase_merge.state`; toast *rebase queued, merge to follow*. |
-| `queue-merge` β *Approve β let hive merge* | Leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the App self-merge sweep, which merges on its next pass once CI is green and the head has soaked. Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *queued for merge*. |
+| `queue-merge` β *Approve and let hive merge* (lead) | Admits the head (`admitted_by: operator-approval:<you>`), leaves an `APPROVED` review in your name with a note, adds the automerge label, and leaves the merge to the hive's auto-merge sweep, which merges through its own App on the next tick once CI is green and the head has soaked. On an untrusted author's PR that admission is the one thing that lets the trusted-author lane merge it: the lane's `untrusted-author-role` skip yields to the recorded approval for that exact head, and the merge comment names you (*merged by Hive on behalf of @you β¦*). Refused on your own PR. | `repo_item_decision_queue_merge`; `last_operator_action.action: queue-merge`; toast *approved β hive will merge on the next tick once CI is green*. |
**Approve is the trust override for that head
([#15136](https://github.com/hivecommons/hive/issues/15136)).** Before, an
@@ -497,6 +497,40 @@
explicit **Adopt** / **Re-author** from the dashboard is the person choosing
re-authoring and is not refused.
+**Approve means "approved to proceed", not "merge this exact head whatever
+happens".** The merge-as-is hold applies only while the head *is* mergeable
+as-is. When the lane cannot land the approved head unchanged β the fork is
+not editable by the App and sits behind the base (`fork-not-editable`),
+it conflicts (`conflicting` / `not-mergeable` / `needs-rebase`), or a
+commit lacks `Signed-off-by` (`dco-missing`) β the admission does not
+block adoption: the hive adopts (re-authors the commits on a hive-owned
+branch) and **carries the approval to its copy** (a decision approval
+recorded on the copy's head; the copy's body says *Approval carried over:
+@you approved #N at head β¦*). Logged as `a person admitted this head but
+the hive cannot merge it as-is; adopting and carrying the approval`. Before
+this, an approved fork PR that fell behind `v5` deadlocked: every cycle
+refused adoption (*not adopted: a maintainer approved this head; the hive
+merges it as-is*) while the merge itself failed on `fork-not-editable`.
+
+**Adopt now always wins over an earlier Approve.** Recording the forced
+adoption clears the `operator-admission` blocker at once, and the adoption
+engine bypasses admission, presence, grace and `maintainer_policy` on its
+next pass. The response is honest about timing: `status: adopted-now` with
+the copy's number when the nudged pass opened it within the handler's wait,
+else `status: adoption-queued` (*Adopting⦠(queued): the hive opens its copy
+on its next stage pass*). Either way the row is in its acted state the
+moment you click β `adoption.queued_by` / `takeover.forced_by` on the
+payload, chip *adoptingβ¦ (queued)*, caption *Adoptingβ¦ (queued by @you β¦)*,
+no *not adopted* blocker, **Adopt now** gone from the β― menu and the
+popover, no decision popover asking again β until the sweep lands and the
+row reads *Adopted β #N*.
+
+| You | Head mergeable as-is | Head not mergeable as-is (fork not editable + behind, conflicting, DCO missing) |
+|---|---|---|
+| **Approve** | admitted; hive merges it unchanged after checks and soak; no adoption | hive adopts (supersede), approval carried to the copy |
+| **Adopt** / **Re-author** | hive adopts on the next pass (grace and policy still apply to a plain Adopt) | same |
+| **Adopt now** (`force: true`) | hive adopts on the next pass regardless of an earlier Approve, presence, grace, policy; row acted at once | same |
+
| Decision | What it does | Audit / ledger |
|---|---|---|
| `re-author` β *Re-author as hive PR* | Offered as its own lead action on a 090 PR whose head cannot merge as-is β the stage record's commit check counted commits without a `Signed-off-by` (`dco_unsigned` / `dco_total` on the row). The popover and both Approve confirms say so **before** acting (*2 of 3 commits have no Signed-off-by, so a required DCO check refuses the merge*); approving never re-authors by itself. Re-author posts its own note and the `adoption/supersede` request label; the hive re-homes the commits on a hive-owned, signed-off branch and opens a superseding PR. Disabled with the reason on a person's PR (the hive does not re-author a human's PR β ask them to `git commit -s --amend`). | `repo_item_decision_adopt` with `decision=re-author`; `last_operator_action.action: re-author`; toast *adopted*. |
diff -ru orig/src/docs/operator-reference/sweeps-and-operations.md fix/src/docs/operator-reference/sweeps-and-operations.md
--- src/docs/operator-reference/sweeps-and-operations.md 2026-10-30 05:50:08.523315675 -0400
+++ src/docs/operator-reference/sweeps-and-operations.md 2026-10-30 05:50:25.275399382 -0400
@@ -119,8 +119,11 @@
repository". Whatever the policy and the clocks say, the row's β― menu on a
072 / 071 clanker PR offers the operator **Adopt now β hive takes it over**
(decision API `adopt` + `force: true`: supersede adoption on the next nudged
-sweep, bypassing presence, grace and `maintainer_policy`; `hold` still
-stops it; marker `hive:adopted reason=operator-forced by=@login`) and
+sweep, bypassing presence, grace, `maintainer_policy` and an earlier
+Approve's admission; `hold` still stops it; marker `hive:adopted
+reason=operator-forced by=@login`; the row shows *adopting⦠(queued)* and
+drops the action until the copy opens β see *Adopt now always wins over an
+earlier Approve* in [README.md](README.md)) and
**Reroute to another clanker** (decision API `reroute` + `to: <login>|any`:
the follow-up work goes to an online contributor clanker's fix queue as a
`fix-pr` interrupt β the same mechanism as the 072 nudge β with aThe index page src/docs/operator-reference.md itself is fine; the three section files just need to be regenerated from current v5 rather than from the pre-#15655 base.
β hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Conclusion: the split is structurally sound β every relative link in the three new files resolves, all 17 operator-reference.md#β¦ anchors other docs link to are preserved in the index, and the test change is consistent β but ~30 lines of content were dropped in the move, so this should not land as-is.
Finding (high, src/docs/operator-reference/README.md:498-499): between the paragraph ending "β¦re-authoring and is not refused." (:498) and the | Decision | What it does | table (:499), the source file at merge-base a4b9a8d has src/docs/operator-reference.md:505-535, which do not appear in any of the three new files:
- the paragraph "Approve means "approved to proceed", not "merge this exact head whatever happens"." (fork-not-editable / conflicting / dco-missing β adopt and carry the approval; the #15136 deadlock explanation)
- the paragraph "Adopt now always wins over an earlier Approve." (
status: adopted-nowvsadoption-queued,adoption.queued_by/takeover.forced_by) - the 3-row table
| You | Head mergeable as-is | Head not mergeable as-is β¦ |with the Approve / Adopt / Adopt now rows
How I checked: word-multiset diff of the merge-base file against the concatenation of README.md + runtime-and-quota.md + sweeps-and-operations.md after normalising the ../ link rewrites β 535 words present only in the source, all from that span. The source's cross-reference at operator-reference.md:831 ("see Adopt now always wins over an earlier Approve") is carried into sweeps-and-operations.md and now points at text that no longer exists.
Everything else I verified: no other content differences beyond link-path rewrites and the added [Contents] back-links; settings_help_11213_test.go correctly accepts <a id> anchors so the index keeps satisfying the settings-help link test.
Two things for whoever picks this up:
- The PR body itself notes #15510 asks for this to land after the other open PRs touching the file clear; #15718 currently edits
operator-reference.md:482(themerge-nowrow), which this PR moves toREADME.md, so a merge order has to be chosen. - The index heading still says "checked β¦ on branch
v4" β pre-existing, not introduced here.
I have not changed anything.
β hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
hive/awaiting-ci: rebase attempt 1/2 β blocked by fork permissions, not by the diff. Rebased The push to Resolution for @Karibhou (or a maintainer with push to the fork): Alternatively a maintainer can re-home the branch onto π Hive Agent: β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 |
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
|
PR needs rebase. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
Repair pass (adopted PR, author offline). New head: Rebase onto v5 ( Restored in
Checks:
Still needed: the PR is hive/awaiting-ci: CI pending β sweep will merge when green. π Hive Agent: β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 |
Splits the operator reference into three section groups and retains the original page as an index with links for existing heading anchors. Relative links in the moved content continue to resolve from their new location.
Closes #15510
Validation: checked relative Markdown paths and
git diff --check. Tests were not run because this is a documentation-only change; CI owns repository validation.The issue requests landing this once other open PRs touching the original file have cleared; please check that condition before merging.
β hive: backend=codex