From 85475ced09c73d8cecdae97cac90941d71bad29d Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Sat, 31 Oct 2026 06:51:28 -0400 Subject: [PATCH 01/10] =?UTF-8?q?=F0=9F=90=9B=20fix:=20explain=20current?= =?UTF-8?q?=20human=20requirements=20on=20covered=20tracker=20rows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- changelog.d/fixed-tracker-human-reason.md | 1 + .../dashboard-sections/activity-monitor.md | 17 +- src/pkg/dashboard/stage_tracker.go | 24 ++- src/pkg/dashboard/stage_tracker_actor.go | 7 +- src/pkg/dashboard/stage_tracker_build.go | 1 + .../stage_tracker_decide_plan_cache_test.go | 2 +- .../stage_tracker_human_attention.go | 77 ++++++++ .../stage_tracker_human_attention.test.js | 178 ++++++++++++++++++ .../stage_tracker_human_attention_test.go | 95 ++++++++++ src/pkg/dashboard/static-src/css/tracker.css | 1 + .../static-src/js/tracker-human-attention.js | 81 ++++++++ .../static-src/js/tracker-row-layout.js | 6 +- .../static-src/js/tracker-row-strip.js | 7 +- src/pkg/dashboard/static-src/manifest.txt | 1 + src/pkg/dashboard/static/index.html | 95 +++++++++- 15 files changed, 569 insertions(+), 24 deletions(-) create mode 100644 changelog.d/fixed-tracker-human-reason.md create mode 100644 src/pkg/dashboard/stage_tracker_human_attention.go create mode 100644 src/pkg/dashboard/stage_tracker_human_attention.test.js create mode 100644 src/pkg/dashboard/stage_tracker_human_attention_test.go create mode 100644 src/pkg/dashboard/static-src/js/tracker-human-attention.js diff --git a/changelog.d/fixed-tracker-human-reason.md b/changelog.d/fixed-tracker-human-reason.md new file mode 100644 index 0000000000..436a284fe9 --- /dev/null +++ b/changelog.d/fixed-tracker-human-reason.md @@ -0,0 +1 @@ +- Explain current human requirements and their actual PR/requester on Activity Monitor rows, distinguish optional delegation and claim ownership, and preserve specific covering-PR reasons without changing stages or linked trees. diff --git a/src/docs/dashboard-sections/activity-monitor.md b/src/docs/dashboard-sections/activity-monitor.md index 74c6931d6c..b954f2242d 100644 --- a/src/docs/dashboard-sections/activity-monitor.md +++ b/src/docs/dashboard-sections/activity-monitor.md @@ -6,10 +6,25 @@ Part of [Dashboard sections explained](../dashboard-sections.md); see that page A progress strip per open issue and pull request showing which step of the pipeline it is on and who must act next. +Human requirements have visible **Needs human: …** text inside the corresponding +row, with the actual PR number, requester and next mover when known. This is +separate from its pipeline stage: a covered issue can still read **PR in +progress** while a specific linked PR asks a person to act. Multiple-PR trees +identify the asking PR rather than placing its siblings on hold; a PR drawn +under another issue names that host. A missing reason explicitly says **Human +decision required; reason unavailable** and links to the item. + +The person glyph is reserved for an exact-current requirement. Claim ownership +and ordinary author work instead have explicit **Claimed by** / **Next move** +context; **Let hive decide** can be an optional delegation action, not a status +indicator. These lines do not change stages, sorting, reference-versus-closing +links, preparation train styling, native queues, or live notes' tuck/reopen +controls. Cleared decisions and mismatching PR heads lose the requirement. + ### First use: find the next action 1. Find an item by repository, number or title. Every open issue and PR in the watched repositories is represented, including held, draft, filtered, exempt and reporter-triage work. Being visible does not make it actionable. -2. Read the lit step and its words, then the reason on the item's `#N` link or lit chevron. The word says where the work is; the actor icon says whose move it is. +2. Read the lit step and the visible human/actor context beneath it. The word says where the work is; **Needs human** names the actual requirement, while **Next move** and **Claimed by** distinguish ordinary actor/claim ownership. Links and chevrons retain further detail. 3. Use **πŸ™‹ Needs human** for work waiting on a person's action. Use **⏸ On hold** separately for work a maintainer deliberately paused. Neither filter grants permission to act. 4. Open **β‹―** (or right-click / Shift+F10) for the actions allowed in that state. Read the confirmation and the result toast; a queued decision is not proof the PR merged. diff --git a/src/pkg/dashboard/stage_tracker.go b/src/pkg/dashboard/stage_tracker.go index 81b9c888f5..42c59024bc 100644 --- a/src/pkg/dashboard/stage_tracker.go +++ b/src/pkg/dashboard/stage_tracker.go @@ -361,6 +361,9 @@ type StageTrackerItem struct { // stalled, a handled regression, blocked-on-pr, 040 covered or a PR // ready for auto-merge β€” the hive advances those (hivecommons/hive#15008). NeedsHuman bool `json:"needs_human,omitempty"` + // HumanAttention is the current item's actionable human requirement, + // separate from an actor/claimant icon or optional delegation action. + HumanAttention *StageTrackerHumanAttention `json:"human_attention,omitempty"` // OnHold is true when the item wears a hold pill: paused on purpose, // waiting on nobody. OnHold bool `json:"on_hold,omitempty"` @@ -666,16 +669,17 @@ type StageTrackerLinkedIssue struct { // StageTrackerLinkedPR is one covering PR nested under an issue row. type StageTrackerLinkedPR struct { - Preparation *StageTrackerPreparation `json:"preparation,omitempty"` - BaseRef string `json:"base_ref,omitempty"` - Number int `json:"number"` - Title string `json:"title,omitempty"` - URL string `json:"url,omitempty"` - Author string `json:"author,omitempty"` - AuthorKind string `json:"author_kind,omitempty"` - Stage int `json:"stage,omitempty"` - StageSince *time.Time `json:"stage_since,omitempty"` - Caption string `json:"caption,omitempty"` + HumanAttention *StageTrackerHumanAttention `json:"human_attention,omitempty"` + Preparation *StageTrackerPreparation `json:"preparation,omitempty"` + BaseRef string `json:"base_ref,omitempty"` + Number int `json:"number"` + Title string `json:"title,omitempty"` + URL string `json:"url,omitempty"` + Author string `json:"author,omitempty"` + AuthorKind string `json:"author_kind,omitempty"` + Stage int `json:"stage,omitempty"` + StageSince *time.Time `json:"stage_since,omitempty"` + Caption string `json:"caption,omitempty"` // NoteChangedAt mirrors the PR row's: when the caption last changed // meaning. NoteChangedAt *time.Time `json:"note_changed_at,omitempty"` diff --git a/src/pkg/dashboard/stage_tracker_actor.go b/src/pkg/dashboard/stage_tracker_actor.go index 0cd1237a96..a016e09e77 100644 --- a/src/pkg/dashboard/stage_tracker_actor.go +++ b/src/pkg/dashboard/stage_tracker_actor.go @@ -459,10 +459,13 @@ func stageTrackerResolveActors(items []StageTrackerItem) { cp := *lead.StageActor // The issue's chevron names the PR the person is wanted on. if cp.Kind == StageActorHuman { - ask := "needs a person" - if pr := prs[it.Repo+"#"+strconv.Itoa(lead.Number)]; pr != nil { + ask := cp.HumanReason + if pr := prs[it.Repo+"#"+strconv.Itoa(lead.Number)]; ask == "" && pr != nil { ask = stageTrackerHumanAsk(stageByNumber(pr.Stage)) } + if ask == "" { + ask = "needs a person" + } cp.HumanReason = stageTrackerClipReason("#" + strconv.Itoa(lead.Number) + " " + ask) } it.StageActor = &cp diff --git a/src/pkg/dashboard/stage_tracker_build.go b/src/pkg/dashboard/stage_tracker_build.go index b1a71f8d06..fd106c4a6e 100644 --- a/src/pkg/dashboard/stage_tracker_build.go +++ b/src/pkg/dashboard/stage_tracker_build.go @@ -514,6 +514,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto stageTrackerResolveLinkedPRs(resp.Items, prOpen) stageTrackerMarkClosedBy(resp.Items, s.mergedLedger().ClosedBy) stageTrackerResolveActors(resp.Items) + stageTrackerResolveHumanAttention(resp.Items) sort.SliceStable(resp.Items, stageTrackerLess(resp.Items)) return resp } diff --git a/src/pkg/dashboard/stage_tracker_decide_plan_cache_test.go b/src/pkg/dashboard/stage_tracker_decide_plan_cache_test.go index 97ed6dfc55..aedc2a075a 100644 --- a/src/pkg/dashboard/stage_tracker_decide_plan_cache_test.go +++ b/src/pkg/dashboard/stage_tracker_decide_plan_cache_test.go @@ -179,7 +179,7 @@ func TestStageTrackerNoHumanMarkerWithoutReason(t *testing.T) { issue.StageActor = &StageTrackerActor{Kind: StageActorHive, Why: "an agent has a PR under way; not yet opened"} items := []StageTrackerItem{pr, issue} stageTrackerResolveActors(items) - if a := items[1].StageActor; a.Kind != StageActorHuman || a.HumanReason != "#15759 needs a decision" || a.Why != pr.StageActor.Why { + if a := items[1].StageActor; a.Kind != StageActorHuman || a.HumanReason != stageTrackerClipReason("#15759 "+pr.StageActor.HumanReason) || a.Why != pr.StageActor.Why { t.Errorf("riding issue actor = %+v", a) } check("riding issue", items[1].StageActor) diff --git a/src/pkg/dashboard/stage_tracker_human_attention.go b/src/pkg/dashboard/stage_tracker_human_attention.go new file mode 100644 index 0000000000..018e585712 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_human_attention.go @@ -0,0 +1,77 @@ +package dashboard + +import ( + "slices" + "strconv" + "strings" + + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// StageTrackerHumanAttention is a finished-snapshot requirement on this exact +// item, not an available decision action or the kind of its claim holder. +type StageTrackerHumanAttention struct { + Number int `json:"number"` + Kind string `json:"kind"` + Head string `json:"head,omitempty"` + Reason string `json:"reason"` + AskedBy string `json:"asked_by,omitempty"` + Owner string `json:"owner,omitempty"` +} + +func stageTrackerHumanAttention(it StageTrackerItem) *StageTrackerHumanAttention { + if !stageTrackerNeedsHuman(it) || it.Stage >= stagelabels.MergeQueue.Number() || + slices.Contains(it.Modifiers, modDraft) || slices.Contains(it.Modifiers, "merged") { + return nil + } + // Mirrored issues carry their PR's observation on the link, never an + // issue-wide requirement inherited from a parent RFC or a sibling PR. + if it.Kind == "issue" && it.Mirrored { + return nil + } + a := &StageTrackerHumanAttention{Number: it.Number, Kind: it.Kind, Head: it.Head} + if d := it.DecisionNeeded; d != nil { + a.Reason = strings.TrimSpace(nonEmpty(d.Question, d.Blocker)) + a.AskedBy = strings.TrimSpace(d.AskedBy) + } + if a.Reason == "" { + a.Reason = strings.TrimSpace(it.HumanMergeReasonText) + } + if actor := it.StageActor; actor != nil && actor.Kind == StageActorHuman { + a.Owner = actor.Login + if a.Reason == "" { + a.Reason = strings.TrimSpace(actor.Why) + } + } + if a.Reason == "" { + a.Reason = "Human decision required; reason unavailable" + } + return a +} + +// Resolve only after operator/decision projections, current PR link hydration +// and actor resolution, so cleared decisions and new heads cannot retain a +// previous link's requirement. No traversal of issue/RFC ancestry is involved. +func stageTrackerResolveHumanAttention(items []StageTrackerItem) { + prs := map[string]*StageTrackerItem{} + for i := range items { + it := &items[i] + it.HumanAttention = stageTrackerHumanAttention(*it) + if it.Kind == "pr" { + prs[it.Repo+"#"+strconv.Itoa(it.Number)] = it + } + } + for i := range items { + it := &items[i] + for j := range it.LinkedPRs { + lp := &it.LinkedPRs[j] + lp.HumanAttention = nil + pr := prs[it.Repo+"#"+strconv.Itoa(lp.Number)] + if pr == nil || pr.Head != lp.Head || lp.State == "closed" || + lp.SupersededBy > 0 || lp.AdoptedBy > 0 { + continue + } + lp.HumanAttention = pr.HumanAttention + } + } +} diff --git a/src/pkg/dashboard/stage_tracker_human_attention.test.js b/src/pkg/dashboard/stage_tracker_human_attention.test.js new file mode 100644 index 0000000000..77bdadeb67 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_human_attention.test.js @@ -0,0 +1,178 @@ +// CI-only behavioral tests of the shipped human context and actual row adapters. +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const vm = require('node:vm'); +const source = name => fs.readFileSync(path.join(__dirname, 'static-src/js', name + '.js'), 'utf8'); +const fn = (file, name) => { + const text = source(file); + const match = text.match(new RegExp('function ' + name + '\\([^\\n]*\\) \\{[^\\n]*\\}\\s*(?:\\n|$)')) + || text.match(new RegExp('function ' + name + '\\([^\\n]*\\) \\{[\\s\\S]*?\\n \\}')); + assert.ok(match, name); + return match[0]; +}; +const esc = value => String(value).replace(/[&<>"']/g, ch => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[ch])); +const plain = value => JSON.parse(JSON.stringify(value)); +function load() { + const c = vm.createContext({ Date, esc, + STAGE_TRACKER_TERMINAL: 100, STAGE_TRACKER_PR_COLUMN: 40, + STAGE_TRACKER_LINKED_GLYPH: '↳', STAGE_TRACKER_SOFT_LINK_TIP: 'refs', + stageTrackerAnchor: n => Number(n) || 0, + stageTrackerAttentionTier: () => 1, + stageTrackerLeadStage: lp => lp.stage || 40, + stageTrackerIcon: (kind, cls) => ``, + stageTrackerPRRef: (n, url, kind, author, title) => `#${n} ${esc(title || '')}`, + stageTrackerPRPillsHtml: ref => ref, + stageTrackerTitleHtml: text => `${esc(text)}`, + stageTrackerTooltip: it => it.caption || '', + stageTrackerLinkedTip: () => '', + stageTrackerActedBadgeHtml: () => '', stageTrackerRowToolsHtml: () => '', + stageTrackerChipsHtml: () => '', stageTrackerMoveAttrs: () => '', stageTrackerSinceHtml: () => '', + stageTrackerStripItems: it => `
  • `, + stageTrackerCurrentStageHtml: it => `${it.stage}`, + stageTrackerEventHtml: (key, ctx) => `

    ${esc(ctx && ctx.note || 'live note')}

    `, + stageTrackerActionCtx: () => ({ user: 'viewer' }), + stageTrackerLeadActionOnRow: item => item.optionalAction ? { id: 'decide:delegate', label: 'Let hive decide' } : null, + }); + for (const name of ['stageTrackerLinkedSuperseder', 'stageTrackerLinkedSupersededGone', 'stageTrackerLinkedSupersededText', 'stageTrackerLinkedSupersededTip']) vm.runInContext(fn('tracker-words-gate', name), c); + for (const name of ['stageTrackerItemKey', 'stageTrackerPRKey', 'stageTrackerRowPRKeys']) vm.runInContext(fn('tracker-merged', name), c); + for (const name of ['stageTrackerLinkedPRItem', 'stageTrackerLinkedPROpen', 'stageTrackerLinkedDrawnHere', 'stageTrackerLinkedSorted', 'stageTrackerHeadColsHtml', 'stageTrackerRowHtml', 'stageTrackerSubRowHtml']) vm.runInContext(fn('tracker-row-layout', name), c); + vm.runInContext(fn('tracker-filter', 'stageTrackerPRIssueSlot'), c); + vm.runInContext(source('tracker-human-attention'), c); + return c; +} +function pr(number = 15985) { + return { kind: 'pr', repo: 'hivecommons/hive', number, stage: 85, state: 'open', head: 'current-' + number, + title: 'PR ' + number, url: 'https://github.com/hivecommons/hive/pull/' + number, base_ref: 'v5', + human_attention: { kind: 'pr', number, head: 'current-' + number, reason: 'Confirm the compatibility policy', + asked_by: 'a reviewer', owner: 'maintainer' }, + stage_actor: { kind: 'human', login: 'maintainer', why: 'Confirm the compatibility policy' } }; +} +function issue(linked) { + return { kind: 'issue', repo: 'hivecommons/hive', number: 15937, stage: 40, linked_pr: linked[0].number, + title: 'Matrix overlay', linked_prs: linked, url: 'https://github.com/hivecommons/hive/issues/15937', + stage_actor: linked[0].stage_actor }; +} + +test('covered issue shows the exact PR requirement/requester in visible prose without overriding its actual stage', () => { + const c = load(), child = pr(), item = issue([child]), before = plain(item); + const html = c.stageTrackerRowHtml(item, [], { nowMs: 1, note: 'review comment' }); + assert.match(html, /data-ham-kind="issue".*data-ham-stage="40"/); + assert.match(html, /data-stage="85"/); + assert.match(html, /PR #15985 β€” Needs human: Confirm the compatibility policy Β· next move: @maintainer Β· requested by a reviewer/); + assert.match(html, />View PR #15985<\/a>/); + assert.match(html, /cue-event-tuckable.*data-cue-key=.*review comment.*Reopen/); + assert.doesNotMatch(html, /Needs you|ham-preparation-head|
    { + const c = load(), child = { ...pr(), drawn_under: 15862 }, item = issue([child]); + const html = c.stageTrackerRowHtml(item, [], { nowMs: 1 }); + assert.match(html, /PR #15985 β€” Needs human:.*shown under issue #15862/); + assert.doesNotMatch(html, /data-ham-sub-key=/); + assert.equal(item.stage, 40); + assert.equal(item.human_attention, undefined); +}); + +test('mixed multiple PR trees render only the asking child and preserve child order/stages', () => { + const c = load(), asking = pr(), ordinary = { ...pr(15998), stage: 50, human_attention: null, stage_actor: { kind: 'hive', why: 'CI pending' } }; + const item = issue([ordinary, asking]), before = plain(item); + const html = c.stageTrackerRowHtml(item, [], { nowMs: 1 }); + assert.equal((html.match(/Needs human:/g) || []).length, 1); + assert.match(html, /data-ham-stage="85" data-ham-sub-key="hivecommons\/hive\/pr#15985"/); + assert.match(html, /data-ham-stage="50" data-ham-sub-key="hivecommons\/hive\/pr#15998"/); + assert.ok(html.indexOf('data-ham-sub-key="hivecommons/hive/pr#15985"') < html.indexOf('Needs human:')); + assert.ok(html.indexOf('Needs human:') < html.indexOf('data-ham-sub-key="hivecommons/hive/pr#15998"')); + assert.deepEqual(plain(item), before); +}); + +test('optional Let hive decide is explicitly an optional action, never evidence of a human gate', () => { + const c = load(), item = { ...pr(), human_attention: null, optionalAction: true, stage: 50, stage_actor: { kind: 'hive' } }; + const html = c.stageTrackerHumanContextHtml(item, [], 1); + assert.match(html, /Optional delegation: Let hive decide is available/); + assert.doesNotMatch(html, /Needs human:|Needs you/); +}); + +test('claim owner and human next mover are explained separately from a required decision', () => { + const c = load(), item = { ...pr(), human_attention: null, stage: 40, stage_actor: { kind: 'none' }, claimant: { kind: 'person', login: 'author' } }; + assert.match(c.stageTrackerHumanContextHtml(item, [], 1), /Claimed by @author Β· claim ownership, not a human decision request/); + item.stage_actor = { kind: 'human', login: 'author', why: '@author must push a fix; the hive does not edit a person’s PR' }; + const html = c.stageTrackerHumanContextHtml(item, [], 1); + assert.match(html, /Next move: @author β€” @author must push a fix/); + assert.doesNotMatch(html, /Needs human:|Needs you/); +}); + +test('changed head/identity, closed/draft/held/superseded and answered observations cannot retain a requirement', () => { + for (const mutate of [ + it => { it.head = 'new-head'; }, it => { it.number++; }, it => { it.kind = 'issue'; }, + it => { it.state = 'closed'; }, it => { it.modifiers = ['draft']; }, it => { it.modifiers = ['hold']; }, + it => { it.hold = { by: 'owner' }; }, it => { it.superseded_by = 16000; }, + it => { it.human_attention = null; it.stage_actor = { kind: 'hive' }; }, + ]) { + const c = load(), item = pr(); mutate(item); + assert.equal(c.stageTrackerHumanAttentionOf(item), null); + assert.doesNotMatch(c.stageTrackerHumanContextHtml(item, [], 1), /Needs human:/); + } +}); + +test('unknown reason is explicit with a detail route; data is escaped and no owner is invented', () => { + const c = load(), item = pr(); + item.human_attention.reason = ''; delete item.human_attention.owner; delete item.human_attention.asked_by; + let html = c.stageTrackerHumanContextHtml(item, [], 1); + assert.match(html, /Needs human: Human decision required; reason unavailable/); + assert.match(html, />View PR #15985/); + assert.doesNotMatch(html, /next move: @|requested by|Needs you/); + item.human_attention.reason = ''; + html = c.stageTrackerHumanContextHtml(item, [], 1); + assert.match(html, /<script>/); + assert.doesNotMatch(html, /