diff --git a/bin/hive-open-issue.sh b/bin/hive-open-issue.sh index d2806df954..c9f56e6f74 100755 --- a/bin/hive-open-issue.sh +++ b/bin/hive-open-issue.sh @@ -17,7 +17,7 @@ # # Usage (drop-in for the common gh shapes): # hive-open-issue --repo --title "" [--body ""|--body-file f] [--label a,b] [--parent ] [--blocked-by ] [--close-on-merge] [--needs-decision] [--no-consolidate ] -# hive-open-issue comment --repo --body "" [--needs-decision|--withdraw-decision] [--blocked-by ] [--blocked-on-pr ] +# hive-open-issue comment --repo --body "" [--needs-decision|--withdraw-decision] [--blocked-by ] [--blocked-on-pr ] # hive-open-issue claim --repo # hive-open-issue close --repo [--override-reason "..."] # hive-open-issue label --repo [--label a,b] [--remove-label c] @@ -73,9 +73,10 @@ # request is unrelated work that merely shares a file or component with one. # The reason is required, and the watcher records it in the result. # -# --blocked-on-pr (comment only) parks the issue on open PR in the -# same repo (hivecommons/hive#13093): use it when the code a finding names -# exists only in an unmerged PR, so there is nothing to ship until it lands. +# --blocked-on-pr (comment only) parks the issue on open PR +# in the same repo, or on owner/repo#n in another one +# (hivecommons/hive#13093): use it when the code a finding names exists only +# in an unmerged PR, so there is nothing to ship until it lands. # The watcher prefixes the note with the blocked-on marker, strips any # @-mentions (the PR's author is not asked to do the hive's work), adds the # `blocked` label and removes `help wanted`; the hive lifts the label itself @@ -152,6 +153,7 @@ NEEDS_DECISION=0 WITHDRAW_DECISION=0 STEP_KIND=""; RELEASE_TAG=""; RELEASE_TARGET=""; STEP_REQUESTED=0 BLOCKED_ON_PR="" +BLOCKED_ON_PR_REPO="" NO_CONSOLIDATE="" NO_CONSOLIDATE_SET=0 DRY_RUN=0 @@ -280,8 +282,14 @@ if [ -n "${BLOCKED_ON_PR:-}" ] && [ "$KIND" != "comment" ]; then echo "hive-open-issue: --blocked-on-pr only applies to a comment; nothing was written." >&2 exit 2 fi +# owner/repo#n names a PR in another repository: split it into the number +# and the repo the watcher reads it from. +if [ -n "${BLOCKED_ON_PR:-}" ] && [[ "$BLOCKED_ON_PR" =~ ^([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)#([0-9]+)$ ]]; then + BLOCKED_ON_PR_REPO="${BASH_REMATCH[1]}" + BLOCKED_ON_PR="${BASH_REMATCH[2]}" +fi if [ -n "${BLOCKED_ON_PR:-}" ] && ! [[ "$BLOCKED_ON_PR" =~ ^[0-9]+$ && "$BLOCKED_ON_PR" -gt 0 ]]; then - echo "hive-open-issue: --blocked-on-pr needs a positive PR number; nothing was written." >&2 + echo "hive-open-issue: --blocked-on-pr needs a positive PR number or owner/repo#n; nothing was written." >&2 exit 2 fi @@ -399,11 +407,12 @@ REMOVE_LABELS_JSON="$(printf '%s\n' "${REMOVE_LABELS[@]:-}" | python3 -c 'import REVIEWERS_JSON="$(printf '%s\n' "${REVIEWERS[@]:-}" | python3 -c 'import json,sys; print(json.dumps([x.rstrip("\n") for x in sys.stdin if x.rstrip("\n")]))')" TEAM_REVIEWERS_JSON="$(printf '%s\n' "${TEAM_REVIEWERS[@]:-}" | python3 -c 'import json,sys; print(json.dumps([x.rstrip("\n") for x in sys.stdin if x.rstrip("\n")]))')" BLOCKED_BY_JSON="$(printf '%s\n' "${BLOCKED_BY[@]:-}" | python3 -c 'import json,sys; print(json.dumps([x.rstrip("\n") for x in sys.stdin if x.rstrip("\n")]))')" -python3 - "$TEMP_FILE" "$REQ_FILE" "$KIND" "$REPO" "$TITLE" "${OVERRIDE_REASON:-$BODY}" "$AGENT" "$LABELS_JSON" "${NUMBER:-0}" "$DRY_RUN" "${PARENT:-0}" "$REMOVE_LABELS_JSON" "$REVIEWERS_JSON" "$TEAM_REVIEWERS_JSON" "$BLOCKED_BY_JSON" "$NEEDS_DECISION" "${BLOCKED_ON_PR:-0}" "$STEP_KIND" "$RELEASE_TAG" "$RELEASE_TARGET" "$STEP_REQUESTED" "$NO_CONSOLIDATE" "$WITHDRAW_DECISION" <<'PY' +python3 - "$TEMP_FILE" "$REQ_FILE" "$KIND" "$REPO" "$TITLE" "${OVERRIDE_REASON:-$BODY}" "$AGENT" "$LABELS_JSON" "${NUMBER:-0}" "$DRY_RUN" "${PARENT:-0}" "$REMOVE_LABELS_JSON" "$REVIEWERS_JSON" "$TEAM_REVIEWERS_JSON" "$BLOCKED_BY_JSON" "$NEEDS_DECISION" "${BLOCKED_ON_PR:-0}" "$STEP_KIND" "$RELEASE_TAG" "$RELEASE_TARGET" "$STEP_REQUESTED" "$NO_CONSOLIDATE" "$WITHDRAW_DECISION" "$BLOCKED_ON_PR_REPO" <<'PY' import json, os, re, sys temporary, path, kind, repo, title, body, agent, labels, number, dry_run, parent, remove_labels, reviewers, team_reviewers, blocked_by, needs_decision, blocked_on_pr = sys.argv[1:18] no_consolidate = sys.argv[22] withdraw_decision = sys.argv[23] +blocked_on_pr_repo = sys.argv[24].strip() labels = [part.strip() for value in json.loads(labels) for part in value.split(",") if part.strip()] remove_labels = [part.strip() for value in json.loads(remove_labels) @@ -518,6 +527,9 @@ if kind == "comment" and int(blocked_on_pr) > 0: # --blocked-on-pr: the watcher adds the marker and the `blocked` label # itself (hivecommons/hive#13093). req["blocked_on_pr"] = int(blocked_on_pr) + if blocked_on_pr_repo: + # owner/repo#n: the PR lives in another repository. + req["blocked_on_pr_repo"] = blocked_on_pr_repo if dry_run == "1": # Honour --dry-run: show exactly what would be queued, write nothing. print("hive-open-issue: DRY RUN — no request written, nothing will be created. Would write %s:" % path) @@ -541,7 +553,7 @@ if [ "$KIND" = "comment" ]; then echo "hive-open-issue: will withdraw your decision park on $REPO#$NUMBER (refused if the park is not yours)" fi if [ -n "${BLOCKED_ON_PR:-}" ]; then - echo "hive-open-issue: will park the issue on $REPO#$BLOCKED_ON_PR (blocked label; help wanted removed; no one is @-mentioned)" + echo "hive-open-issue: will park the issue on ${BLOCKED_ON_PR_REPO:-$REPO}#$BLOCKED_ON_PR (blocked label; help wanted removed; no one is @-mentioned)" fi elif [ "$KIND" = "claim" ]; then echo "hive-open-issue: requested claim of $REPO#$NUMBER (hive/claimed-by-$AGENT label)" diff --git a/bin/test_hive_open_issue.sh b/bin/test_hive_open_issue.sh index 0cb9ca2223..a346808f0e 100755 --- a/bin/test_hive_open_issue.sh +++ b/bin/test_hive_open_issue.sh @@ -245,6 +245,45 @@ check "comment --blocked-by refusal writes no request" "" "$(find_req badblocked rm -rf "$REQ_DIR" mkdir -p "$REQ_DIR" +# --blocked-on-pr takes a same-repo number or owner/repo#n (a PR in another +# repository): the request carries the number and, for the second, its repo. +run_script "blockedonprbot" comment --repo "hiveorg/widgets" 7 --body "Lands after the upstream change." \ + --blocked-on-pr "hiveorg/gadgets#42" >/dev/null +REQ_FILE="$(find_req blockedonprbot)" +if [ -n "$REQ_FILE" ]; then + GOT_BLOCKED="$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('blocked_on_pr'), d.get('blocked_on_pr_repo'))" "$REQ_FILE")" + check "comment --blocked-on-pr owner/repo#n carries the number and the repo" "42 hiveorg/gadgets" "$GOT_BLOCKED" +else + echo " FAIL: request file not created for --blocked-on-pr owner/repo#n test" + FAIL=$((FAIL + 1)) +fi + +rm -rf "$REQ_DIR" +mkdir -p "$REQ_DIR" + +run_script "blockedonprsamebot" comment --repo "hiveorg/widgets" 7 --body "Lands after #41." --blocked-on-pr 41 >/dev/null +REQ_FILE="$(find_req blockedonprsamebot)" +if [ -n "$REQ_FILE" ]; then + GOT_BLOCKED="$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d.get('blocked_on_pr'), d.get('blocked_on_pr_repo'))" "$REQ_FILE")" + check "comment --blocked-on-pr stays same-repo (no blocked_on_pr_repo)" "41 None" "$GOT_BLOCKED" +else + echo " FAIL: request file not created for --blocked-on-pr test" + FAIL=$((FAIL + 1)) +fi + +rm -rf "$REQ_DIR" +mkdir -p "$REQ_DIR" + +set +e +run_script "badblockedonprbot" comment --repo "hiveorg/widgets" 7 --body "x" --blocked-on-pr "hiveorg/gadgets#" >/dev/null 2>&1 +BAD_RC=$? +set -e +check "comment --blocked-on-pr refuses a malformed owner/repo#n (exit 2)" "2" "$BAD_RC" +check "comment --blocked-on-pr refusal writes no request" "" "$(find_req badblockedonprbot)" + +rm -rf "$REQ_DIR" +mkdir -p "$REQ_DIR" + # --- Section 3d: --close-on-merge flag (filing-time opt-in, #10304) --- run_script "closeonmergebot" --repo "hiveorg/widgets" --title "Sweep finding" --body "found by reading the code" --close-on-merge diff --git a/changelog.d/added-blocked-pr-depends-on.md b/changelog.d/added-blocked-pr-depends-on.md new file mode 100644 index 0000000000..fc7f2b5f8b --- /dev/null +++ b/changelog.d/added-blocked-pr-depends-on.md @@ -0,0 +1 @@ +- **A PR now waits for the pull requests its `Depends-on:` lines name, in the same repository or another one.** Before, only the dashboard's critical path read `Depends-on: #N` / `owner/repo#N`, and nothing stopped a merge lane from landing the PR first, so a person had to hold it and remember to release it. The blocked sweep (every 5 minutes, configured repositories) now puts the existing `blocked` label on an open, non-draft PR whose `Depends-on:` names an open pull request, with one `` comment per open target (the marker a relay's blocked verdict already writes), and lifts it with one `` note once every marked pull request has merged or closed (the note says when one closed without merging) or is no longer listed. Every merge lane now refuses a `blocked` PR (`label:blocked`): self-authored and trusted-bot, trusted-author, contributor (whatever `exclude_labels` says), the queued merge-request lane, the merge train, the native merge queue and the dashboard's merge verdict and human-merge shortcuts. Like `hold` it is a gate, not a stage: the route and the activity monitor row name the target (`blocked on owner/repo#N`, `Blocked on PR #N — lifts when it merges`). People win: a person's `blocked` is never placed over or lifted, and a person who removes the hive's `blocked` is not overridden for the same dependencies (a newly listed open one re-arms it). Writes go through the write-back gate (`gate_comment`). An issue named in `Depends-on:` stays display-only. `hive-open-issue comment --blocked-on-pr` now also takes `owner/repo#n`. diff --git a/src/cmd/hive/main_sweeps.go b/src/cmd/hive/main_sweeps.go index 09c1157189..3495e04cd1 100644 --- a/src/cmd/hive/main_sweeps.go +++ b/src/cmd/hive/main_sweeps.go @@ -1281,11 +1281,18 @@ func runBlockedIssuesSweepIfDue(ctx context.Context, ghClient *github.Client, cf res, err := ghClient.SweepBlockedIssues(ctx, github.BlockedSweepOptions{Repos: repos}) if err != nil { logger.Warn("blocked issues reconciliation sweep failed", "error", err) - return - } - if res.Unblocked+res.Retargeted+res.Stripped+res.Errors > 0 { + } else if res.Unblocked+res.Retargeted+res.Stripped+res.Errors > 0 { logger.Info("blocked issues reconciliation sweep complete", "items", res.Items, "unblocked", res.Unblocked, "retargeted", res.Retargeted, "help_wanted_stripped", res.Stripped, "errors", res.Errors) } + // The same sweep holds PRs on the open pull requests their Depends-on + // lines name, and lifts that hold once they land. + prRes, err := ghClient.SweepBlockedPRDependencies(ctx, github.BlockedSweepOptions{Repos: repos}) + if err != nil { + logger.Warn("blocked PR dependency sweep: a repository could not be listed", "error", err) + } + if prRes.Placed+prRes.Marked+prRes.Unblocked+prRes.Suppressed+prRes.Errors > 0 { + logger.Info("blocked PR dependency sweep complete", "prs", prRes.PRs, "placed", prRes.Placed, "marked", prRes.Marked, "released_by_person", prRes.Released, "unblocked", prRes.Unblocked, "suppressed", prRes.Suppressed, "errors", prRes.Errors) + } } // runDuplicateSweepIfDue clusters open PRs by changed-file set and suggests diff --git a/src/cmd/hive/merge_eligibility.go b/src/cmd/hive/merge_eligibility.go index d2d8543bd8..134281379a 100644 --- a/src/cmd/hive/merge_eligibility.go +++ b/src/cmd/hive/merge_eligibility.go @@ -940,6 +940,13 @@ func automergeBlockLabelReason(labels []string, trusted bool) string { return "label:hold" } } + // Last, as in the lanes' labelBlockReason: a PR held on its Depends-on + // targets (or a person's `blocked`) is never merge-eligible. + for _, label := range labels { + if strings.EqualFold(strings.TrimSpace(label), github.BlockedLabel) { + return "label:" + github.BlockedLabel + } + } return "" } diff --git a/src/cmd/hive/merge_eligibility_blocked_test.go b/src/cmd/hive/merge_eligibility_blocked_test.go new file mode 100644 index 0000000000..2ef9c749ef --- /dev/null +++ b/src/cmd/hive/merge_eligibility_blocked_test.go @@ -0,0 +1,24 @@ +package main + +import "testing" + +// The dashboard's merge verdict refuses a `blocked` PR like the lanes do, so +// a PR held on its Depends-on targets never reads merge-eligible. A hold on +// the same PR still reads as the hold. +func TestAutomergeBlockLabelReasonBlocked(t *testing.T) { + for _, tc := range []struct { + labels []string + want string + }{ + {[]string{"blocked"}, "label:blocked"}, + {[]string{"kind/bug", "Blocked"}, "label:blocked"}, + {[]string{"blocked", "hold"}, "label:hold"}, + {[]string{"kind/bug"}, ""}, + } { + for _, trusted := range []bool{true, false} { + if got := automergeBlockLabelReason(tc.labels, trusted); got != tc.want { + t.Fatalf("automergeBlockLabelReason(%v, %v) = %q, want %q", tc.labels, trusted, got, tc.want) + } + } + } +} diff --git a/src/docs/dashboard.md b/src/docs/dashboard.md index 97e4991444..28297770ed 100644 --- a/src/docs/dashboard.md +++ b/src/docs/dashboard.md @@ -1017,6 +1017,11 @@ are untouched. (`owner/repo#N` names another repository). Agents write it when they know the order. A prerequisite in a tracked repository that is no longer open is done and drops out; one in an untracked repository stays as `external`. + The line also holds the merge: while a pull request it names is open, the + blocked sweep puts `blocked` on the PR and no merge lane merges it, and + the row reads `Blocked on PR #N — lifts when it merges`. See + [`blocked`](labels-and-control-signals/reference.md#blocked). A + prerequisite that is an issue stays display-only here. - An issue waits on the open PR whose closing link (`Fixes`, `Closes`, `Resolves #N`, or GitHub's own closing reference) names it, and on its open GitHub "blocked by" issues. diff --git a/src/docs/hive-open-issue.md b/src/docs/hive-open-issue.md index 531a8ac125..2528a94cf1 100644 --- a/src/docs/hive-open-issue.md +++ b/src/docs/hive-open-issue.md @@ -43,7 +43,7 @@ Shapes are selected by an optional leading positional keyword (`comment`, ```sh hive-open-issue --repo --title "" [--body ""|--body-file f] [--label a,b] [--parent ] [--blocked-by ] [--needs-decision] [--no-consolidate ] [--step-kind release --release-tag --release-target ] [--claim] -hive-open-issue comment --repo --body "" [--needs-decision|--withdraw-decision] [--blocked-by ] [--blocked-on-pr ] +hive-open-issue comment --repo --body "" [--needs-decision|--withdraw-decision] [--blocked-by ] [--blocked-on-pr ] hive-open-issue claim --repo hive-open-issue label --repo [--label a,b] [--remove-label c] hive-open-issue request-review --repo [--reviewer a,b] [--team-reviewer t] @@ -68,7 +68,7 @@ hive-open-issue request-review --repo [--reviewer a,b] | `--withdraw-decision` | — | comment | take back a decision park you placed yourself; see [Withdrawing your own park](#withdrawing-your-own-park). Cannot be combined with `--needs-decision` | | `--claim` | — | issue | file the new issue **and** claim it for this agent in the same request (see [Filing your own next step](#filing-your-own-next-step)). The request carries `"claim": true`; the result reports `claimed`, or `claim_error` when the claim did not land | | `--no-consolidate` | — | issue | requires a non-empty reason; the watcher skips open-issue consolidation (same-subject, file-set and component folds) and files a new issue, echoing the reason as `consolidation_skipped_reason` in the result and logging it. Use it for unrelated work that only shares a file or component with an open issue ([#14360](https://github.com/hivecommons/hive/issues/14360)). The request carries `"no_consolidate_reason"`. A request that declares `--parent` or `--blocked-by` needs no reason: it is a distinct DAG node and never takes the file-set, component or canonical-subject folds, and a genuine create reports `consolidation_skipped_reason` as `parent` or `blocked_by` ([#16065](https://github.com/hivecommons/hive/issues/16065)) | -| `--blocked-on-pr` | — | comment | park the issue on open PR `` in the same repo: the watcher prefixes the note with ``, strips `@`-mentions from it, adds the `blocked` label and removes `help wanted` (see [Blocked on an unmerged PR](#blocked-on-an-unmerged-pr)) | +| `--blocked-on-pr` | — | comment | park the issue on open PR `` in the same repo, or on `owner/repo#n` in another repository (the request then also carries `"blocked_on_pr_repo"`): the watcher prefixes the note with ``, strips `@`-mentions from it, adds the `blocked` label and removes `help wanted` (see [Blocked on an unmerged PR](#blocked-on-an-unmerged-pr)) | | `--number` | — | comment, claim, close, label, request-review | the issue/PR number; a bare positional number or a `.../issues/N` or `.../pull/N` URL is also accepted | | `--dry-run` | `-n` | all | validate the arguments and print the exact request that would be written, then exit `0` **without writing it** — nothing is created, commented, claimed, or closed. **This is how you test the tool.** A live call creates a real GitHub issue/comment/label change under the hive's App identity | @@ -355,6 +355,11 @@ hive-open-issue comment --repo o/r 13093 --blocked-on-pr 13092 \ --body "Blocked on #13092: the flagged file exists only on that PR; nothing to ship until it lands." ``` +A PR in another repository is named `owner/repo#n` +(`--blocked-on-pr acme/gadget#42`); the marker then reads +`` and the sweep lifts the block +when that PR merges or closes. + The watcher prefixes the body with the marker ``, strips any `@login` mention from it (the PR's author is not asked to do the hive's work; address them only in a review comment on their diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index 7d3eaacc62..365cb7db7f 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -94,7 +94,7 @@ Some hive-authored labels look like provenance but are read as signals, so they | `needs-sha` from SHA-hold | Issues | SHA-hold sweep | Trusted-reporter `kind/bug` without a SHA gets this soft label plus the same `` notice instead of `hold`; the issue stays actionable. The sweep removes it once a SHA appears. | Soft (informational) | Hive | Eval tick SHA sweep | Add SHA evidence, or remove the label | `issues.sha_hold_trusted_label` (default `needs-sha`; `hold` restores the hard hold for everyone) | | `do-not-merge` and `do-not-merge*` | Issues, PRs | Exempt filter, merge sweeps, task-list sweep | Permanently exempt; exact match is case-insensitive but prefix matching follows Go `strings.HasPrefix` on the original label. | Hard suppress | Human | Enumeration/sweeps | Human removes | Built-in `PermanentExemptLabels` (`src/pkg/github/client.go:750-755`, `src/pkg/github/client.go:2035-2053`) | | `governor.labels.exempt` entries | Issues, PRs | Exempt filter | Same exempt behavior as `do-not-merge`; wins over required-label admission. Defaults include `nightly-tests`, `LFX`, `meta-tracker`, `auto-qa-tuning-report`, `adopters`, `changes-requested`, `waiting-on-author`. | Hard suppress | Operator/dashboard | Enumeration/sweeps | Remove label or config entry | `governor.labels.exempt` (`src/pkg/config/governor_config.go:175-184`, `src/pkg/config/defaults.go:260-270`) | -| `blocked` | Issues | Enumeration, stage derivation, claim gate, review backlog, blocked sweep | The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr ` parks an existing one; both write ``. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)). When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker, but only on a review-backlog item (its body carries `filed by Hive review backlog`) that GitHub reports no open "blocked by" link on ([#13364](https://github.com/hivecommons/hive/issues/13364)). A human's marker-less `blocked` stays. A contributor relay's `blocked` verdict that named nothing (GitHub records it as the App bot too, because the relay labels with its hub-minted task token) is turned into a `needs-human` ask instead: `needs-human` is added, `blocked` removed and one note says what is missing. Lifting it only sent the issue back to the next agent, which re-applied it, and keeping it hid the issue from every inbox. A blocked verdict whose reason is empty or only the relay footer is booked idle and its label released, like a tooling failure. A marker in a comment counts like one in the body: the row's reason (`blocked on owner/repo#N`) and the band signal name it. With no blocked-on marker, a body deadline `` files it `blocked until ` and the activity monitor's blocked chip reads `re-check at ` ([#13310](https://github.com/hivecommons/hive/issues/13310)). | Hard suppress | Hive (reserved for agents; relay only) | Review backlog filing; blocked-on comment relay | The blocked sweep after each stage-label sync removes it, with one `` note, once the tracked PR is merged or closed, or once a recheck-after deadline passes (`deadline passed; re-triaging`) unless the body also carries ``. An ops-tracking issue on the hive's own project keeps `blocked` once its deadline passes and instead gets soak triage: the hub's `/api/hub/hives` (or, with no hub, the spoke's own `/api/version`) is probed for every `stable`-channel hive (fresh heartbeat, no restart loop, running the candidate `sha256:` digest or `v5 ` named in the body), ONE `` comment is posted, only the checklist lines that evidence proves are ticked, and `` is appended to the body so the sweep does not repeat ([#13311](https://github.com/hivecommons/hive/issues/13311)); a human may remove it at any time | Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`) | +| `blocked` | Issues and PRs | Enumeration, stage derivation, claim gate, review backlog, blocked sweep | The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr ` parks an existing one; both write ``. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)). When a blocked filing folds into an already-open twin, the twin's own state governs: `blocked` is not applied to it, because the folded body (and its marker) is discarded and the twin's earlier evidence stands on its own; the blocked sweep also lifts a hive-applied `blocked` that has no marker, no deadline and no ops-tracking marker, but only on a review-backlog item (its body carries `filed by Hive review backlog`) that GitHub reports no open "blocked by" link on ([#13364](https://github.com/hivecommons/hive/issues/13364)). A human's marker-less `blocked` stays. A contributor relay's `blocked` verdict that named nothing (GitHub records it as the App bot too, because the relay labels with its hub-minted task token) is turned into a `needs-human` ask instead: `needs-human` is added, `blocked` removed and one note says what is missing. Lifting it only sent the issue back to the next agent, which re-applied it, and keeping it hid the issue from every inbox. A blocked verdict whose reason is empty or only the relay footer is booked idle and its label released, like a tooling failure. A marker in a comment counts like one in the body: the row's reason (`blocked on owner/repo#N`) and the band signal name it. With no blocked-on marker, a body deadline `` files it `blocked until ` and the activity monitor's blocked chip reads `re-check at ` ([#13310](https://github.com/hivecommons/hive/issues/13310)). On a PR, `blocked` holds the merge: the blocked sweep puts it on an open, non-draft PR whose `Depends-on:` line names an open pull request (same repository or another), with one `` comment per open target, and every merge lane refuses a `blocked` PR (`label:blocked`). A person's `blocked` is never lifted; a person who removes the hive's `blocked` is not overridden for the same dependencies. | Hard suppress | Hive (reserved for agents; relay only) | Review backlog filing; blocked-on comment relay | The blocked sweep after each stage-label sync removes it, with one `` note, once the tracked PR is merged or closed, or once a recheck-after deadline passes (`deadline passed; re-triaging`) unless the body also carries ``. On a PR it removes the hive's own `blocked` once every marked pull request has merged or closed (the note says when one closed without merging) or is no longer listed under `Depends-on:`. An ops-tracking issue on the hive's own project keeps `blocked` once its deadline passes and instead gets soak triage: the hub's `/api/hub/hives` (or, with no hub, the spoke's own `/api/version`) is probed for every `stable`-channel hive (fresh heartbeat, no restart loop, running the candidate `sha256:` digest or `v5 ` named in the body), ONE `` comment is posted, only the checklist lines that evidence proves are ticked, and `` is appended to the body so the sweep does not repeat ([#13311](https://github.com/hivecommons/hive/issues/13311)); a human may remove it at any time | Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/pr_blocked_depends_on.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`) | | `needs-human` | Issues | Enumeration, task-list sweep, claim escalation gate and un-park sweep | Filters issues from agent kicks and contributor offers; records a human decision requirement. See the [issue reference](#needs-human) and [Maintainer commands](../maintainer-commands.md). | Hard suppress | Hive or human | Enumeration/task-list sweep/kick building | An eligible maintainer's ordinary `/hive approve` or `/hive decision ` lifts it regardless of who applied it; label-driven un-parking remains provenance-sensitive. Keep `hold` if work must stay stopped. Agents may add, never remove it. | Fixed label (`src/pkg/github/client.go:1008-1024`, `src/pkg/github/task_list_sweep.go:611-641`, `src/pkg/github/task_list_sweep.go:874-880`, `src/cmd/hive/claimescalation.go`) | | `needs-spec` from the clarity gate | Issues | Scheduler kick assembly (`runs.triage.clarity_gate`) | With the gate on (default off), a human-filed, unclaimed issue whose clarity score (goal, acceptance criteria, scope, detail, open choices) is under `runs.triage.clarity_gate.threshold` gets one `` comment with concise questions for its author and the `needs-spec` hard-suppress label instead of a claim; it derives `stage/045-needs-decision` and leaves the agent queue ([#13577](https://github.com/hivecommons/hive/issues/13577)). | Hard suppress | Hive | Before kicks are built | The issue author, or a non-hive commenter with write/maintain/admin, replies after the marker and the resume sweep removes the hive's own `needs-spec` and records the un-park so the issue re-derives `stage/010-actionable` ([#13588](https://github.com/hivecommons/hive/issues/13588)); a `needs-spec` a person added is never lifted by the sweep. Or remove `needs-spec` by hand. The marker keeps the gate from asking again | `runs.triage.clarity_gate` (`src/pkg/scheduler/clarity_gate.go`, `src/pkg/classify/clarity.go`, `src/pkg/github/clarity_gate_resume.go`) | | `stage/017-possible-existing` from the prior-art gate | Issues | Scheduler kick assembly (`runs.triage.prior_art`) | With the gate on (default on), an unclaimed feature / RFC / epic issue whose key terms match an existing knowledge bead, setting, merged PR, closed issue, doc or code identifier at `runs.triage.prior_art.threshold` (default 70) gets one `` comment quoting the findings and the `stage/017-possible-existing` label instead of a claim; hive-filed issues get a `` note and are never parked ([#13575](https://github.com/hivecommons/hive/issues/13575)). | Hard suppress | Hive | Before kicks are built | The author or a write+ commenter replies `/hive decision proceed — ` (label lifted, a *Scope vs existing* section appended to the body, re-derives 010) or `/hive decision exists` (closed `not_planned` with `already-exists`); a plain reply lifts the label too. A clanker-filed park with no reply is closed `already-exists` after `runs.triage.prior_art.bot_close_ttl` (default 72h); reopen to continue. A 017 a person added is never lifted by the sweep | `runs.triage.prior_art` (`src/pkg/priorart`, `src/pkg/scheduler/prior_art_gate.go`, `src/pkg/github/prior_art_gate_resume.go`) | @@ -295,7 +295,7 @@ An open issue whose GitHub dependency list names an open blocker is enumerated w #### `blocked` -**Applies to:** Issues. **Kind:** Hard suppress. +**Applies to:** Issues and PRs. **Kind:** Hard suppress. The issue waits on an unmerged PR (or another outside blocker): the review backlog files a finding `blocked` when its evidence file exists only on the reviewed PR (absent on the base branch), and `hive-open-issue comment --blocked-on-pr ` parks an existing one; both write ``. A `blocked` issue is filtered (reason `blocked on owner/repo#N`), derives no stage label, is refused by every automated claim producer (`blocked: owner/repo#N`) including the contributor relay, and never carries `help wanted` ([#13093](https://github.com/hivecommons/hive/issues/13093)). A blocker that is an issue rather than a PR is named by the issue form, ``, in the body or a comment (a contributor's `blocked` verdict comment writes it); the issue is filtered `blocked on issue owner/repo#N`, its `blocked` stays while that issue is open and is never lifted as marker-less (projectbluefin/utah#10 and #855 were lifted, re-triaged and re-verified "still blocked" again and again). A malformed issue marker counts as no marker. @@ -303,6 +303,8 @@ When a blocked filing folds into an already-open twin, the twin's own state gove With the marker (in the body, or in a comment the blocked sweep has read), the band signal reads `blocked on owner/repo#N — lifted when it merges or closes` instead of `the label records no reason`, the activity monitor's pill reads `blocked on #N`, links the PR and carries its cached state (`blocked_on_pr` in `/api/stage-tracker`), and the hive's own removal of the label re-reads the issue live rather than waiting for the next enumeration ([#14952](https://github.com/hivecommons/hive/issues/14952)). With the issue form, the blocker joins `blocked_on` instead and the caption reads `Blocked on issue #N — lifts when it closes` ([#16852](https://github.com/hivecommons/hive/issues/16852)). It is also always skipped by contributor admission and shown in the default waiting band. +**On a pull request: `Depends-on:` holds the merge.** A PR body's `Depends-on: #N` or `Depends-on: owner/repo#N` lines (the same lines the dashboard's critical path reads) say the PR must land after another one, for example a change whose tests need a pull request in another repository. The blocked sweep (every 5 minutes, over the configured repositories) puts `blocked` on an open, non-draft PR whose `Depends-on:` names at least one open pull request, and posts one `` comment per open target (the same marker and writer a relay's blocked verdict uses). Every merge lane refuses a `blocked` PR with `label:blocked`: the self-authored and trusted-bot lane, the trusted-author lane, the contributor lane (whatever `exclude_labels` says), the queued merge-request lane, the merge train, the native merge queue (the App's own entry is withdrawn), the dashboard's merge verdict and its human-merge shortcuts. Like a hold it is a gate, not a stage: the PR's stage is its head's progress and the route carries `blocked on owner/repo#N`; the activity monitor row names the target (`blocked_on_pr`, caption `Blocked on PR #N — lifts when it merges`). A target that is an issue, a closed PR, or a PR the App cannot read places nothing (an unreadable one is logged once). The sweep never places over a person's `blocked`, never lifts one, and never puts its own back after a person removed it, until the body names an open pull request it has not marked yet. It lifts its own `blocked`, with one `` note, once every marked pull request has merged or closed (the note says when one closed without merging) or is no longer listed under `Depends-on:`. Both writes go through the write-back gate (`gate_comment`), and the sweep needs the App bot login to tell its label from a person's. Stacked PRs (a base branch that is another open PR's) are not handled. + **Who applies it:** Hive (reserved for agents; relay only). **Checked by:** Enumeration, stage derivation, claim gate, review backlog, blocked sweep. **When:** Review backlog filing; blocked-on comment relay. @@ -311,7 +313,7 @@ With the marker (in the body, or in a comment the blocked sweep has read), the b The hard-suppress reconcile (#12002) can also lift a Hive-applied `blocked` after a referencing PR merges, but only when the newest label event was by the App bot; human-applied or re-applied labels are not lifted. It posts ``. -**Configuration and implementation.** Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`); contributor/dashboard controls: `hub.contribute_skip_labels`, dashboard bands (`src/pkg/config/hub_config.go:187-193`, `src/docs/dashboard.md:105-140`) +**Configuration and implementation.** Fixed label (`src/pkg/github/issue_blocked.go`, `src/pkg/github/pr_blocked_depends_on.go`, `src/pkg/github/issue_recheck_soak.go`, `src/pkg/github/issue_stage_labels.go`, `src/pkg/github/issue_claim_gate.go`); contributor/dashboard controls: `hub.contribute_skip_labels`, dashboard bands (`src/pkg/config/hub_config.go:187-193`, `src/docs/dashboard.md:105-140`) #### `needs-human` diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index b37cc9b7fb..8348eaf079 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -410,7 +410,7 @@ used to admit the PR: | CI red (required or optional) while **every** failing check on the head is also red on the base branch's tip — the governor's `base_red_checks` / `base_red`, set during CI enrichment when a same-named latest check run on the base ref (meta checks excluded) concluded failure / timed_out / cancelled / action_required / startup_failure / stale **and** the PR's changed files include none of `.github/workflows/*`, `Dockerfile` / `Dockerfile.*` / `*.Dockerfile`, `go.mod` / `go.sum` (a PR touching those plausibly owns the check and stays author-facing; a lookup error or a diff beyond the file-list page budget also stays author-facing) | `050-review-pending` / `060-reviewed`, reason `base-branch-red:,` ("waiting for the base branch's CI to recover (…) — not this PR's fault"): never 070/071/072, never nudged (a 072 nudge already posted for the head is edited in place to say it was withdrawn), never stalled, still not merged (the lane's skip reason is the same token). The fix loop counts no attempt, kicks no fixer, and posts one `` hold comment per head; an escalation the hive itself raised (ledger `label_applied`) over such a head has its `needs-human` removed with the hold wording. The next evaluation after the base goes green re-evaluates the head: a still-red PR is handed back as usual. Conflicts and requested changes stay author-facing (seen on [#13270](https://github.com/hivecommons/hive/pull/13270) and [#13258](https://github.com/hivecommons/hive/pull/13258), 2026-10-20) | | CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:,`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or run or approve it for head `` as the repository requires). A new head on the same fork PR (a merge of the base, or the author's push) keeps the guard while the lane's red check is one of the recorded `fork-guard:` checks, so the PR does not drop to 072 and nobody is nudged before the annotation for that head is read. A fork PR head that nothing has classified yet (its first red head, or a PR that came to 072 for another reason first) is classified from its own check annotations with the same rule, once per head, before it can be nudged: a head red only on fork-guarded checks goes straight to 085 and the guard is recorded for later heads (projectbluefin/utah-packages#972, where the author was nudged and sent relay rework for a fork-gated Canary five minutes before the annotation was read). The hive also does not update the branch of a fork head that waits on a fork-guarded check: the run a maintainer dispatches proves one exact head, and a merge of the base would discard it. Once the check is green the guard drops and updates resume before merge. While the PR stays parked across new heads, the entry comment is rewritten in place for each one, so it always names the current head, and it says that a run which passed on an earlier head does not cover this one even when the patch is the same, because a rebase or a merge of the base changes the code the check runs (projectbluefin/utah-packages#917). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273), projectbluefin/utah-packages#862 and #869) | | any **non-required** check on the current head is red, whatever the lane's reason (the lane gates on required checks only, so it still soaks and merges; a reader of the rollup sees ✗). Parking modifiers (`hold`, `needs-human`, admission reasons) still win | `070-fixing` / `071-needs-author` / `072-returned-to-contributor` (by author kind), reason `optional-check-failing:` (the nudge lists every red check); never 080 or 100. A red *required* check is the lane's own `required-check-failing:*` → 070/071/072 ([#12538](https://github.com/hivecommons/hive/issues/12538), seen on [#12457](https://github.com/hivecommons/hive/pull/12457)) | -| `label:hold`, `held`, `sentinel`, `contributor-lane:sentinel-blocked` | **gate**, not a stage ([#17327](https://github.com/hivecommons/hive/issues/17327)): routed by the head's evidence (below) exactly as a trust cause — CI / 070 while checks run or fail, 071 on a reviewer question, `090-ready-for-human-merge` when the head is otherwise clean — with the gate reason kept on the route so the popover and the entry comment say "Held: …". The lanes refuse the merge on the label, never on the stage | +| `label:hold`, `label:blocked`, `held`, `sentinel`, `contributor-lane:sentinel-blocked` | **gate**, not a stage ([#17327](https://github.com/hivecommons/hive/issues/17327)): routed by the head's evidence (below) exactly as a trust cause — CI / 070 while checks run or fail, 071 on a reviewer question, `090-ready-for-human-merge` when the head is otherwise clean — with the gate reason kept on the route so the popover and the entry comment say "Held: …". The lanes refuse the merge on the label, never on the stage. `label:blocked` is a PR wearing `blocked`: its gate reason reads `blocked on owner/repo#N` when the blocked sweep has read the pull request it waits on | | `label:needs-human`, `exempt-label`, `excluded-label:*`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `review-off` (a verdict is required but the review swarm is off, so none will be requested) / `reporter-trust-hold`, `workflow-permission` (GitHub refused update-branch or the merge-forward with a 403 because the base changed `.github/workflows/` and the token the hive used lacks the workflows permission; no token the hive holds can push that update, so it is not sent to 070), `fork-workflow-update` (the same update-branch refusal on a fork head: the App is not installed on the fork, so no grant lets it push there), `linked-issue:hold:#N: