Skip to content

✨ feat(dashboard): Let hive decide shows what hive saw and why each option was ruled out - #16936

Merged
hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:feat/delegate-plan-what-hive-saw
Nov 6, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:feat/delegate-plan-what-hive-saw

Conversation

@Danathar

@Danathar Danathar commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Summary

The Let hive decide preview tells the owner what the hive would do and gives one short reason. It does not show what that decision rests on, so an owner has to take the reason on trust. This PR adds What hive saw under the dialog's Details: every fact the decision rules read, each marked as fine, holding the item back, or steering the decision. Details also gets the rule that decided, with its whole reason, and each ruled-out option with the fact that ruled it out. The visible part of the dialog is unchanged.

What went wrong

An owner asked for "more information in that pop up dialog, specifically why hive would do what it wants to do". For an adopt decision the dialog said only:

Why Their clanker is offline.

Details then listed the ladder's raw lines (mergeable-as-is: adoption stalled on a lane blocker). It never said whether CI was green, whether the head conflicts, who the author is, what the review said, or which rule decided. The decision is made by fixed rules over about twenty facts (delegatedecision.Input), and the preview threw all of them away after deciding.

What changes

The plan response (POST …/decide-delegated/plan) gains four fields:

Field What it holds
saw [{label, value, state}], every fact the rules read, in the order an owner checks them: author, contributor reachability, CI, conflicts, sign-off, review, Sentinel, then size, workflow files, already-landed, duplicates and competing PRs, adoption state, reporter trust, a paused repo, and the reviewer's question. state is ok, blocks or info. Facts that do not apply to the item's kind are left out, so an issue gets no CI line.
rule_plain The deciding rule in plain words (from the glossary).
rationale The rule's whole reason, with issue references removed. It is left out when it only repeats why. When no mechanical rule applies (llm-delegate), this is the model's own reason.
why_not [{option, because}], the ladder's ruled-out rungs as the options an owner would have picked by hand: Approve as it is: conflicting, CI not green.

The dialog, under Details only:

  1. the Sentinel finding, as before;
  2. What hive saw: one fact per line, marked ✓, ✗ or •. A screen reader hears "(fine)" or "(holds it back)" instead of the mark;
  3. Rule, then its reason;
  4. Why not the others, now as options with their reasons. A plan without why_not, from an older server, still shows the raw lines;
  5. the rails, as before.

A batch labels each item's facts with its reference. The three-second visible budget (title, one sentence, one why, two "then" items) is untouched, and a test pins that the visible text is identical with and without the new fields.

Why not more

A chat panel inside the dialog for asking about the PR was discussed as a next step. It needs a design decision first, because the panel would read untrusted PR text right next to buttons that merge. This PR is the deterministic part: it shows exactly what the rules saw, with nothing generated.

Files

  • src/pkg/delegatedecision/facts.go (new): Input.Facts(), Ladder.WhyNot().
  • src/pkg/dashboard/api_repo_item_decide_delegated_plan.go: the four fields, filled in planDelegatedDecision.
  • src/pkg/dashboard/api_repo_item_decide_delegated_plan_rule.go (new): delegatedPlanRule.
  • src/pkg/dashboard/static-src/js/tracker-actions.js, static-src/css/tracker.css, regenerated static/index.html.
  • src/docs/dashboard-sections/activity-monitor.md, src/docs/api-reference/packs-and-acmm.md.
  • changelog.d/added-delegate-plan-what-hive-saw.md

Tests

  • pkg/delegatedecision/facts_test.go:
    • a green PR lists no blocker;
    • a blocked PR names every blocker with its words;
    • pending CI is not a blocker;
    • an issue lists no head facts;
    • hive-authored and person-authored PRs have no reachability line;
    • WhyNot maps rungs to options, including an unknown rung and a nil ladder.
  • TestDelegatedDecisionPlanShowsWhatHiveSaw: through the real plan route, the plan carries saw with the offline fact the adopt decision rests on, rule_plain, rationale without issue references, and a why_not entry for Approve as it is.
  • TestDelegatedPlanRuleDropsARationaleTheWhyAlreadySays
  • TestStageTrackerDelegatePlanDetailsShowWhatHiveSaw runs the dialog code under node. It checks:
    • the visible text is identical with and without the new fields;
    • the facts sit under Details with their marks and screen-reader words;
    • an unknown state renders as info;
    • a fact value containing markup is escaped;
    • the order is what hive saw, then why not the others, then rails;
    • an older plan keeps its raw lines;
    • a batch labels each item.

Without the change, both route and dialog tests fail. The route test shows What hive saw has no "CI" line: [], rule_plain = "", why_not = []. The dialog test shows Details with only the raw ruled-out lines. With the change they pass.

The whole ./pkg/dashboard/ package (146 s), ./pkg/delegatedecision/ and ./pkg/dashboard/webstatic/... pass. go vet is clean, the generated index.html passes its -check, and the docs, link, API-reference and changelog checks pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

The preview gave one "Why" line and the ladder's raw "rung: reason"
lines, so an owner could not check a decision against what it rested on.

The plan now carries saw (every fact the decision rules read, each marked
ok / blocks / info), rule_plain and rationale (the deciding rule in plain
words and its whole reason), and why_not (each ruled-out ladder option with
the fact that ruled it out). The dialog lists them under Details as "What
hive saw", the rule, and "Why not the others"; the visible part keeps its
budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 6, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

Details Needs approval from an approver in each of these files:

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

@kubestellar-prow kubestellar-prow Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v6

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

PR Title Relation Files
#16935 🐛 [v6] delegate: name the option or leave the choice on an issue with competing options same files src/docs/dashboard-sections/activity-monitor.md
src/pkg/dashboard/api_repo_item_decide_delegated_plan.go
src/pkg/dashboard/static/index.html
#16688 🌱 Forward-merge v5 into v6 (2 commits) same files src/pkg/dashboard/static/index.html

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Style/maintainability review at head d29db48.

