Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-human-merge-breaking-title.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Auto-merge never merges a breaking-titled (`⚠️`/`⚠`) or `needs-owner-merge`-labelled PR: one shared `RequiresHumanMerge` predicate skips it in every lane and the merge train, the tracker parks it at 090 *Ready for human merge · human merge* ("breaking change — owner merges") with **Approve & merge as maintainer** as the lead action, and hive posts one writeback-gated comment saying it waits for a human. Configurable via `auto_merge.human_merge_title_prefixes` and `auto_merge.human_merge_labels`.
4 changes: 4 additions & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package main

import (
Expand Down Expand Up @@ -81,6 +81,7 @@
"github.com/hivecommons/hive/pkg/snapshot"
"github.com/hivecommons/hive/pkg/spokealerts"
"github.com/hivecommons/hive/pkg/stageengine"
"github.com/hivecommons/hive/pkg/stageengine/prstage"
"github.com/hivecommons/hive/pkg/stagelabels"
"github.com/hivecommons/hive/pkg/timeline"
"github.com/hivecommons/hive/pkg/tokens"
Expand Down Expand Up @@ -2569,6 +2570,7 @@
// Human-merge paths (#11038): read through b.cfg on every evaluation so
// a reload of auto_merge.human_merge_paths applies without a restart.
autoMergeOpts.HumanMergePaths = func(repo string) []string { return humanMergePathsFor(b.cfg, repo) }
autoMergeOpts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(b.cfg) }
autoMergeOpts.RequireCurrentBase = func(repo string) bool { return b.cfg != nil && b.cfg.AutoMerge.RequireCurrentBaseFor(repo) }
autoMergeOpts.RequireCurrentBaseStrict = func(repo string) bool {
return b.cfg != nil && b.cfg.AutoMerge.RequireCurrentBaseStrictFor(repo)
Expand Down Expand Up @@ -9454,6 +9456,7 @@
opts.RepoAutoMergeEnabled = func(repo string) bool { return cfg.RepoAutoMergeEnabled(repo) }
opts.RepoOnGitHub = func(repo string) bool { return cfg.RepoOnGitHub(repo) }
opts.HumanMergePaths = func(repo string) []string { return humanMergePathsFor(cfg, repo) }
opts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(cfg) }
opts.RequireCurrentBase = func(repo string) bool { return cfg.AutoMerge.RequireCurrentBaseFor(repo) }
opts.RequireCurrentBaseStrict = func(repo string) bool { return cfg.AutoMerge.RequireCurrentBaseStrictFor(repo) }
opts.MergeForwardTrustedHuman = func(repo string) bool { return cfg.AutoMerge.MergeForwardTrustedHumanFor(repo) }
Expand Down Expand Up @@ -10036,6 +10039,7 @@
if cfg != nil {
approveOpts.RepoAutoMergeEnabled = cfg.RepoAutoMergeEnabled
approveOpts.HumanMergePaths = func(repo string) []string { return humanMergePathsFor(cfg, repo) }
approveOpts.HumanMergeRule = func() prstage.HumanMergeRule { return humanMergeRuleFor(cfg) }
approveOpts.TrustedBotAuthors = func() map[string]bool { return cfg.AutoMerge.TrustedBotAuthorSet() }
}
approveEngine := automerge.New(ghClient, approveOpts)
Expand Down
11 changes: 11 additions & 0 deletions src/cmd/hive/main_helpers.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package main

import (
Expand All @@ -15,6 +15,7 @@
"github.com/hivecommons/hive/pkg/github/automerge"
"github.com/hivecommons/hive/pkg/holdguard"
"github.com/hivecommons/hive/pkg/intent"
"github.com/hivecommons/hive/pkg/stageengine/prstage"
"github.com/hivecommons/hive/pkg/writeback"
)

Expand Down Expand Up @@ -409,6 +410,16 @@
return cfg.AutoMerge.HumanMergePathsFor(repo)
}

// humanMergeRuleFor reads auto_merge.human_merge_title_prefixes /
// human_merge_labels through cfg on every call so a reload applies
// (hivecommons/hive#15442). A nil config means the defaults.
func humanMergeRuleFor(cfg *config.Config) prstage.HumanMergeRule {
if cfg == nil {
return prstage.HumanMergeRule{}
}
return cfg.AutoMerge.HumanMergeRule()
}

// selfMergeIntentGate builds the intent-tier gate the App self-merge sweep
// enforces (#6258) from the same config and bead evidence the human merge
// lane uses. Enforce is read through cfg on every call so a reload applies.
Expand Down
1 change: 1 addition & 0 deletions src/docs/dashboard-copy-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ The new hover, verbatim (title line omitted):
| `stageTrackerUntrustedAuthorWhy` (all 10 trust reasons, summed) | question, reason text, delegated outcome | 314 | 68 | `TestStageTrackerHumanMergeSaysItOnce` (no config keys, no jargon) |
| `stageTrackerUntrustedAuthorFix` (new; the how-to-trust line, Details only) | Details | — | 81 | same |
| `stageTrackerHumanMergeReasonWords` tips (9 codes, summed) | chip hover, 090 chevron tip | 227 | 101 | `TestStageTrackerHumanMergeReason` |
| `stageTrackerHumanMergeReasonWords[breaking-change]` (new: chip `human merge`, caption *Ready for human merge (breaking change — owner merges)*) | chip, caption, chevron tip, `new.gates[]` | — | 14 | `TestStageTrackerHumanMergeRequiredRow` |
| `HumanMergeReasonText` composition (090 untrusted author) | chevron tip, row tooltip, feed | 43 + 24 ("Until then a maintainer merges — Approve & merge…") | 11 | `TestStageTrackerHumanMergeSaysItOnce` |
| `HumanMergeReasonText` admitted prefix | same | 41 | 9 | `TestStageTrackerDecisionForHumanMerge/admitted…` |
| `stageTrackerCaption` 090 | row caption, feed | 19 | 7 | `TestStageTrackerCaption…` cases in `stage_tracker_test.go` |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -774,7 +774,7 @@ Side stages share a column rather than adding columns:

The author legend is a blue Hive hexagon, purple contributor-agent robot or teal human silhouette. The kind is `author/*`, inferred from the snapshot if its label is absent; the link tooltip names the login. On Claimed, the actor is the claim holder; on PR in progress and Returned to contributor it is the author. Hive owns review, adoption and auto-merge work; a human owns a human decision or manual merge. The payload's `stage_actor` is the authoritative actor (see [Who is on it](#who-is-on-it-actor-icons)).

At 090 the row explains why: `· workflow files`, `· tests removed`, `· manual-merge policy`, `· branch protection`, `· merge method`, `· auto-merge off`, `· untrusted author`, `· unauthorized`, `· reviewer deferred` or `· policy` ([#14658](https://github.com/hivecommons/hive/issues/14658)). `human_merge_reason` is a `prstage.HumanMergeReason*` code from the stage record's lane reason; `human_merge_reason_text` supplies the sentence and next step. For example, workflow-file changes require Merge on GitHub. Manual-merge text can read *Awaiting human merge · workflow files · approved by @login*; search and needs-attention text carry the same reason. A nested PR mirrors `human_approver`, `manual_merge` and both reason fields on `linked_prs`.
At 090 the row explains why: `· workflow files`, `· tests removed`, `· manual-merge policy`, `· branch protection`, `· merge method`, `· auto-merge off`, `· untrusted author`, `· unauthorized`, `· reviewer deferred`, `· policy` or `· human merge` (a ⚠️-titled or `needs-owner-merge` PR — the caption reads *Ready for human merge (breaking change — owner merges)*, `human_merge_reason` is `breaking-change`, and hive never merges it, so **Approve — let hive merge** is greyed) ([#14658](https://github.com/hivecommons/hive/issues/14658)). `human_merge_reason` is a `prstage.HumanMergeReason*` code from the stage record's lane reason; `human_merge_reason_text` supplies the sentence and next step. For example, workflow-file changes require Merge on GitHub. Manual-merge text can read *Awaiting human merge · workflow files · approved by @login*; search and needs-attention text carry the same reason. A nested PR mirrors `human_approver`, `manual_merge` and both reason fields on `linked_prs`.

### Pairing, rows and counts

Expand Down
22 changes: 22 additions & 0 deletions src/docs/hive-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,28 @@ auto_merge:
enabled: true # default; set false to leave such PRs held
```

### Breaking-titled or `needs-owner-merge` PRs wait for a human

A PR whose trimmed title starts with `⚠️` (U+26A0, with or without the VS16
selector — the PR-title convention for a breaking change) or that carries a
`needs-owner-merge` label is never merged by hive. One shared predicate,
`automerge.RequiresHumanMerge(pr)`, is evaluated once per PR where each lane
already computes eligibility (the App self-merge, label-queued, trusted-author
and contributor prefilters, and the refetch just before a merge), so the merge
train — which draws its candidates from the same prefilters — never fronts or
carries such a PR either. The prefixes and labels are configurable via
`auto_merge.human_merge_title_prefixes` and `auto_merge.human_merge_labels`
(see the operator reference); an empty list turns that half of the rule off.

When the PR is otherwise merge-ready (green checks, approvals satisfied) the
stage tracker parks it at **090 Ready for human merge** with the chip
*human merge* and the reason *breaking change — owner merges*; the owner
merges it with **Approve & merge as maintainer** (the existing gated
operator path) or on GitHub. Hive posts one comment, through the writeback
gate, saying it will wait for a human. The rule exists because a ⚠️-titled
PR was auto-merged by the trusted-author lane while its owner was still
deciding whether to ship it.

### Trusted-author auto-merge

`auto_merge.trusted_authors` is a third, default-off sweep tier for
Expand Down
4 changes: 4 additions & 0 deletions src/docs/operator-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,8 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through
| `auto_merge.allow_unprotected_base` | Deprecated no-op. | Accepted so older configs keep loading. `hive-merge` now merges into any protected or unprotected branch the App can write, subject to the CI-evidence gate and GitHub's own merge rules. |
| `auto_merge.no_ci_ok` | Empty by default. | Explicit repo list whose zero-CI merge-request verdict may pass; failing or pending CI evidence is still enforced. |
| `auto_merge.human_merge_paths` | Unset (off). | Per-repo map of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`) for paths a person must merge. Applies to every merge lane (App self-merge, trusted-author, label-queued, merge-request relay) whatever the intent tier; a matching PR is held with one comment, and an incomplete changed-file list fails closed. Details in the sweep key table below. |
| `auto_merge.human_merge_title_prefixes` | `["⚠️", "⚠"]` | Title prefixes (after trimming) that mark a PR as a breaking change a person must merge. Every auto-merge lane and the merge train skip the PR; the tracker parks it at 090 *Ready for human merge · human merge*. Set to `[]` to disable. |
| `auto_merge.human_merge_labels` | `["needs-owner-merge"]` | Labels (case-insensitive) that mark a PR a person must merge; same effect as the title prefixes. Set to `[]` to disable. |
| `forgestate.enabled` | `false` | Runs the per-repo ForgeState cache ([#13373](https://github.com/hivecommons/hive/issues/13373)) and switches the automerge sweep lanes (self-authored, trusted-author, contributor lane) to it: no `/pulls` list per 10 s tick, passes triggered by `check_suite`/`check_run`/`status`/`pull_request_review`/`pull_request` webhooks for the affected PR plus a 5-minute floor pass, and a 60 s freshness-bounded read-through before every merge; a stale snapshot never merges ([#13377](https://github.com/hivecommons/hive/issues/13377)). `forgestate.reconcile_interval_s` (900), `freshness_bound_s` (60), `drift_threshold` (0.05) and `search_budget` (20) tune the cache. |
| `evidence.enabled` | On by default. | The review relay writes one [review evidence bundle](review-evidence.md) per PR head to `/data/evidence/<owner>/<repo>/<number>/<head>.json` when it records a verdict or posts a review; the sentinel sweep adds its findings to the flagged head's bundle; and every merge path adds the head's CI check-run summary, the human approvals and label changes, and the merge event. Owners and mergers read bundles through `GET /api/review/evidence` and `GET /api/review/evidence/list` (see the [API reference](api-reference.md)). Set `false` to stop writing new bundles; existing ones are left in place. |
| `evidence.signing_key_file` | Unset (bundles unsigned). | Path to an Ed25519 private key (32-byte seed or 64-byte key, hex or base64). When set and readable, bundles are signed. Dashboard/API readers require a valid signature under its public half and fail closed when the configured key is unavailable; unsigned mode verifies only the bundle content hash. Writers still record `"signed": false` when the key is empty, absent or unusable and log a warning for an unusable key, so an evidence write failure never blocks review or merge work. Keep the key off shared hosts. |
Expand Down Expand Up @@ -430,6 +432,8 @@ advanced into the merge path.
| `auto_merge.allow_unprotected_base` | deprecated no-op | Accepted for compatibility only. [`hive-merge`](hive-merge.md) no longer refuses solely because a base branch has no GitHub branch protection; it may merge into any branch the App can write after positive CI evidence. |
| `auto_merge.no_ci_ok` | unset (refuse) | **Merge-request watcher key, not a sweep key.** Per-repo opt-in that downgrades only the "unverified" CI verdict (zero statuses, check runs, and workflow runs) to green, for adopted repos with no CI by design. Red and pending verdicts are never downgraded (#6281). See [hive-merge.md](hive-merge.md). |
| `auto_merge.human_merge_paths` | unset | Per-repo map of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`) for paths a person must merge, e.g. `Danathar/goodreads-mcp: [".claude/settings.json", ".claude/hooks/**"]`. Every App merge path honors it: the automerge sweep lanes (App self-merge, trusted-author, label-queued) and the agent merge-request relay refuse a PR that touches a listed path, add `hold`, and post one `<!-- hive-human-merge-path -->` comment naming the path(s); a person must merge it. If the changed-file list cannot be fetched completely for a configured repo, the merge is withheld (#11038, #11039). |
| `auto_merge.human_merge_title_prefixes` | `["⚠️", "⚠"]` | PR-title prefixes that mean "breaking change — owner merges" (U+26A0 with or without the VS16 selector by default, matched after trimming leading whitespace). One shared predicate, `automerge.RequiresHumanMerge(pr)`, runs where each lane computes eligibility — App self-merge, label-queued, trusted-author and contributor lanes, plus the refetch before a merge — so a matching PR is never merged by hive and never fronts a merge train, however green and however approved. The PR parks at stage 090 *Ready for human merge* with the `human merge` chip and reason *breaking change — owner merges*; the owner merges it with **Approve & merge as maintainer** or on GitHub. Hive posts one writeback-gated comment saying it will wait for a human. Set to `[]` to turn the title rule off. Added after a ⚠️-titled PR was auto-merged by the trusted-author lane while its owner was still deciding whether to ship it. |
| `auto_merge.human_merge_labels` | `["needs-owner-merge"]` | Labels (case-insensitive, trimmed) that carry the same "a person merges this" meaning as the title prefixes above; either match is enough. Set to `[]` to turn the label rule off. |
| `auto_merge.require_current_base` | unset | Repo list (`owner/repo`) with an explicit **on** override for the current-base merge gate (Settings → Repos → "Merge only on current base"). On a gated repo the App self-merge, trusted-author and contributor lanes only merge a head that contains the current base tip. A green head tested against an older base is updated with GitHub update-branch (a merge commit; no author commit is rewritten) and merges once CI is green on the new head, so a semantic conflict with work merged since turns that PR red instead of breaking the base ([#13634](https://github.com/hivecommons/hive/issues/13634), [#15335](https://github.com/hivecommons/hive/issues/15335)). Costs one compare call per merge candidate. Listing a repo here is also **strict**: a behind head the App cannot update (fork without maintainer edits, branch protection or a missing `contents: write`) is parked (`fork-not-editable` / `update-branch`) rather than merged as tested. Wins over `skip_current_base` and over the default. |
| `auto_merge.require_current_base_default` | `false` | Hive-wide default of the current-base gate for repos in neither `require_current_base` nor `skip_current_base` (Settings → Features → Auto-merge → "Merge only on current base"). **Off** by default: the merge train already update-branches overlapping siblings, so the gate is being soaked per repo (hive's own hive first, via `require_current_base`) before any hive turns it on everywhere. When `true`, a behind head the App cannot update merges as it was tested, with one WARN per PR (`automerge current-base gate: … merging as tested`), so fork-heavy repos are not parked wholesale. |
| `auto_merge.skip_current_base` | unset | Repo list (`owner/repo`) with an explicit **off** override for the current-base gate (Settings → Repos → "Merge only on current base" unchecked): a green head there merges even if the base has moved, whatever `require_current_base_default` says. An explicit `require_current_base` entry wins over this list. |
Expand Down
41 changes: 41 additions & 0 deletions src/pkg/config/automerge_human_merge_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
package config

import (
"reflect"
"testing"

"github.com/hivecommons/hive/pkg/stageengine/prstage"
)

func TestAutoMergeHumanMergeRuleDefaultsAndOverrides(t *testing.T) {
var unset AutoMergeConfig
if got := unset.HumanMergeRule(); !reflect.DeepEqual(got.TitlePrefixes, prstage.DefaultHumanMergeTitlePrefixes) || !reflect.DeepEqual(got.Labels, prstage.DefaultHumanMergeLabels) {
t.Fatalf("unset keys should yield the defaults, got %+v", got)
}
if ok, _ := unset.HumanMergeRule().RequiresHumanMerge("\u26a0\ufe0f break", nil); !ok {
t.Fatal("default rule must catch a ⚠️ title")
}

off := AutoMergeConfig{HumanMergeTitlePrefixes: []string{}, HumanMergeLabels: []string{}}
if got := off.HumanMergeRule(); len(got.TitlePrefixes) != 0 || got.TitlePrefixes == nil || len(got.Labels) != 0 || got.Labels == nil {
t.Fatalf("explicit empty lists must stay empty (non-nil), got %+v", got)
}
if ok, _ := off.HumanMergeRule().RequiresHumanMerge("\u26a0\ufe0f break", []string{"needs-owner-merge"}); ok {
t.Fatal("empty lists must switch the rule off")
}

custom := AutoMergeConfig{HumanMergeTitlePrefixes: []string{"BREAKING:"}, HumanMergeLabels: []string{"ship-by-owner"}}
prefixes := custom.HumanMergeTitlePrefixesEffective()
prefixes[0] = "mutated"
if custom.HumanMergeTitlePrefixes[0] != "BREAKING:" {
t.Fatal("HumanMergeTitlePrefixesEffective must return a copy")
}
labels := custom.HumanMergeLabelsEffective()
labels[0] = "mutated"
if custom.HumanMergeLabels[0] != "ship-by-owner" {
t.Fatal("HumanMergeLabelsEffective must return a copy")
}
if ok, reason := custom.HumanMergeRule().RequiresHumanMerge("x", []string{"Ship-By-Owner"}); !ok || reason != "label:ship-by-owner" {
t.Fatalf("custom label rule = %v %q", ok, reason)
}
}
Loading
Loading