1. Facts() reads in.Small, but the rule it mirrors reads in.IsSmall() — src/pkg/delegatedecision/facts.go:113 vs policy.go:452,791. IsSmall() also honours the size/XS/size/S labels, so a labelled-small PR is approved under small-low-risk while What hive saw shows no Change: small… line — the list no longer matches "every fact the rules read" (PR body / activity-monitor.md).

		if in.IsSmall() {

2. rungOptions is a second operator-facing text table outside the glossary — facts.go:199-205. decision_glossary.go:9-16 declares the glossary "the ONE source for operator-facing text", and TestGlossaryCoversEveryRuleSlug guards it; nothing guards rungOptions, so a future ladder rung silently falls back to Plain(rung) (facts.go:218), which is rule-phrasing ("the author hasn't been reachable…") rather than an option. Suggest an Option string field on GlossaryEntry for the five ladder rungs (read via Explain(rung)), or at least a test asserting every slug decideLadder can put in RuledOut has a rungOptions entry. Related: the fact values re-word mergeBlockers (ladder.go:287-316) — Details now shows "DCO sign-off missing" under What hive saw and "DCO missing" under Why not the others for the same fact; reusing one wording would keep the two lists in step.

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

@hivecommons-hive

hivecommons-hive Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from adjudicator-3 (folded here because this head already carries its hive review):

Intent alignment (head d29db48) — the diff does what the title and body say: saw/rule_plain/rationale/why_not are filled in planDelegatedDecision (src/pkg/dashboard/api_repo_item_decide_delegated_plan.go:241,285-286), rendered under Details only (static-src/js/tracker-actions.js:1703-1718), with the older-server fallback to ladder.ruled_out (:1667-1669). Two advisory gaps in the "every fact the decision rules read" claim, neither blocking:

  1. Two rule inputs have no fact line. Input.Facts() (src/pkg/delegatedecision/facts.go:33-190) never emits HiveSuperseding / HiveSupersederHardStop, which decideHiveSuperseder decides on (policy.go:883-886), nor BlockedOnPRClosed (policy.go:571). For a hive superseding PR parked on a hard stop, "What hive saw" shows only Author: the hive and the stop appears solely in the rationale. Suggested addition after the Already landed block (facts.go:143):

    +		if in.HiveSuperseding {
    +			if stop := strings.TrimSpace(in.HiveSupersederHardStop); stop != "" {
    +				add("Supersedes another PR", "the hive's own superseding copy, stopped: "+stop, FactBlocks)
    +			} else {
    +				add("Supersedes another PR", "the hive's own superseding copy; auto-merges once clean", FactInfo)
    +			}
    +		}

    and, for issues, if in.BlockedOnPRClosed { add("Linked PR", "closed unmerged", FactInfo) }.

  2. Review finding is marked ✗ even when the rules ignore it. facts.go:97-103 adds ReviewerFinding as FactBlocks whenever non-empty, but the policy only acts on it under ReviewerRequiresHuman (policy.go:820-831), and the dashboard sets ReviewerFinding from agg.DecisionFinding regardless of that flag (api_repo_item_decide_delegated.go:949-955). Suggest:

    		if f := strings.TrimSpace(in.ReviewerFinding); f != "" {
    			state := FactInfo
    			if in.ReviewerRequiresHuman {
    				state = FactBlocks
    			}
    			if in.SecurityFinding {
    				f += " (security review)"
    			}
    			add("Review finding", f, state)
    		}
    

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review at head d29db48.

Review fact marks a reject / incomplete swarm verdict as ✓ fine — src/pkg/delegatedecision/facts.go:88-89

The Review switch treats any non-empty HeadReviewVerdict that is not changes_requested/requires_human as FactOK. HeadReviewVerdict is copied verbatim from the swarm aggregate (src/pkg/dashboard/api_repo_item_decide_delegated.go:934-937), and review.Verdict also has reject and incomplete (src/pkg/review/review.go:55,62). On such a head the dialog renders "✓ Review the hive's review on this head: reject (fine)" — the mark that this PR exists to make trustworthy says the opposite of the verdict. The ladder itself ignores these verdicts (ladder.go:179), so this is a presentation defect, not a decision one, but it's the new output. None of TestFacts* covers a verdict other than changes_requested/requires_human.

		case strings.EqualFold(strings.TrimSpace(in.HeadReviewVerdict), "approve"):
			add("Review", "the hive's review on this head: approve", FactOK)
		case strings.EqualFold(strings.TrimSpace(in.HeadReviewVerdict), "reject"):
			add("Review", "the hive's review on this head: reject", FactBlocks)
		case strings.TrimSpace(in.HeadReviewVerdict) != "":
			add("Review", "the hive's review on this head: "+strings.ReplaceAll(strings.TrimSpace(in.HeadReviewVerdict), "_", " "), FactInfo)

Everything else checked out: WhyNot nil-safety, the early-return paths in planDelegatedDecision (Saw is set at construction so the workflows-handoff plan still carries it), the JS state normalisation and escaping, and the rationale-dedupe against Why.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Read Facts() and WhyNot() against the ladder rules in the v6 tree; the change looks correct to me.

  • Each FactBlocks label corresponds to a condition the ladder actually gates on: ladder.go:184 (CI, conflicts, DCO, reporter-trust, adoption-stalled, change requests, needs-person), :204 (workflow path, DCO+online). WorkflowsPushable splitting Workflow files into info/blocks matches policy.go:493. Review lets ChangeRequest() (policy.go:350-358) win before HeadReviewVerdict is shown as OK, so a changes_requested head is never marked ✓.
  • Rendering is safe: every value goes through esc() and state is whitelisted to ok|blocks|info before being used in data-state (tracker-actions.js:1661, :1712).
  • The plan is additive (omitempty on all four fields, api_repo_item_decide_delegated_plan.go:77-80), and the JS keeps the ladder.ruled_out fallback when why_not is absent.
  • static/index.html carries the built copy of the static-src changes, and both docs that list the plan shape were updated.

Not a code finding: two checks on this head show CANCELLED (Sign-off survives the squash, native-queue-policy), which looks like superseded runs rather than failures; a re-run should clear them.

Reviewed by reviewer — no findings.

Reviewer notes

Read the diff against the v6 tree at merge-base and the helpers it leans on; this looks correct to me.

What I verified:

  • src/pkg/delegatedecision/facts.go only reads fields and helpers that already exist with the meaning it assumes: PersonAuthored() (policy.go:1000), AuthorWord()/OfflineWording() (ladder.go:78, :91), ChangeRequest()/HeadNeedsPerson() (policy.go:350, :362), SupersededText (ladder.go:133). The CI tri-state matches CIRed() at policy.go:339 (pending is neither green nor red), and ReviewerFinding is only populated alongside ReviewerRequiresHuman (policy.go:310-317, used at :820), so marking it blocks is consistent with how the policy treats it.
  • Ladder.WhyNot() splits on ": ", which is exactly how decideLadder builds RuledOut (ladder.go:161, rung+": "+why); unknown rungs fall back to Plain() which humanises rather than leaking a bare slug (decision_glossary.go:325). Nil receiver is handled, so d.Ladder.WhyNot() on a non-ladder decision is safe.
  • tracker-actions.js: every fact label/value, rule, rationale and why_not line goes through esc(), and state is normalised to ok|blocks|info before being written into data-state, so server-supplied text (author login, reviewer finding, Sentinel reason, question) cannot inject markup. The why_not → ladder.ruled_out fallback keeps older servers rendering.
  • go build ./pkg/delegatedecision/ ./pkg/dashboard/ is clean at eb8377d; static/index.html is regenerated (contains the new ham-plan-saw classes), and docs/api-reference/packs-and-acmm.md documents the four new fields.

No findings. Body matches the diff: the visible dialog text is untouched and all additions sit under Details.

Evidence bundle `#16936eb8377d` sha256:1617e81cc84ac661819205cf3476a5e9c78cef204eda3c3b17aab2e2c073cdf9 — download from the dashboard or `hivectl review evidence #16936`.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Read the diff against the v6 merge-base (19f1b75) and the code it hooks into; this looks correct to me.

What I checked:

  • Ladder.WhyNot() (src/pkg/delegatedecision/facts.go:212) splits on ": ", which is exactly the format decideLadder's skip writes (ladder.go:161: rung+": "+why). Unknown rungs fall back to Plain(rung), and the nil-ladder case is handled before plan.WhyNot = d.Ladder.WhyNot() is reached for non-ladder decisions.
  • Facts() mirrors the rules rather than inventing new ones: CI pending is info, not blocks, matching mergeBlockers (ladder.go:294) and CIRed() (policy.go:339); the Review line uses the same ChangeRequest()/HeadNeedsPerson() the mergeable-as-is rung checks at ladder.go:184.
  • Client side (tracker-actions.js): state is normalised to ok|blocks|info before indexing marks, so a bad value from the server can't produce marks[undefined]; label, value, rule and rationale all go through esc(); why_not falls back to ladder.ruled_out for an older server.
  • All four new plan fields are omitempty additions; nothing existing is renamed, and go build ./pkg/delegatedecision/ ./pkg/dashboard/ is clean at eb8377d.

Not verified here: I could not run the suite in this environment, so I am relying on CI for TestDelegatedDecisionPlanShowsWhatHiveSaw and the node dialog test (server-tests is green; dashboard shards were still running when I looked).

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

@hivecommons-hive
hivecommons-hive Bot merged commit 15fa166 into hivecommons:v6 Nov 6, 2026
70 of 71 checks passed
@hivecommons-hive

Copy link
Copy Markdown
Contributor

merged by Hive trusted-author auto-merge: author @Danathar holds role owner and GitHub permission maintain on repo; CI green at eb8377d.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant