From d32767a96ac52115a594f5b777c14b2c9038621f Mon Sep 17 00:00:00 2001 From: Douglas Baggett Date: Sun, 8 Nov 2026 20:49:40 -0500 Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=90=9B=20[v6]=20knowledge=20priming:?= =?UTF-8?q?=20search=20on=20the=20task,=20rank=20its=20repo=20first?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "# Relevant Knowledge" query was an issue's labels plus title words, and on hive-routed work those were mostly the hive's own routing: stage/010-actionable, agent/reviewer, approved-direction and the "[reviewer] Review backlog (style):" stem. They match review and scanning notes in every repo, so utah-packages#879 was primed with other repos' entries. extractKeywords now drops the hive's routing label families and the filer tag, and cuts a review backlog title to its perspective and finding. The kick context carries the issues' repositories, and the primer adds 0.1 to the rerank score of entries tagged repo:/ for them. The tag orders what the search found; it admits nothing. Label-scoped entries still see every label. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Douglas Baggett --- changelog.d/fixed-knowledge-priming-query.md | 1 + src/docs/agent-knowledge-and-memory.md | 7 +- src/pkg/knowledge/primer.go | 34 +++++- src/pkg/knowledge/scope.go | 13 ++- src/pkg/scheduler/kick_priming.go | 89 +++++++++++++--- src/pkg/scheduler/kick_priming_query_test.go | 103 +++++++++++++++++++ 6 files changed, 227 insertions(+), 20 deletions(-) create mode 100644 changelog.d/fixed-knowledge-priming-query.md create mode 100644 src/pkg/scheduler/kick_priming_query_test.go diff --git a/changelog.d/fixed-knowledge-priming-query.md b/changelog.d/fixed-knowledge-priming-query.md new file mode 100644 index 0000000000..f5b9842e9d --- /dev/null +++ b/changelog.d/fixed-knowledge-priming-query.md @@ -0,0 +1 @@ +- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels and title words, and on hive-routed work those were mostly the hive's own: `stage/010-actionable`, `agent/reviewer`, `approved-direction`, and the `[reviewer] Review backlog (style):` title stem. Those words match review and scanning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos. The query now leaves out the hive's routing label families (`stage/`, `agent/`, `hive/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge/`, `needs-`, `dco-signoff`, `sentinel-`, plus `approved-direction`, `hive-review`, `lgtm` and `approved`) and the filer tag, and cuts a review backlog title down to its perspective (`style`, `security`) and finding. The task's repository now counts too: an entry tagged `repo:/` for the repo being worked on ranks ahead of an otherwise equal entry about another repo. The tag only orders entries the search already found; it never adds one on its own. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index 3f6392b28d..db4244fd0a 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -28,12 +28,15 @@ memory. ▼ ┌───────────────── Scheduler.primeKnowledge (pkg/scheduler/kick_priming.go) ───┐ │ 1. extractKeywords ← titles + labels of the agent's first │ - │ maxIssuesToPrime (=5) queued issues │ + │ maxIssuesToPrime (=5) queued issues, minus hive routing │ + │ labels (stage/, agent/, hive/, needs-, …) and the [agent] / │ + │ "Review backlog ():" title stem │ │ 2. scope ← knowledge.agent_scopes[] (or base agent for a replica) │ │ 3. Primer.PrimeScoped (pkg/knowledge/primer.go) │ │ search every layer/store → merge by layer precedence → │ │ FilterByLifecycle (approved only) → scope.Filter → │ - │ Fisher-Rao rerank → type priority → cap at max_facts (25) → │ + │ Fisher-Rao rerank → +0.1 for entries tagged repo: → │ + │ type priority → cap at max_facts (25) → │ │ expandWithGraph (never past the scope) → Context7 hints │ │ 4. PrimedKnowledge.Render (primer_render.go): "# Relevant Knowledge", │ │ grouped by type, whole facts dropped past max_bytes (8192), │ diff --git a/src/pkg/knowledge/primer.go b/src/pkg/knowledge/primer.go index ff9ed0e4b0..ca4e600e63 100644 --- a/src/pkg/knowledge/primer.go +++ b/src/pkg/knowledge/primer.go @@ -163,7 +163,7 @@ func (p *Primer) PrimeForKick(ctx context.Context, scope *TOCScope, kc KickConte merged = scope.Filter(merged) } merged, scopedOut := FilterByKickContext(merged, kc) - reranked := p.rerankFisherRao(query, merged) + reranked := boostTaskRepos(p.rerankFisherRao(query, merged), kc.Repos) prioritized := p.applyPriority(reranked) if len(prioritized) > p.config.MaxFacts { @@ -236,6 +236,38 @@ func (p *Primer) rerankFisherRao(query string, facts []Fact) []Fact { return facts } +// taskRepoBoost is added to the rerank score of a fact tagged with the kick's +// own repository. It is a nudge, not a gate: a fact about another repo that +// matches the work clearly better still ranks first. +const taskRepoBoost = 0.1 + +// boostTaskRepos lifts the facts tagged repo:/ for one of repos +// (the knowledge-entries convention) and re-sorts by score. Every fact was +// already selected by relevance; the tag is never a reason to show one. +func boostTaskRepos(facts []Fact, repos []string) []Fact { + if len(repos) == 0 || len(facts) == 0 { + return facts + } + want := make(map[string]bool, len(repos)) + for _, r := range repos { + if r = strings.ToLower(strings.TrimSpace(r)); r != "" { + want["repo:"+r] = true + } + } + for i := range facts { + for _, tag := range facts[i].Tags { + if want[strings.ToLower(strings.TrimSpace(tag))] { + facts[i].Confidence = clampScore(facts[i].Confidence + taskRepoBoost) + break + } + } + } + sort.SliceStable(facts, func(i, j int) bool { + return facts[i].Confidence > facts[j].Confidence + }) + return facts +} + // mergeWithPrecedence deduplicates facts by slug, keeping the version from the // highest-precedence layer (personal > project > org > community). func (p *Primer) mergeWithPrecedence(facts []Fact) []Fact { diff --git a/src/pkg/knowledge/scope.go b/src/pkg/knowledge/scope.go index 048e501162..90919d7349 100644 --- a/src/pkg/knowledge/scope.go +++ b/src/pkg/knowledge/scope.go @@ -31,15 +31,22 @@ func (s *FactScope) IsZero() bool { } // KickContext is what the primer knows about the work a kick is for. The -// scheduler fills Lane and Labels from the lane name and the primed issues; -// Paths is filled only by callers that know which files are being touched. +// scheduler fills Lane, Labels and Repos from the lane name and the primed +// issues; Paths is filled only by callers that know which files are being +// touched. type KickContext struct { Lane string Labels []string Paths []string + // Repos are the primed issues' repositories as "/". They are + // not a scope dimension (Admits ignores them) and they select nothing: + // a fact tagged repo: only ranks ahead of an otherwise equal + // fact about another repo (boostTaskRepos). + Repos []string } -// IsZero reports whether the context carries nothing to match on. +// IsZero reports whether the context carries nothing a fact's scope can +// match on. Repos are not a scope dimension, so they do not count. func (kc KickContext) IsZero() bool { return kc.Lane == "" && len(kc.Labels) == 0 && len(kc.Paths) == 0 } diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index c5138dfdf7..6cdc0fba93 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -4,12 +4,14 @@ import ( "context" "fmt" "log/slog" + "regexp" "strings" "github.com/hivecommons/hive/crux/agentsmd" "github.com/hivecommons/hive/crux/skillreg" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/issueshape" "github.com/hivecommons/hive/pkg/knowledge" ) @@ -555,11 +557,17 @@ func (s *Scheduler) KickSummary(agentName string) (KickSummary, bool) { // against (#17045): the base lane name (a replica resolves to the agent it // replicates) and the union of the primed issues' labels. File paths are not // known on the kick path, so entries scoped by paths alone wait for a caller -// that has them. +// that has them. It also carries the issues' repositories, which rank entries +// tagged with them ahead of other repos' entries but admit nothing. func kickContextFor(cfg *config.Config, agentName string, issues []github.Issue) knowledge.KickContext { kc := knowledge.KickContext{Lane: cfg.BaseAgentName(agentName)} seen := make(map[string]bool) + seenRepo := make(map[string]bool) for _, issue := range issues { + if repo := strings.ToLower(strings.TrimSpace(issue.Repo)); strings.Contains(repo, "/") && !seenRepo[repo] { + seenRepo[repo] = true + kc.Repos = append(kc.Repos, repo) + } for _, label := range issue.Labels { lower := strings.ToLower(strings.TrimSpace(label)) if lower == "" || seen[lower] { @@ -575,31 +583,38 @@ func kickContextFor(cfg *config.Config, agentName string, issues []github.Issue) // extractKeywords pulls searchable terms from issue labels and titles. // Title words are included because labels alone are often all noise // (triage/accepted, kind/bug) and produce zero keywords after filtering. +// +// The hive's own routing labels and the filer tag in hive-filed titles are +// dropped: on utah-packages#879 they made up most of the query +// (stage/010-actionable, agent/reviewer, "reviewer review backlog") and pulled +// in review notes from unrelated repos. The issues' repositories are not search +// terms; they ride in the kick context and rank the repo's own entries first +// (kickContextFor). func extractKeywords(issues []github.Issue) []string { seen := make(map[string]bool) var keywords []string + add := func(word string) { + if !seen[word] { + keywords = append(keywords, word) + seen[word] = true + } + } for _, issue := range issues { for _, label := range issue.Labels { lower := strings.ToLower(label) - if !seen[lower] && !isNoiseLabel(lower) { - keywords = append(keywords, lower) - seen[lower] = true + if !isNoiseLabel(lower) { + add(lower) } } if issue.ComplexityTier != "" { - tier := strings.ToLower(issue.ComplexityTier) - if !seen[tier] { - keywords = append(keywords, tier) - seen[tier] = true - } + add(strings.ToLower(issue.ComplexityTier)) } - for _, word := range splitTitleWords(issue.Title) { - if !seen[word] && !isNoiseWord(word) { - keywords = append(keywords, word) - seen[word] = true + for _, word := range splitTitleWords(searchableTitle(issue.Title)) { + if !isNoiseWord(word) { + add(word) } } } @@ -607,6 +622,24 @@ func extractKeywords(issues []github.Issue) []string { return keywords } +// reviewBacklogTitleRE matches the stem the hive puts on its review backlog +// items, "Review backlog (): " (pkg/github +// reviewBacklogIssueTitle). +var reviewBacklogTitleRE = regexp.MustCompile(`^Review backlog \(([^)]+)\):\s*`) + +// searchableTitle is the part of an issue title that says what the issue is +// about: the leading filer tag ("[reviewer]", "[scanner]") is dropped, and a +// review backlog stem is cut down to its perspective, which names the kind of +// finding ("security", "style"). The words "review backlog" match every +// review-related entry in the vault whatever the repo. +func searchableTitle(title string) string { + title = issueshape.StripAgentPrefix(title) + if m := reviewBacklogTitleRE.FindStringSubmatch(title); m != nil { + title = m[1] + " " + title[len(m[0]):] + } + return title +} + // splitTitleWords extracts lowercase words from an issue title, dropping // short words and punctuation. func splitTitleWords(title string) []string { @@ -659,6 +692,34 @@ var noiseLabels = map[string]bool{ "hold": true, } +// noiseLabelPrefixes are the label families the hive and its review bots use +// to route and gate work: where an item sits in the pipeline (stage/, needs-), +// which lane holds it (agent/, hive/claimed-by-…), and review or merge state. +// They say nothing about what the issue is about, and they are on most items, +// so as search terms they match the same review and scanning entries for +// every task. +var noiseLabelPrefixes = []string{ + "stage/", "agent/", "hive/", "triage/", "size/", "lifecycle/", + "do-not-merge/", "needs-", "dco-signoff", "sentinel-", +} + +// noiseControlLabels are single hive or review-bot labels outside those +// families. +var noiseControlLabels = map[string]bool{ + "approved-direction": true, + "hive-review": true, + "lgtm": true, + "approved": true, +} + func isNoiseLabel(label string) bool { - return noiseLabels[label] + if noiseLabels[label] || noiseControlLabels[label] { + return true + } + for _, prefix := range noiseLabelPrefixes { + if strings.HasPrefix(label, prefix) { + return true + } + } + return false } diff --git a/src/pkg/scheduler/kick_priming_query_test.go b/src/pkg/scheduler/kick_priming_query_test.go new file mode 100644 index 0000000000..833487338e --- /dev/null +++ b/src/pkg/scheduler/kick_priming_query_test.go @@ -0,0 +1,103 @@ +package scheduler + +import ( + "context" + "log/slog" + "os" + "path/filepath" + "reflect" + "testing" + + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// utah-packages#879 as a scanner task: before, the query was the hive's own +// routing labels plus the review backlog stem ("stage/010-actionable +// agent/reviewer kind/cleanup approved-direction reviewer review backlog +// style …"), so review notes from other repos outranked anything about +// utah-packages. The query keeps what the issue is about. +func TestExtractKeywords_DropsHiveRoutingAndNamesTheRepo(t *testing.T) { + issue := github.Issue{ + Repo: "projectbluefin/utah-packages", + Number: 879, + Title: "[reviewer] Review backlog (style): spec file mixes tabs and spaces", + Labels: []string{"stage/010-actionable", "agent/reviewer", "kind/cleanup", "approved-direction", "hive/claimed-by-scanner", "needs-triage"}, + } + got := extractKeywords([]github.Issue{issue}) + want := []string{"kind/cleanup", "style", "spec", "file", "mixes", "tabs", "spaces"} + if !reflect.DeepEqual(got, want) { + t.Fatalf("keywords = %q\nwant %q", got, want) + } +} + +func TestSearchableTitle(t *testing.T) { + for title, want := range map[string]string{ + "[reviewer] Review backlog (security): token in log line": "security token in log line", + "Review backlog (style): long line": "style long line", + "[scanner] Sidebar anchors drift": "Sidebar anchors drift", + "[ACMM L0] Add a CONTRIBUTING file": "[ACMM L0] Add a CONTRIBUTING file", + "Review the backlog of stale PRs": "Review the backlog of stale PRs", + } { + if got := searchableTitle(title); got != want { + t.Errorf("searchableTitle(%q) = %q, want %q", title, got, want) + } + } +} + +func TestIsNoiseLabel_HiveRoutingFamilies(t *testing.T) { + for _, l := range []string{"stage/010-actionable", "agent/reviewer", "hive/claimed-by-scanner", "triage/needs-information", + "size/l", "needs-human", "do-not-merge/hold", "dco-signoff: yes", "sentinel-alert", "approved-direction", "hive-review", "lgtm"} { + if !isNoiseLabel(l) { + t.Errorf("%q is a hive routing label and should not be a search term", l) + } + } + for _, l := range []string{"kind/cleanup", "priority/high", "area/packaging", "rpm", "stagehand", "agentic"} { + if isNoiseLabel(l) { + t.Errorf("%q describes the work and should stay a search term", l) + } + } +} + +// The task's repo ranks its own entries first: every entry carries a +// repo:/ tag, so of two entries that match the issue equally, the +// one tagged with the task's repo comes first. The repo admits nothing: an +// entry that shares no word with the issue stays out however it is tagged. +func TestKnowledgeKick_TaskRepoRanksItsEntriesFirst(t *testing.T) { + vault := t.TempDir() + entry := func(name, title, repo string) { + body := "---\ntitle: " + title + "\ntype: gotcha\nlayer: project\ntags: [repo:" + repo + ", packaging]\n---\n" + + "Spec files use spaces for indentation, never tabs.\n" + if err := os.WriteFile(filepath.Join(vault, name+".md"), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + } + entry("other-repo", "Packaging conventions", "projectbluefin/bluefin-lts") + entry("task-repo", "Packaging conventions", "projectbluefin/utah-packages") + logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) + store, err := knowledge.NewFileStore(vault, "vault", logger) + if err != nil { + t.Fatal(err) + } + primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger) + primer.AddFileStore("vault", store, knowledge.LayerProject) + + task := github.Issue{Repo: "projectbluefin/utah-packages", Number: 879, Title: "Spec file mixes tabs and spaces"} + kc := kickContextFor(guidanceScheduler(t, "").cfg, "scanner", []github.Issue{task}) + if !reflect.DeepEqual(kc.Repos, []string{"projectbluefin/utah-packages"}) { + t.Fatalf("kick context repos = %q", kc.Repos) + } + primed := primer.PrimeForKick(context.Background(), nil, kc, extractKeywords([]github.Issue{task})) + if len(primed.Facts) != 2 { + t.Fatalf("primed %d facts, want both entries", len(primed.Facts)) + } + if primed.Facts[0].Slug != "task-repo" || primed.Facts[0].Confidence <= primed.Facts[1].Confidence { + t.Fatalf("ranking = %s (%.3f), %s (%.3f); want the task repo's entry strictly first", + primed.Facts[0].Slug, primed.Facts[0].Confidence, primed.Facts[1].Slug, primed.Facts[1].Confidence) + } + + unrelated := primer.PrimeForKick(context.Background(), nil, kc, []string{"kernel", "panic"}) + if len(unrelated.Facts) != 0 { + t.Fatalf("the repo tag alone admitted %d facts for an unrelated query", len(unrelated.Facts)) + } +} From c9c5541318d9cb51b0139f9797ff18318788b51c Mon Sep 17 00:00:00 2001 From: Douglas Baggett Date: Sun, 8 Nov 2026 20:50:26 -0500 Subject: [PATCH 2/5] test: name the keyword test for what it checks Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Douglas Baggett --- src/pkg/scheduler/kick_priming_query_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pkg/scheduler/kick_priming_query_test.go b/src/pkg/scheduler/kick_priming_query_test.go index 833487338e..40eb622ac1 100644 --- a/src/pkg/scheduler/kick_priming_query_test.go +++ b/src/pkg/scheduler/kick_priming_query_test.go @@ -17,7 +17,7 @@ import ( // agent/reviewer kind/cleanup approved-direction reviewer review backlog // style …"), so review notes from other repos outranked anything about // utah-packages. The query keeps what the issue is about. -func TestExtractKeywords_DropsHiveRoutingAndNamesTheRepo(t *testing.T) { +func TestExtractKeywords_DropsHiveRouting(t *testing.T) { issue := github.Issue{ Repo: "projectbluefin/utah-packages", Number: 879, From e8ab2972f3571b5b54e5e350179734b8ce4ba3d3 Mon Sep 17 00:00:00 2001 From: Douglas Baggett Date: Sun, 8 Nov 2026 20:57:08 -0500 Subject: [PATCH 3/5] knowledge priming: also drop the origin/ and hive: label families Seen in the projectbluefin hive's primer queries: origin/governor and hive: churn-triaged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Douglas Baggett --- changelog.d/fixed-knowledge-priming-query.md | 2 +- src/pkg/scheduler/kick_priming.go | 7 ++++--- src/pkg/scheduler/kick_priming_query_test.go | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/changelog.d/fixed-knowledge-priming-query.md b/changelog.d/fixed-knowledge-priming-query.md index f5b9842e9d..2123666038 100644 --- a/changelog.d/fixed-knowledge-priming-query.md +++ b/changelog.d/fixed-knowledge-priming-query.md @@ -1 +1 @@ -- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels and title words, and on hive-routed work those were mostly the hive's own: `stage/010-actionable`, `agent/reviewer`, `approved-direction`, and the `[reviewer] Review backlog (style):` title stem. Those words match review and scanning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos. The query now leaves out the hive's routing label families (`stage/`, `agent/`, `hive/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge/`, `needs-`, `dco-signoff`, `sentinel-`, plus `approved-direction`, `hive-review`, `lgtm` and `approved`) and the filer tag, and cuts a review backlog title down to its perspective (`style`, `security`) and finding. The task's repository now counts too: an entry tagged `repo:/` for the repo being worked on ranks ahead of an otherwise equal entry about another repo. The tag only orders entries the search already found; it never adds one on its own. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). +- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels and title words, and on hive-routed work those were mostly the hive's own: `stage/010-actionable`, `agent/reviewer`, `approved-direction`, and the `[reviewer] Review backlog (style):` title stem. Those words match review and scanning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos. The query now leaves out the hive's routing label families (`stage/`, `agent/`, `hive/`, `hive:`, `origin/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge/`, `needs-`, `dco-signoff`, `sentinel-`, plus `approved-direction`, `hive-review`, `lgtm` and `approved`) and the filer tag, and cuts a review backlog title down to its perspective (`style`, `security`) and finding. The task's repository now counts too: an entry tagged `repo:/` for the repo being worked on ranks ahead of an otherwise equal entry about another repo. The tag only orders entries the search already found; it never adds one on its own. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index 6cdc0fba93..ff9030b329 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -694,13 +694,14 @@ var noiseLabels = map[string]bool{ // noiseLabelPrefixes are the label families the hive and its review bots use // to route and gate work: where an item sits in the pipeline (stage/, needs-), -// which lane holds it (agent/, hive/claimed-by-…), and review or merge state. +// which lane holds it (agent/, hive/claimed-by-…, hive: churn-triaged), which +// lane filed it (origin/), and review or merge state. // They say nothing about what the issue is about, and they are on most items, // so as search terms they match the same review and scanning entries for // every task. var noiseLabelPrefixes = []string{ - "stage/", "agent/", "hive/", "triage/", "size/", "lifecycle/", - "do-not-merge/", "needs-", "dco-signoff", "sentinel-", + "stage/", "agent/", "hive/", "hive:", "origin/", "triage/", "size/", + "lifecycle/", "do-not-merge/", "needs-", "dco-signoff", "sentinel-", } // noiseControlLabels are single hive or review-bot labels outside those diff --git a/src/pkg/scheduler/kick_priming_query_test.go b/src/pkg/scheduler/kick_priming_query_test.go index 40eb622ac1..6efe9a650f 100644 --- a/src/pkg/scheduler/kick_priming_query_test.go +++ b/src/pkg/scheduler/kick_priming_query_test.go @@ -46,7 +46,7 @@ func TestSearchableTitle(t *testing.T) { } func TestIsNoiseLabel_HiveRoutingFamilies(t *testing.T) { - for _, l := range []string{"stage/010-actionable", "agent/reviewer", "hive/claimed-by-scanner", "triage/needs-information", + for _, l := range []string{"stage/010-actionable", "agent/reviewer", "hive/claimed-by-scanner", "hive: churn-triaged", "origin/governor", "triage/needs-information", "size/l", "needs-human", "do-not-merge/hold", "dco-signoff: yes", "sentinel-alert", "approved-direction", "hive-review", "lgtm"} { if !isNoiseLabel(l) { t.Errorf("%q is a hive routing label and should not be a search term", l) From 7e501d23679cc38609f1ef81867095d144327a7c Mon Sep 17 00:00:00 2001 From: Douglas Baggett Date: Sun, 8 Nov 2026 21:34:40 -0500 Subject: [PATCH 4/5] knowledge priming: never worse than before, and keep topic tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 2, from an independent review of round 1: - A query left empty by the filter falls back to the old one (legacyKeywords), so no kick loses a section it had. - A leading [tag] comes off only when it names a hive lane, origin source or configured agent; "[nvidia] …" keeps nvidia. - The complexity tier is no longer a search term; epic, claimed, author/* and hive-pause/* join the routing labels, using the config helpers for agent/* and origin/*. - The task-repo boost is a separate rankBoost that applyPriority sorts on within a type; Confidence, which kicks show, is untouched. It uses FactRepo and matches a bare repo: code-map tag. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Douglas Baggett --- changelog.d/fixed-knowledge-priming-query.md | 2 +- src/docs/agent-knowledge-and-memory.md | 15 +- src/pkg/knowledge/primer.go | 46 +++--- src/pkg/knowledge/primer_task_repo_test.go | 37 +++++ src/pkg/knowledge/scope.go | 2 +- src/pkg/knowledge/types.go | 5 + src/pkg/scheduler/kick_priming.go | 136 ++++++++++++++---- src/pkg/scheduler/kick_priming_query_test.go | 144 ++++++++++++------- 8 files changed, 283 insertions(+), 104 deletions(-) create mode 100644 src/pkg/knowledge/primer_task_repo_test.go diff --git a/changelog.d/fixed-knowledge-priming-query.md b/changelog.d/fixed-knowledge-priming-query.md index 2123666038..2c8da00d89 100644 --- a/changelog.d/fixed-knowledge-priming-query.md +++ b/changelog.d/fixed-knowledge-priming-query.md @@ -1 +1 @@ -- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels and title words, and on hive-routed work those were mostly the hive's own: `stage/010-actionable`, `agent/reviewer`, `approved-direction`, and the `[reviewer] Review backlog (style):` title stem. Those words match review and scanning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos. The query now leaves out the hive's routing label families (`stage/`, `agent/`, `hive/`, `hive:`, `origin/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge/`, `needs-`, `dco-signoff`, `sentinel-`, plus `approved-direction`, `hive-review`, `lgtm` and `approved`) and the filer tag, and cuts a review backlog title down to its perspective (`style`, `security`) and finding. The task's repository now counts too: an entry tagged `repo:/` for the repo being worked on ranks ahead of an otherwise equal entry about another repo. The tag only orders entries the search already found; it never adds one on its own. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). +- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels, complexity tier and title words. On hive-routed work those were mostly the hive's own: `epic`, `approved-direction`, `stage/010-actionable`, `agent/reviewer`, `medium`, and the `[reviewer] Review backlog (style):` title stem. They match review and planning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos, and on the projectbluefin hive the reviewer, quality and sec-check kicks carried the same section whatever their work. The query now leaves out what the hive itself put on the item: its routing label families (`stage/`, `agent/`, `origin/`, `hive/`, `hive:`, `hive-pause/`, `author/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge/`, `needs-`, `dco-signoff`, `sentinel-`, plus `approved-direction`, `hive-review`, `lgtm`, `approved`, `claimed` and `epic`), the complexity tier, a leading `[]` tag when it names a hive lane, origin source or configured agent (a person's `[nvidia] …` keeps `nvidia`), and the review backlog stem, cut down to its perspective (`style`, `security`). When nothing is left, the query falls back to the one earlier releases built, so no kick loses its knowledge section. The task's repository now counts too: within a type, an entry tagged `repo:/` for the repo being worked on (or `repo:`, as a code map configured by path is tagged) ranks ahead of an otherwise equal entry about another repo. The tag only orders entries the search already found and never adds one, and the confidence a kick shows is unchanged. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index db4244fd0a..e459e1b748 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -27,16 +27,19 @@ memory. registerKnowledgeStores (cmd/hive/boot_knowledge_primer.go) ▼ ┌───────────────── Scheduler.primeKnowledge (pkg/scheduler/kick_priming.go) ───┐ - │ 1. extractKeywords ← titles + labels of the agent's first │ - │ maxIssuesToPrime (=5) queued issues, minus hive routing │ - │ labels (stage/, agent/, hive/, needs-, …) and the [agent] / │ - │ "Review backlog ():" title stem │ + │ 1. extractKeywordsFor ← titles + labels of the agent's first │ + │ maxIssuesToPrime (=5) queued issues, minus what the hive put │ + │ there: routing labels (stage/, agent/, origin/, hive/, needs-, │ + │ …), the complexity tier, a filer tag naming a hive agent and │ + │ the "Review backlog ():" stem; if nothing is │ + │ left, the pre-filter query (legacyKeywords) │ │ 2. scope ← knowledge.agent_scopes[] (or base agent for a replica) │ │ 3. Primer.PrimeScoped (pkg/knowledge/primer.go) │ │ search every layer/store → merge by layer precedence → │ │ FilterByLifecycle (approved only) → scope.Filter → │ - │ Fisher-Rao rerank → +0.1 for entries tagged repo: → │ - │ type priority → cap at max_facts (25) → │ + │ Fisher-Rao rerank → type priority (within a type, +0.1 to │ + │ rank, not to confidence, for entries tagged repo:) → cap at max_facts (25) → │ │ expandWithGraph (never past the scope) → Context7 hints │ │ 4. PrimedKnowledge.Render (primer_render.go): "# Relevant Knowledge", │ │ grouped by type, whole facts dropped past max_bytes (8192), │ diff --git a/src/pkg/knowledge/primer.go b/src/pkg/knowledge/primer.go index ca4e600e63..c3e5f1c9c5 100644 --- a/src/pkg/knowledge/primer.go +++ b/src/pkg/knowledge/primer.go @@ -3,6 +3,7 @@ package knowledge import ( "context" "log/slog" + "path" "sort" "strings" "time" @@ -236,35 +237,37 @@ func (p *Primer) rerankFisherRao(query string, facts []Fact) []Fact { return facts } -// taskRepoBoost is added to the rerank score of a fact tagged with the kick's -// own repository. It is a nudge, not a gate: a fact about another repo that -// matches the work clearly better still ranks first. +// taskRepoBoost is added to the ranking score of a fact tagged with the +// kick's own repository. It is a nudge, not a gate: a fact about another repo +// that matches the work clearly better still ranks first. const taskRepoBoost = 0.1 -// boostTaskRepos lifts the facts tagged repo:/ for one of repos -// (the knowledge-entries convention) and re-sorts by score. Every fact was -// already selected by relevance; the tag is never a reason to show one. +// boostTaskRepos marks the facts whose repo: tag (FactRepo) names one of +// repos, so applyPriority ranks them ahead of an otherwise equal fact within +// the same type. It sets rankBoost only: Confidence, which the kick shows, is +// untouched. Every fact was already selected by relevance; the tag is never a +// reason to show one. A tag holding a bare repository name, as a code map +// configured by path is tagged, matches the task repo's name part. func boostTaskRepos(facts []Fact, repos []string) []Fact { - if len(repos) == 0 || len(facts) == 0 { + if len(repos) == 0 { return facts } - want := make(map[string]bool, len(repos)) - for _, r := range repos { - if r = strings.ToLower(strings.TrimSpace(r)); r != "" { - want["repo:"+r] = true - } - } for i := range facts { - for _, tag := range facts[i].Tags { - if want[strings.ToLower(strings.TrimSpace(tag))] { - facts[i].Confidence = clampScore(facts[i].Confidence + taskRepoBoost) + tagged := FactRepo(facts[i]) + if tagged == "" { + continue + } + for _, repo := range repos { + name := repo + if !strings.Contains(tagged, "/") { + name = path.Base(repo) + } + if strings.EqualFold(tagged, name) { + facts[i].rankBoost = taskRepoBoost break } } } - sort.SliceStable(facts, func(i, j int) bool { - return facts[i].Confidence > facts[j].Confidence - }) return facts } @@ -286,7 +289,8 @@ func (p *Primer) mergeWithPrecedence(facts []Fact) []Fact { return result } -// applyPriority sorts facts by configured type priority, then by confidence. +// applyPriority sorts facts by configured type priority, then by confidence +// plus any task-repo rank boost (boostTaskRepos). func (p *Primer) applyPriority(facts []Fact) []Fact { priorityMap := make(map[string]int) for i, typ := range p.config.Priority { @@ -306,7 +310,7 @@ func (p *Primer) applyPriority(facts []Fact) []Fact { if pi != pj { return pi < pj } - return facts[i].Confidence > facts[j].Confidence + return facts[i].Confidence+facts[i].rankBoost > facts[j].Confidence+facts[j].rankBoost }) return facts diff --git a/src/pkg/knowledge/primer_task_repo_test.go b/src/pkg/knowledge/primer_task_repo_test.go new file mode 100644 index 0000000000..6f8b7b62e1 --- /dev/null +++ b/src/pkg/knowledge/primer_task_repo_test.go @@ -0,0 +1,37 @@ +package knowledge + +import "testing" + +// The task-repo boost orders facts within a type and never across types, and +// it leaves the confidence a kick shows alone. +func TestBoostTaskRepos_OrdersWithinTypeOnly(t *testing.T) { + p := &Primer{config: PrimerConfig{Priority: []string{"gotcha", "pattern"}}} + facts := []Fact{ + {Slug: "other-gotcha", Type: FactGotcha, Confidence: 0.50, Tags: []string{"repo:org/other"}}, + {Slug: "task-gotcha", Type: FactGotcha, Confidence: 0.45, Tags: []string{"repo:Org/Task"}}, + {Slug: "task-pattern", Type: FactPattern, Confidence: 0.90, Tags: []string{"repo:org/task"}}, + {Slug: "task-codemap", Type: FactPattern, Confidence: 0.85, Tags: []string{"repo:task"}}, + {Slug: "untagged", Type: FactPattern, Confidence: 0.92}, + } + sorted := p.applyPriority(boostTaskRepos(facts, []string{"org/task"})) + + want := []string{"task-gotcha", "other-gotcha", "task-pattern", "task-codemap", "untagged"} + for i, slug := range want { + if sorted[i].Slug != slug { + t.Fatalf("position %d = %s, want %s (order %v)", i, sorted[i].Slug, slug, slugsOf(sorted)) + } + } + for _, f := range sorted { + if f.Slug == "task-gotcha" && f.Confidence != 0.45 { + t.Errorf("boost changed the shown confidence to %.2f", f.Confidence) + } + } +} + +func slugsOf(facts []Fact) []string { + out := make([]string, len(facts)) + for i, f := range facts { + out[i] = f.Slug + } + return out +} diff --git a/src/pkg/knowledge/scope.go b/src/pkg/knowledge/scope.go index 90919d7349..62a64cd2f3 100644 --- a/src/pkg/knowledge/scope.go +++ b/src/pkg/knowledge/scope.go @@ -41,7 +41,7 @@ type KickContext struct { // Repos are the primed issues' repositories as "/". They are // not a scope dimension (Admits ignores them) and they select nothing: // a fact tagged repo: only ranks ahead of an otherwise equal - // fact about another repo (boostTaskRepos). + // fact of the same type about another repo (boostTaskRepos). Repos []string } diff --git a/src/pkg/knowledge/types.go b/src/pkg/knowledge/types.go index 24371c0b1d..90ee38eadf 100644 --- a/src/pkg/knowledge/types.go +++ b/src/pkg/knowledge/types.go @@ -299,6 +299,11 @@ type Fact struct { Updated time.Time `json:"-"` BodySize int `json:"-"` Origin string `json:"-"` + + // rankBoost is added to Confidence when PrimeForKick orders facts, for a + // fact about the kick's own repository (boostTaskRepos). It changes the + // order only, never the confidence a kick shows. + rankBoost float64 } // Source tracks where a fact was extracted from. diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index ff9030b329..e9749be59e 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -9,6 +9,7 @@ import ( "github.com/hivecommons/hive/crux/agentsmd" "github.com/hivecommons/hive/crux/skillreg" + "github.com/hivecommons/hive/pkg/authorkind" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/github" "github.com/hivecommons/hive/pkg/issueshape" @@ -382,7 +383,7 @@ func (s *Scheduler) renderKnowledge(primer *knowledge.Primer, cfg *config.Config return knowledgeInjection{}, nil } - keywords := extractKeywords(issues) + keywords := extractKeywordsFor(cfg, issues) if len(keywords) == 0 { s.logger.Debug("knowledge primer: no keywords extracted from issues", "issue_count", len(issues)) return knowledgeInjection{}, nil @@ -580,17 +581,29 @@ func kickContextFor(cfg *config.Config, agentName string, issues []github.Issue) return kc } -// extractKeywords pulls searchable terms from issue labels and titles. +// extractKeywords pulls searchable terms from issue labels and titles, for a +// hive with no agents of its own configured beyond the built-in lanes; see +// extractKeywordsFor. +func extractKeywords(issues []github.Issue) []string { + return extractKeywordsFor(nil, issues) +} + +// extractKeywordsFor pulls searchable terms from issue labels and titles. // Title words are included because labels alone are often all noise // (triage/accepted, kind/bug) and produce zero keywords after filtering. // -// The hive's own routing labels and the filer tag in hive-filed titles are -// dropped: on utah-packages#879 they made up most of the query -// (stage/010-actionable, agent/reviewer, "reviewer review backlog") and pulled -// in review notes from unrelated repos. The issues' repositories are not search -// terms; they ride in the kick context and rank the repo's own entries first -// (kickContextFor). -func extractKeywords(issues []github.Issue) []string { +// What the hive itself puts on an item is dropped, because it says where the +// item sits in the hive, not what it is about: its routing labels +// (isNoiseLabel), its complexity tier, the "[]" filer tag on a title it +// filed, and the "Review backlog" stem. On utah-packages#879 those made up +// most of the query (stage/010-actionable, agent/reviewer, medium, "reviewer +// review backlog") and pulled in review notes from unrelated repos. +// +// When nothing is left, the query falls back to the terms earlier releases +// used (legacyKeywords), so no kick loses its knowledge section to the filter. +// The issues' repositories are not search terms; they ride in the kick +// context and rank the repo's own entries first (kickContextFor). +func extractKeywordsFor(cfg *config.Config, issues []github.Issue) []string { seen := make(map[string]bool) var keywords []string add := func(word string) { @@ -608,13 +621,47 @@ func extractKeywords(issues []github.Issue) []string { } } + for _, word := range splitTitleWords(searchableTitle(cfg, issue.Title)) { + if !isNoiseWord(word) { + add(word) + } + } + } + + if len(keywords) == 0 { + return legacyKeywords(issues) + } + return keywords +} + +// legacyKeywords is the query earlier releases built: every label outside +// noiseLabels, the complexity tier, and every title word. It is the fallback +// for an issue whose own words are all hive routing. +func legacyKeywords(issues []github.Issue) []string { + seen := make(map[string]bool) + var keywords []string + + for _, issue := range issues { + for _, label := range issue.Labels { + lower := strings.ToLower(label) + if !seen[lower] && !noiseLabels[lower] { + keywords = append(keywords, lower) + seen[lower] = true + } + } + if issue.ComplexityTier != "" { - add(strings.ToLower(issue.ComplexityTier)) + tier := strings.ToLower(issue.ComplexityTier) + if !seen[tier] { + keywords = append(keywords, tier) + seen[tier] = true + } } - for _, word := range splitTitleWords(searchableTitle(issue.Title)) { - if !isNoiseWord(word) { - add(word) + for _, word := range splitTitleWords(issue.Title) { + if !seen[word] && !isNoiseWord(word) { + keywords = append(keywords, word) + seen[word] = true } } } @@ -628,18 +675,46 @@ func extractKeywords(issues []github.Issue) []string { var reviewBacklogTitleRE = regexp.MustCompile(`^Review backlog \(([^)]+)\):\s*`) // searchableTitle is the part of an issue title that says what the issue is -// about: the leading filer tag ("[reviewer]", "[scanner]") is dropped, and a -// review backlog stem is cut down to its perspective, which names the kind of -// finding ("security", "style"). The words "review backlog" match every -// review-related entry in the vault whatever the repo. -func searchableTitle(title string) string { - title = issueshape.StripAgentPrefix(title) +// about. A leading "[]" tag is dropped only when it names a hive filer +// (isHiveFiler): any lowercase word in brackets has the filer shape, and a +// person's "[nvidia] driver fails to build" keeps "nvidia". A review backlog +// stem is cut down to its perspective, which names the kind of finding +// ("security", "style"); the words "review backlog" match every review-related +// entry in the vault whatever the repo. +func searchableTitle(cfg *config.Config, title string) string { + title = strings.TrimSpace(title) + if tag := issueshape.AgentPrefix(title); tag != "" && isHiveFiler(cfg, tag) { + title = issueshape.StripAgentPrefix(title) + } if m := reviewBacklogTitleRE.FindStringSubmatch(title); m != nil { title = m[1] + " " + title[len(m[0]):] } return title } +// isHiveFiler reports whether tag names something that files issues for the +// hive: a built-in lane (scanner, reviewer, …), another origin source +// (selfreport, governor, …) or an agent configured on this hive. +func isHiveFiler(cfg *config.Config, tag string) bool { + tag = strings.ToLower(strings.TrimSpace(tag)) + if config.IsKnownOriginLane(tag) { + return true + } + for _, source := range config.KnownOriginSources() { + if tag == source { + return true + } + } + if cfg != nil { + for name := range cfg.Agents { + if strings.EqualFold(name, tag) || strings.EqualFold(cfg.BaseAgentName(name), tag) { + return true + } + } + } + return false +} + // splitTitleWords extracts lowercase words from an issue title, dropping // short words and punctuation. func splitTitleWords(title string) []string { @@ -694,29 +769,36 @@ var noiseLabels = map[string]bool{ // noiseLabelPrefixes are the label families the hive and its review bots use // to route and gate work: where an item sits in the pipeline (stage/, needs-), -// which lane holds it (agent/, hive/claimed-by-…, hive: churn-triaged), which -// lane filed it (origin/), and review or merge state. -// They say nothing about what the issue is about, and they are on most items, -// so as search terms they match the same review and scanning entries for -// every task. +// which lane holds or filed it (agent/ and origin/, see isNoiseLabel; +// hive/claimed-by-…; hive: churn-triaged), a hive's hold (hive-pause/), +// the author class (author/human, …), and review or merge state. They say +// nothing about what the issue is about, and they are on most items, so as +// search terms they match the same review and scanning entries for every task. var noiseLabelPrefixes = []string{ - "stage/", "agent/", "hive/", "hive:", "origin/", "triage/", "size/", - "lifecycle/", "do-not-merge/", "needs-", "dco-signoff", "sentinel-", + "stage/", "hive/", "hive:", github.HiveHoldLabelPrefix, authorkind.Prefix, + "triage/", "size/", "lifecycle/", "do-not-merge/", "needs-", "dco-signoff", + "sentinel-", } // noiseControlLabels are single hive or review-bot labels outside those -// families. +// families. "epic" is the hive's default never-claim marker for trackers +// (claims.DefaultNeverClaimLabels); "claimed" is its claim marker. var noiseControlLabels = map[string]bool{ "approved-direction": true, "hive-review": true, "lgtm": true, "approved": true, + "claimed": true, + "epic": true, } func isNoiseLabel(label string) bool { if noiseLabels[label] || noiseControlLabels[label] { return true } + if config.IsAgentLaneLabel(label) || config.IsOriginLabel(label) { + return true + } for _, prefix := range noiseLabelPrefixes { if strings.HasPrefix(label, prefix) { return true diff --git a/src/pkg/scheduler/kick_priming_query_test.go b/src/pkg/scheduler/kick_priming_query_test.go index 6efe9a650f..deeee152c1 100644 --- a/src/pkg/scheduler/kick_priming_query_test.go +++ b/src/pkg/scheduler/kick_priming_query_test.go @@ -8,21 +8,25 @@ import ( "reflect" "testing" + "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/github" "github.com/hivecommons/hive/pkg/knowledge" ) // utah-packages#879 as a scanner task: before, the query was the hive's own -// routing labels plus the review backlog stem ("stage/010-actionable -// agent/reviewer kind/cleanup approved-direction reviewer review backlog -// style …"), so review notes from other repos outranked anything about -// utah-packages. The query keeps what the issue is about. +// routing labels, its complexity tier and the review backlog stem +// ("stage/010-actionable agent/reviewer kind/cleanup approved-direction +// medium reviewer review backlog style …"), so review notes from other repos +// outranked anything about utah-packages. The query keeps what the issue is +// about. func TestExtractKeywords_DropsHiveRouting(t *testing.T) { issue := github.Issue{ - Repo: "projectbluefin/utah-packages", - Number: 879, - Title: "[reviewer] Review backlog (style): spec file mixes tabs and spaces", - Labels: []string{"stage/010-actionable", "agent/reviewer", "kind/cleanup", "approved-direction", "hive/claimed-by-scanner", "needs-triage"}, + Repo: "projectbluefin/utah-packages", + Number: 879, + Title: "[reviewer] Review backlog (style): spec file mixes tabs and spaces", + ComplexityTier: "Medium", + Labels: []string{"stage/010-actionable", "agent/reviewer", "kind/cleanup", "approved-direction", + "hive/claimed-by-scanner", "needs-triage", "epic", "claimed", "author/human", "hive-pause/h1", "origin/governor"}, } got := extractKeywords([]github.Issue{issue}) want := []string{"kind/cleanup", "style", "spec", "file", "mixes", "tabs", "spaces"} @@ -31,73 +35,117 @@ func TestExtractKeywords_DropsHiveRouting(t *testing.T) { } } +// An issue whose every term is hive routing falls back to the query earlier +// releases built, so the filter never leaves a kick with no knowledge section +// it used to get. +func TestExtractKeywords_AllRoutingFallsBackToLegacyQuery(t *testing.T) { + issue := github.Issue{ + Repo: "projectbluefin/utah", + Number: 12, + Title: "[ci-maintainer] Fix CI", + Labels: []string{"agent/ci-maintainer", "stage/010-actionable", "kind/bug"}, + } + got := extractKeywords([]github.Issue{issue}) + want := []string{"agent/ci-maintainer", "stage/010-actionable", "ci-maintainer"} + if !reflect.DeepEqual(got, want) { + t.Fatalf("keywords = %q\nwant the legacy query %q", got, want) + } + if !reflect.DeepEqual(got, legacyKeywords([]github.Issue{issue})) { + t.Fatal("the fallback is not the legacy query") + } +} + func TestSearchableTitle(t *testing.T) { + cfg := &config.Config{} + cfg.Agents = map[string]config.AgentConfig{"packager": {}} for title, want := range map[string]string{ "[reviewer] Review backlog (security): token in log line": "security token in log line", "Review backlog (style): long line": "style long line", "[scanner] Sidebar anchors drift": "Sidebar anchors drift", + "[selfreport] Agent pane froze": "Agent pane froze", + "[packager] Bump the spec": "Bump the spec", + "[nvidia] driver fails to build on F44": "[nvidia] driver fails to build on F44", "[ACMM L0] Add a CONTRIBUTING file": "[ACMM L0] Add a CONTRIBUTING file", "Review the backlog of stale PRs": "Review the backlog of stale PRs", } { - if got := searchableTitle(title); got != want { + if got := searchableTitle(cfg, title); got != want { t.Errorf("searchableTitle(%q) = %q, want %q", title, got, want) } } + if got := searchableTitle(nil, "[packager] Bump the spec"); got != "[packager] Bump the spec" { + t.Errorf("an unconfigured agent name was stripped as a filer: %q", got) + } } func TestIsNoiseLabel_HiveRoutingFamilies(t *testing.T) { - for _, l := range []string{"stage/010-actionable", "agent/reviewer", "hive/claimed-by-scanner", "hive: churn-triaged", "origin/governor", "triage/needs-information", - "size/l", "needs-human", "do-not-merge/hold", "dco-signoff: yes", "sentinel-alert", "approved-direction", "hive-review", "lgtm"} { + for _, l := range []string{"stage/010-actionable", "stage/stalled", "agent/reviewer", "hive/claimed-by-scanner", "hive: churn-triaged", + "origin/governor", "triage/needs-information", "size/l", "needs-human", "do-not-merge/hold", "dco-signoff: yes", + "sentinel-alert", "approved-direction", "hive-review", "lgtm", "claimed", "epic", "author/human", "hive-pause/h1"} { if !isNoiseLabel(l) { t.Errorf("%q is a hive routing label and should not be a search term", l) } } - for _, l := range []string{"kind/cleanup", "priority/high", "area/packaging", "rpm", "stagehand", "agentic"} { + for _, l := range []string{"kind/cleanup", "priority/high", "area/packaging", "rpm", "stagehand", "agentic", "authoring", "epics-tracker"} { if isNoiseLabel(l) { t.Errorf("%q describes the work and should stay a search term", l) } } } -// The task's repo ranks its own entries first: every entry carries a -// repo:/ tag, so of two entries that match the issue equally, the -// one tagged with the task's repo comes first. The repo admits nothing: an +// The task's repo ranks its own entries first within a type: of two entries +// that match the issue equally, the one tagged with the task's repo comes +// first, a code map tagged with the bare repo name counts, and the confidence +// the kick shows is not changed by the ranking. The repo admits nothing: an // entry that shares no word with the issue stays out however it is tagged. func TestKnowledgeKick_TaskRepoRanksItsEntriesFirst(t *testing.T) { - vault := t.TempDir() - entry := func(name, title, repo string) { - body := "---\ntitle: " + title + "\ntype: gotcha\nlayer: project\ntags: [repo:" + repo + ", packaging]\n---\n" + - "Spec files use spaces for indentation, never tabs.\n" - if err := os.WriteFile(filepath.Join(vault, name+".md"), []byte(body), 0o644); err != nil { - t.Fatal(err) - } - } - entry("other-repo", "Packaging conventions", "projectbluefin/bluefin-lts") - entry("task-repo", "Packaging conventions", "projectbluefin/utah-packages") - logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) - store, err := knowledge.NewFileStore(vault, "vault", logger) - if err != nil { - t.Fatal(err) - } - primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger) - primer.AddFileStore("vault", store, knowledge.LayerProject) + for _, tc := range []struct{ name, taskTag string }{ + {"org/name tag", "projectbluefin/utah-packages"}, + {"bare code-map tag", "utah-packages"}, + } { + t.Run(tc.name, func(t *testing.T) { + vault := t.TempDir() + entry := func(name, repo string) { + body := "---\ntitle: Packaging conventions\ntype: gotcha\nlayer: project\ntags: [repo:" + repo + ", packaging]\n---\n" + + "Spec files use spaces for indentation, never tabs.\n" + if err := os.WriteFile(filepath.Join(vault, name+".md"), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + } + entry("other-repo", "projectbluefin/bluefin-lts") + entry("task-repo", tc.taskTag) + logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) + store, err := knowledge.NewFileStore(vault, "vault", logger) + if err != nil { + t.Fatal(err) + } + primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger) + primer.AddFileStore("vault", store, knowledge.LayerProject) - task := github.Issue{Repo: "projectbluefin/utah-packages", Number: 879, Title: "Spec file mixes tabs and spaces"} - kc := kickContextFor(guidanceScheduler(t, "").cfg, "scanner", []github.Issue{task}) - if !reflect.DeepEqual(kc.Repos, []string{"projectbluefin/utah-packages"}) { - t.Fatalf("kick context repos = %q", kc.Repos) - } - primed := primer.PrimeForKick(context.Background(), nil, kc, extractKeywords([]github.Issue{task})) - if len(primed.Facts) != 2 { - t.Fatalf("primed %d facts, want both entries", len(primed.Facts)) - } - if primed.Facts[0].Slug != "task-repo" || primed.Facts[0].Confidence <= primed.Facts[1].Confidence { - t.Fatalf("ranking = %s (%.3f), %s (%.3f); want the task repo's entry strictly first", - primed.Facts[0].Slug, primed.Facts[0].Confidence, primed.Facts[1].Slug, primed.Facts[1].Confidence) - } + task := github.Issue{Repo: "projectbluefin/utah-packages", Number: 879, Title: "Spec file mixes tabs and spaces"} + kc := kickContextFor(guidanceScheduler(t, "").cfg, "scanner", []github.Issue{task}) + if !reflect.DeepEqual(kc.Repos, []string{"projectbluefin/utah-packages"}) { + t.Fatalf("kick context repos = %q", kc.Repos) + } + plain := primer.PrimeForKick(context.Background(), nil, knowledge.KickContext{}, extractKeywords([]github.Issue{task})) + primed := primer.PrimeForKick(context.Background(), nil, kc, extractKeywords([]github.Issue{task})) + if len(primed.Facts) != 2 || len(plain.Facts) != 2 { + t.Fatalf("primed %d / %d facts, want both entries", len(primed.Facts), len(plain.Facts)) + } + if primed.Facts[0].Slug != "task-repo" { + t.Fatalf("ranking = %s, %s; want the task repo's entry first", primed.Facts[0].Slug, primed.Facts[1].Slug) + } + for _, f := range primed.Facts { + for _, g := range plain.Facts { + if f.Slug == g.Slug && f.Confidence != g.Confidence { + t.Errorf("%s: confidence %.3f with the repo boost, %.3f without; the boost must not change it", f.Slug, f.Confidence, g.Confidence) + } + } + } - unrelated := primer.PrimeForKick(context.Background(), nil, kc, []string{"kernel", "panic"}) - if len(unrelated.Facts) != 0 { - t.Fatalf("the repo tag alone admitted %d facts for an unrelated query", len(unrelated.Facts)) + unrelated := primer.PrimeForKick(context.Background(), nil, kc, []string{"kernel", "panic"}) + if len(unrelated.Facts) != 0 { + t.Fatalf("the repo tag alone admitted %d facts for an unrelated query", len(unrelated.Facts)) + } + }) } } From 459cab3845632366206857dcfd8a46edb6b7ef93 Mon Sep 17 00:00:00 2001 From: Douglas Baggett Date: Sun, 8 Nov 2026 21:42:44 -0500 Subject: [PATCH 5/5] knowledge priming: query only; retry the old query when nothing matches Round 3, from a second independent review: - The repo ranking is out of this PR (kept on a local branch): it could change which entries survive the caps, and does nothing on a vault without repo: tags. The knowledge package is back to v6. - When the issue's own terms match no entry, renderKnowledge searches again with the old query, so no kick loses the section it got. - Never-claim labels come from claims.never_claim_labels; Prow's tide/, ok-to-test, release-note, cncf-cla: and bare do-not-merge are left out. - One collectKeywords walk serves both queries; the review backlog regex takes any leading tag; the filer set is built once per query. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Douglas Baggett --- changelog.d/fixed-knowledge-priming-query.md | 2 +- src/docs/agent-knowledge-and-memory.md | 11 +- src/pkg/knowledge/primer.go | 42 +--- src/pkg/knowledge/primer_task_repo_test.go | 37 --- src/pkg/knowledge/scope.go | 13 +- src/pkg/knowledge/types.go | 5 - src/pkg/scheduler/kick_priming.go | 232 ++++++++++--------- src/pkg/scheduler/kick_priming_query_test.go | 144 ++++++------ 8 files changed, 209 insertions(+), 277 deletions(-) delete mode 100644 src/pkg/knowledge/primer_task_repo_test.go diff --git a/changelog.d/fixed-knowledge-priming-query.md b/changelog.d/fixed-knowledge-priming-query.md index 2c8da00d89..1d779e877c 100644 --- a/changelog.d/fixed-knowledge-priming-query.md +++ b/changelog.d/fixed-knowledge-priming-query.md @@ -1 +1 @@ -- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels, complexity tier and title words. On hive-routed work those were mostly the hive's own: `epic`, `approved-direction`, `stage/010-actionable`, `agent/reviewer`, `medium`, and the `[reviewer] Review backlog (style):` title stem. They match review and planning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos, and on the projectbluefin hive the reviewer, quality and sec-check kicks carried the same section whatever their work. The query now leaves out what the hive itself put on the item: its routing label families (`stage/`, `agent/`, `origin/`, `hive/`, `hive:`, `hive-pause/`, `author/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge/`, `needs-`, `dco-signoff`, `sentinel-`, plus `approved-direction`, `hive-review`, `lgtm`, `approved`, `claimed` and `epic`), the complexity tier, a leading `[]` tag when it names a hive lane, origin source or configured agent (a person's `[nvidia] …` keeps `nvidia`), and the review backlog stem, cut down to its perspective (`style`, `security`). When nothing is left, the query falls back to the one earlier releases built, so no kick loses its knowledge section. The task's repository now counts too: within a type, an entry tagged `repo:/` for the repo being worked on (or `repo:`, as a code map configured by path is tagged) ranks ahead of an otherwise equal entry about another repo. The tag only orders entries the search already found and never adds one, and the confidence a kick shows is unchanged. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). +- **Primed knowledge is now about the task, not about the hive's own routing.** The "# Relevant Knowledge" search built its query from an issue's labels, complexity tier and title words. On hive-routed work those were mostly the hive's own: `epic`, `approved-direction`, `stage/010-actionable`, `agent/reviewer`, `medium`, and the `[reviewer] Review backlog (style):` title stem. They match review and planning notes in every repo, so a scanner task on `projectbluefin/utah-packages#879` was primed with entries about other repos, and on the projectbluefin hive the reviewer, quality and sec-check kicks carried the same section whatever their work. The query now leaves out what the hive itself put on the item: its routing label families (`stage/`, `agent/`, `origin/`, `hive/`, `hive:`, `hive-pause/`, `author/`, `triage/`, `size/`, `lifecycle/`, `do-not-merge`, `needs-`, `dco-signoff`, `sentinel-`), Prow's (`tide/`, `ok-to-test`, `release-note`, `cncf-cla:`), the labels `approved-direction`, `hive-review`, `lgtm`, `approved` and `claimed`, the hive's never-claim labels (`claims.never_claim_labels`, default `epic`), the complexity tier, a leading `[]` tag when it names a hive lane, origin source or configured agent (a person's `[nvidia] …` keeps `nvidia`), and the review backlog stem, cut down to its perspective (`style`, `security`). When that leaves nothing to search on, or what is left matches no entry, the search runs again with the query earlier releases built, so no kick loses the section it got before. This applies to resident kicks and to contributor role guidance alike. See [Knowledge: the kick primer](src/docs/agent-knowledge-and-memory.md#1-knowledge-the-kick-primer-push). diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index e459e1b748..723cf1faa5 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -30,16 +30,15 @@ memory. │ 1. extractKeywordsFor ← titles + labels of the agent's first │ │ maxIssuesToPrime (=5) queued issues, minus what the hive put │ │ there: routing labels (stage/, agent/, origin/, hive/, needs-, │ - │ …), the complexity tier, a filer tag naming a hive agent and │ - │ the "Review backlog ():" stem; if nothing is │ - │ left, the pre-filter query (legacyKeywords) │ + │ never-claim, Prow's, …), the complexity tier, a filer tag │ + │ naming a hive agent and the "Review backlog (

):" stem; when │ + │ that leaves nothing, or matches no entry in step 3, the search │ + │ uses the pre-filter query instead (legacyKeywords) │ │ 2. scope ← knowledge.agent_scopes[] (or base agent for a replica) │ │ 3. Primer.PrimeScoped (pkg/knowledge/primer.go) │ │ search every layer/store → merge by layer precedence → │ │ FilterByLifecycle (approved only) → scope.Filter → │ - │ Fisher-Rao rerank → type priority (within a type, +0.1 to │ - │ rank, not to confidence, for entries tagged repo:) → cap at max_facts (25) → │ + │ Fisher-Rao rerank → type priority → cap at max_facts (25) → │ │ expandWithGraph (never past the scope) → Context7 hints │ │ 4. PrimedKnowledge.Render (primer_render.go): "# Relevant Knowledge", │ │ grouped by type, whole facts dropped past max_bytes (8192), │ diff --git a/src/pkg/knowledge/primer.go b/src/pkg/knowledge/primer.go index c3e5f1c9c5..ff9ed0e4b0 100644 --- a/src/pkg/knowledge/primer.go +++ b/src/pkg/knowledge/primer.go @@ -3,7 +3,6 @@ package knowledge import ( "context" "log/slog" - "path" "sort" "strings" "time" @@ -164,7 +163,7 @@ func (p *Primer) PrimeForKick(ctx context.Context, scope *TOCScope, kc KickConte merged = scope.Filter(merged) } merged, scopedOut := FilterByKickContext(merged, kc) - reranked := boostTaskRepos(p.rerankFisherRao(query, merged), kc.Repos) + reranked := p.rerankFisherRao(query, merged) prioritized := p.applyPriority(reranked) if len(prioritized) > p.config.MaxFacts { @@ -237,40 +236,6 @@ func (p *Primer) rerankFisherRao(query string, facts []Fact) []Fact { return facts } -// taskRepoBoost is added to the ranking score of a fact tagged with the -// kick's own repository. It is a nudge, not a gate: a fact about another repo -// that matches the work clearly better still ranks first. -const taskRepoBoost = 0.1 - -// boostTaskRepos marks the facts whose repo: tag (FactRepo) names one of -// repos, so applyPriority ranks them ahead of an otherwise equal fact within -// the same type. It sets rankBoost only: Confidence, which the kick shows, is -// untouched. Every fact was already selected by relevance; the tag is never a -// reason to show one. A tag holding a bare repository name, as a code map -// configured by path is tagged, matches the task repo's name part. -func boostTaskRepos(facts []Fact, repos []string) []Fact { - if len(repos) == 0 { - return facts - } - for i := range facts { - tagged := FactRepo(facts[i]) - if tagged == "" { - continue - } - for _, repo := range repos { - name := repo - if !strings.Contains(tagged, "/") { - name = path.Base(repo) - } - if strings.EqualFold(tagged, name) { - facts[i].rankBoost = taskRepoBoost - break - } - } - } - return facts -} - // mergeWithPrecedence deduplicates facts by slug, keeping the version from the // highest-precedence layer (personal > project > org > community). func (p *Primer) mergeWithPrecedence(facts []Fact) []Fact { @@ -289,8 +254,7 @@ func (p *Primer) mergeWithPrecedence(facts []Fact) []Fact { return result } -// applyPriority sorts facts by configured type priority, then by confidence -// plus any task-repo rank boost (boostTaskRepos). +// applyPriority sorts facts by configured type priority, then by confidence. func (p *Primer) applyPriority(facts []Fact) []Fact { priorityMap := make(map[string]int) for i, typ := range p.config.Priority { @@ -310,7 +274,7 @@ func (p *Primer) applyPriority(facts []Fact) []Fact { if pi != pj { return pi < pj } - return facts[i].Confidence+facts[i].rankBoost > facts[j].Confidence+facts[j].rankBoost + return facts[i].Confidence > facts[j].Confidence }) return facts diff --git a/src/pkg/knowledge/primer_task_repo_test.go b/src/pkg/knowledge/primer_task_repo_test.go deleted file mode 100644 index 6f8b7b62e1..0000000000 --- a/src/pkg/knowledge/primer_task_repo_test.go +++ /dev/null @@ -1,37 +0,0 @@ -package knowledge - -import "testing" - -// The task-repo boost orders facts within a type and never across types, and -// it leaves the confidence a kick shows alone. -func TestBoostTaskRepos_OrdersWithinTypeOnly(t *testing.T) { - p := &Primer{config: PrimerConfig{Priority: []string{"gotcha", "pattern"}}} - facts := []Fact{ - {Slug: "other-gotcha", Type: FactGotcha, Confidence: 0.50, Tags: []string{"repo:org/other"}}, - {Slug: "task-gotcha", Type: FactGotcha, Confidence: 0.45, Tags: []string{"repo:Org/Task"}}, - {Slug: "task-pattern", Type: FactPattern, Confidence: 0.90, Tags: []string{"repo:org/task"}}, - {Slug: "task-codemap", Type: FactPattern, Confidence: 0.85, Tags: []string{"repo:task"}}, - {Slug: "untagged", Type: FactPattern, Confidence: 0.92}, - } - sorted := p.applyPriority(boostTaskRepos(facts, []string{"org/task"})) - - want := []string{"task-gotcha", "other-gotcha", "task-pattern", "task-codemap", "untagged"} - for i, slug := range want { - if sorted[i].Slug != slug { - t.Fatalf("position %d = %s, want %s (order %v)", i, sorted[i].Slug, slug, slugsOf(sorted)) - } - } - for _, f := range sorted { - if f.Slug == "task-gotcha" && f.Confidence != 0.45 { - t.Errorf("boost changed the shown confidence to %.2f", f.Confidence) - } - } -} - -func slugsOf(facts []Fact) []string { - out := make([]string, len(facts)) - for i, f := range facts { - out[i] = f.Slug - } - return out -} diff --git a/src/pkg/knowledge/scope.go b/src/pkg/knowledge/scope.go index 62a64cd2f3..048e501162 100644 --- a/src/pkg/knowledge/scope.go +++ b/src/pkg/knowledge/scope.go @@ -31,22 +31,15 @@ func (s *FactScope) IsZero() bool { } // KickContext is what the primer knows about the work a kick is for. The -// scheduler fills Lane, Labels and Repos from the lane name and the primed -// issues; Paths is filled only by callers that know which files are being -// touched. +// scheduler fills Lane and Labels from the lane name and the primed issues; +// Paths is filled only by callers that know which files are being touched. type KickContext struct { Lane string Labels []string Paths []string - // Repos are the primed issues' repositories as "/". They are - // not a scope dimension (Admits ignores them) and they select nothing: - // a fact tagged repo: only ranks ahead of an otherwise equal - // fact of the same type about another repo (boostTaskRepos). - Repos []string } -// IsZero reports whether the context carries nothing a fact's scope can -// match on. Repos are not a scope dimension, so they do not count. +// IsZero reports whether the context carries nothing to match on. func (kc KickContext) IsZero() bool { return kc.Lane == "" && len(kc.Labels) == 0 && len(kc.Paths) == 0 } diff --git a/src/pkg/knowledge/types.go b/src/pkg/knowledge/types.go index 90ee38eadf..24371c0b1d 100644 --- a/src/pkg/knowledge/types.go +++ b/src/pkg/knowledge/types.go @@ -299,11 +299,6 @@ type Fact struct { Updated time.Time `json:"-"` BodySize int `json:"-"` Origin string `json:"-"` - - // rankBoost is added to Confidence when PrimeForKick orders facts, for a - // fact about the kick's own repository (boostTaskRepos). It changes the - // order only, never the confidence a kick shows. - rankBoost float64 } // Source tracks where a fact was extracted from. diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index e9749be59e..541b5e3911 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -5,15 +5,18 @@ import ( "fmt" "log/slog" "regexp" + "slices" "strings" "github.com/hivecommons/hive/crux/agentsmd" "github.com/hivecommons/hive/crux/skillreg" "github.com/hivecommons/hive/pkg/authorkind" + "github.com/hivecommons/hive/pkg/claims" "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/github" "github.com/hivecommons/hive/pkg/issueshape" "github.com/hivecommons/hive/pkg/knowledge" + "github.com/hivecommons/hive/pkg/stagelabels" ) const maxIssuesToPrime = 5 @@ -398,7 +401,19 @@ func (s *Scheduler) renderKnowledge(primer *knowledge.Primer, cfg *config.Config } scope = &agentScope } - primed := primer.PrimeForKick(context.Background(), scope, kickContextFor(cfg, agentName, issues), keywords) + kc := kickContextFor(cfg, agentName, issues) + primed := primer.PrimeForKick(context.Background(), scope, kc, keywords) + // The issue's own terms matched nothing: search again with the terms + // earlier releases used, so leaving the hive's routing words out never + // costs a kick the section it got before. + if len(primed.Facts) == 0 { + if legacy := legacyKeywords(issues); len(legacy) > 0 && !slices.Equal(legacy, keywords) { + s.logger.Info("knowledge primer: no entry matched the issue terms, retrying with the full query", + "sample", keywordSample(keywords), "full_sample", keywordSample(legacy)) + keywords = legacy + primed = primer.PrimeForKick(context.Background(), scope, kc, keywords) + } + } result, omitted := primed.Render() inj := knowledgeInjection{ Section: result, @@ -558,17 +573,11 @@ func (s *Scheduler) KickSummary(agentName string) (KickSummary, bool) { // against (#17045): the base lane name (a replica resolves to the agent it // replicates) and the union of the primed issues' labels. File paths are not // known on the kick path, so entries scoped by paths alone wait for a caller -// that has them. It also carries the issues' repositories, which rank entries -// tagged with them ahead of other repos' entries but admit nothing. +// that has them. func kickContextFor(cfg *config.Config, agentName string, issues []github.Issue) knowledge.KickContext { kc := knowledge.KickContext{Lane: cfg.BaseAgentName(agentName)} seen := make(map[string]bool) - seenRepo := make(map[string]bool) for _, issue := range issues { - if repo := strings.ToLower(strings.TrimSpace(issue.Repo)); strings.Contains(repo, "/") && !seenRepo[repo] { - seenRepo[repo] = true - kc.Repos = append(kc.Repos, repo) - } for _, label := range issue.Labels { lower := strings.ToLower(strings.TrimSpace(label)) if lower == "" || seen[lower] { @@ -581,9 +590,9 @@ func kickContextFor(cfg *config.Config, agentName string, issues []github.Issue) return kc } -// extractKeywords pulls searchable terms from issue labels and titles, for a -// hive with no agents of its own configured beyond the built-in lanes; see -// extractKeywordsFor. +// extractKeywords is extractKeywordsFor with no hive config: the built-in +// lanes and origin sources are the only filers, and the default never-claim +// labels apply. func extractKeywords(issues []github.Issue) []string { return extractKeywordsFor(nil, issues) } @@ -594,40 +603,20 @@ func extractKeywords(issues []github.Issue) []string { // // What the hive itself puts on an item is dropped, because it says where the // item sits in the hive, not what it is about: its routing labels -// (isNoiseLabel), its complexity tier, the "[]" filer tag on a title it -// filed, and the "Review backlog" stem. On utah-packages#879 those made up +// (isRoutingLabel), its complexity tier, the "[]" filer tag on a title +// it filed, and the "Review backlog" stem. On utah-packages#879 those made up // most of the query (stage/010-actionable, agent/reviewer, medium, "reviewer -// review backlog") and pulled in review notes from unrelated repos. -// -// When nothing is left, the query falls back to the terms earlier releases -// used (legacyKeywords), so no kick loses its knowledge section to the filter. -// The issues' repositories are not search terms; they ride in the kick -// context and rank the repo's own entries first (kickContextFor). +// review backlog") and pulled in review notes from unrelated repos. When +// nothing is left, the terms earlier releases used are returned instead +// (legacyKeywords); renderKnowledge also falls back to them when these terms +// match no entry. func extractKeywordsFor(cfg *config.Config, issues []github.Issue) []string { - seen := make(map[string]bool) - var keywords []string - add := func(word string) { - if !seen[word] { - keywords = append(keywords, word) - seen[word] = true - } - } - - for _, issue := range issues { - for _, label := range issue.Labels { - lower := strings.ToLower(label) - if !isNoiseLabel(lower) { - add(lower) - } - } - - for _, word := range splitTitleWords(searchableTitle(cfg, issue.Title)) { - if !isNoiseWord(word) { - add(word) - } - } - } - + filers := hiveFilers(cfg) + neverClaim := neverClaimLabels(cfg) + keywords := collectKeywords(issues, + func(label string) bool { return !isRoutingLabel(label) && !neverClaim[label] }, + false, + func(title string) string { return searchableTitle(filers, title) }) if len(keywords) == 0 { return legacyKeywords(issues) } @@ -635,33 +624,41 @@ func extractKeywordsFor(cfg *config.Config, issues []github.Issue) []string { } // legacyKeywords is the query earlier releases built: every label outside -// noiseLabels, the complexity tier, and every title word. It is the fallback -// for an issue whose own words are all hive routing. +// noiseLabels, the complexity tier, and every title word. func legacyKeywords(issues []github.Issue) []string { + return collectKeywords(issues, + func(label string) bool { return !isNoiseLabel(label) }, + true, + func(title string) string { return title }) +} + +// collectKeywords is the shared walk: each issue's kept labels, then its tier +// when withTier is set, then the words of title(issue.Title), lower-cased, +// noise words dropped and each term once. +func collectKeywords(issues []github.Issue, keepLabel func(string) bool, withTier bool, title func(string) string) []string { seen := make(map[string]bool) var keywords []string + add := func(word string) { + if !seen[word] { + keywords = append(keywords, word) + seen[word] = true + } + } for _, issue := range issues { for _, label := range issue.Labels { - lower := strings.ToLower(label) - if !seen[lower] && !noiseLabels[lower] { - keywords = append(keywords, lower) - seen[lower] = true + if lower := strings.ToLower(label); keepLabel(lower) { + add(lower) } } - if issue.ComplexityTier != "" { - tier := strings.ToLower(issue.ComplexityTier) - if !seen[tier] { - keywords = append(keywords, tier) - seen[tier] = true - } + if withTier && issue.ComplexityTier != "" { + add(strings.ToLower(issue.ComplexityTier)) } - for _, word := range splitTitleWords(issue.Title) { - if !seen[word] && !isNoiseWord(word) { - keywords = append(keywords, word) - seen[word] = true + for _, word := range splitTitleWords(title(issue.Title)) { + if !isNoiseWord(word) { + add(word) } } } @@ -670,49 +667,62 @@ func legacyKeywords(issues []github.Issue) []string { } // reviewBacklogTitleRE matches the stem the hive puts on its review backlog -// items, "Review backlog (): " (pkg/github -// reviewBacklogIssueTitle). -var reviewBacklogTitleRE = regexp.MustCompile(`^Review backlog \(([^)]+)\):\s*`) +// items, "[reviewer] Review backlog (): ", with or +// without the filer tag (the same shape as pkg/github's +// reviewBacklogTitleCategoryRE). +var reviewBacklogTitleRE = regexp.MustCompile(`^(?:\[[^\]\s]+\]\s*)?Review backlog \(([^)]+)\):\s*`) // searchableTitle is the part of an issue title that says what the issue is -// about. A leading "[]" tag is dropped only when it names a hive filer -// (isHiveFiler): any lowercase word in brackets has the filer shape, and a -// person's "[nvidia] driver fails to build" keeps "nvidia". A review backlog -// stem is cut down to its perspective, which names the kind of finding -// ("security", "style"); the words "review backlog" match every review-related -// entry in the vault whatever the repo. -func searchableTitle(cfg *config.Config, title string) string { +// about. A review backlog title is cut down to its perspective, which names +// the kind of finding ("security", "style"), and the finding; the words +// "review backlog" match every review-related entry in the vault whatever the +// repo. Otherwise a leading "[]" is dropped only when it names a hive +// filer (hiveFilers): any lowercase word in brackets has the filer shape, and +// a person's "[nvidia] driver fails to build" keeps "nvidia". +func searchableTitle(filers map[string]bool, title string) string { title = strings.TrimSpace(title) - if tag := issueshape.AgentPrefix(title); tag != "" && isHiveFiler(cfg, tag) { - title = issueshape.StripAgentPrefix(title) - } if m := reviewBacklogTitleRE.FindStringSubmatch(title); m != nil { - title = m[1] + " " + title[len(m[0]):] + return m[1] + " " + title[len(m[0]):] + } + if tag := issueshape.AgentPrefix(title); tag != "" && filers[strings.ToLower(tag)] { + return issueshape.StripAgentPrefix(title) } return title } -// isHiveFiler reports whether tag names something that files issues for the -// hive: a built-in lane (scanner, reviewer, …), another origin source -// (selfreport, governor, …) or an agent configured on this hive. -func isHiveFiler(cfg *config.Config, tag string) bool { - tag = strings.ToLower(strings.TrimSpace(tag)) - if config.IsKnownOriginLane(tag) { - return true +// hiveFilers is the set of names that file issues for the hive: the built-in +// lanes (scanner, reviewer, …), the other origin sources (selfreport, +// governor, …) and the agents configured on this hive. +func hiveFilers(cfg *config.Config) map[string]bool { + filers := make(map[string]bool) + for _, lane := range config.KnownOriginLanes { + filers[lane] = true } for _, source := range config.KnownOriginSources() { - if tag == source { - return true - } + filers[source] = true } if cfg != nil { for name := range cfg.Agents { - if strings.EqualFold(name, tag) || strings.EqualFold(cfg.BaseAgentName(name), tag) { - return true - } + filers[strings.ToLower(name)] = true + filers[strings.ToLower(cfg.BaseAgentName(name))] = true } } - return false + return filers +} + +// neverClaimLabels is the hive's never-claim set (claims.never_claim_labels, +// default "epic"), lower-cased. Those labels mark trackers the hive will not +// work, so like routing labels they say nothing about the work. +func neverClaimLabels(cfg *config.Config) map[string]bool { + labels := claims.DefaultNeverClaimLabels + if cfg != nil { + labels = cfg.Governor.Claims.EffectiveNeverClaimLabels() + } + out := make(map[string]bool, len(labels)) + for _, l := range labels { + out[strings.ToLower(strings.TrimSpace(l))] = true + } + return out } // splitTitleWords extracts lowercase words from an issue title, dropping @@ -767,39 +777,45 @@ var noiseLabels = map[string]bool{ "hold": true, } -// noiseLabelPrefixes are the label families the hive and its review bots use -// to route and gate work: where an item sits in the pipeline (stage/, needs-), -// which lane holds or filed it (agent/ and origin/, see isNoiseLabel; -// hive/claimed-by-…; hive: churn-triaged), a hive's hold (hive-pause/), -// the author class (author/human, …), and review or merge state. They say -// nothing about what the issue is about, and they are on most items, so as -// search terms they match the same review and scanning entries for every task. -var noiseLabelPrefixes = []string{ - "stage/", "hive/", "hive:", github.HiveHoldLabelPrefix, authorkind.Prefix, - "triage/", "size/", "lifecycle/", "do-not-merge/", "needs-", "dco-signoff", - "sentinel-", -} - -// noiseControlLabels are single hive or review-bot labels outside those -// families. "epic" is the hive's default never-claim marker for trackers -// (claims.DefaultNeverClaimLabels); "claimed" is its claim marker. -var noiseControlLabels = map[string]bool{ +func isNoiseLabel(label string) bool { + return noiseLabels[label] +} + +// routingLabelPrefixes are the label families the hive, Prow and the review +// bots use to route and gate work: where an item sits in the pipeline +// (stage/, needs-), who holds or filed it (agent/ and origin/, see +// isRoutingLabel; hive/claimed-by-…; hive: churn-triaged), a hive's hold +// (hive-pause/), the author class (author/human, …), and review, test or +// merge state (tide/, do-not-merge, release-note, cncf-cla:). They say nothing +// about what the issue is about, and they are on most items, so as search +// terms they match the same review and scanning entries for every task. +var routingLabelPrefixes = []string{ + stagelabels.Prefix, "hive/", "hive:", github.HiveHoldLabelPrefix, authorkind.Prefix, + "triage/", "size/", "lifecycle/", "do-not-merge", "needs-", "dco-signoff", + "sentinel-", "tide/", "release-note", "cncf-cla:", +} + +// routingLabels are single hive, Prow or review-bot labels outside those +// families. +var routingLabels = map[string]bool{ "approved-direction": true, "hive-review": true, "lgtm": true, "approved": true, "claimed": true, - "epic": true, + "ok-to-test": true, } -func isNoiseLabel(label string) bool { - if noiseLabels[label] || noiseControlLabels[label] { +// isRoutingLabel reports whether a lower-cased label is one the hive's search +// leaves out: noiseLabels, and every routing label above. +func isRoutingLabel(label string) bool { + if noiseLabels[label] || routingLabels[label] { return true } if config.IsAgentLaneLabel(label) || config.IsOriginLabel(label) { return true } - for _, prefix := range noiseLabelPrefixes { + for _, prefix := range routingLabelPrefixes { if strings.HasPrefix(label, prefix) { return true } diff --git a/src/pkg/scheduler/kick_priming_query_test.go b/src/pkg/scheduler/kick_priming_query_test.go index deeee152c1..d6fa09b950 100644 --- a/src/pkg/scheduler/kick_priming_query_test.go +++ b/src/pkg/scheduler/kick_priming_query_test.go @@ -1,11 +1,14 @@ package scheduler import ( - "context" + "encoding/json" "log/slog" + "net/http" + "net/http/httptest" "os" - "path/filepath" "reflect" + "strings" + "sync" "testing" "github.com/hivecommons/hive/pkg/config" @@ -26,7 +29,8 @@ func TestExtractKeywords_DropsHiveRouting(t *testing.T) { Title: "[reviewer] Review backlog (style): spec file mixes tabs and spaces", ComplexityTier: "Medium", Labels: []string{"stage/010-actionable", "agent/reviewer", "kind/cleanup", "approved-direction", - "hive/claimed-by-scanner", "needs-triage", "epic", "claimed", "author/human", "hive-pause/h1", "origin/governor"}, + "hive/claimed-by-scanner", "needs-triage", "epic", "claimed", "author/human", "hive-pause/h1", + "origin/governor", "ok-to-test", "tide/merge-method-squash", "do-not-merge"}, } got := extractKeywords([]github.Issue{issue}) want := []string{"kind/cleanup", "style", "spec", "file", "mixes", "tabs", "spaces"} @@ -35,9 +39,8 @@ func TestExtractKeywords_DropsHiveRouting(t *testing.T) { } } -// An issue whose every term is hive routing falls back to the query earlier -// releases built, so the filter never leaves a kick with no knowledge section -// it used to get. +// An issue whose every term is hive routing gets the query earlier releases +// built, so the filter never leaves it with nothing to search on. func TestExtractKeywords_AllRoutingFallsBackToLegacyQuery(t *testing.T) { issue := github.Issue{ Repo: "projectbluefin/utah", @@ -50,16 +53,28 @@ func TestExtractKeywords_AllRoutingFallsBackToLegacyQuery(t *testing.T) { if !reflect.DeepEqual(got, want) { t.Fatalf("keywords = %q\nwant the legacy query %q", got, want) } - if !reflect.DeepEqual(got, legacyKeywords([]github.Issue{issue})) { - t.Fatal("the fallback is not the legacy query") +} + +// A hive that configures its own never-claim labels gets those left out too, +// and the default "epic" then counts as an ordinary word. +func TestExtractKeywords_ConfiguredNeverClaimLabels(t *testing.T) { + cfg := &config.Config{} + cfg.Governor.Claims.NeverClaimLabels = []string{"Tracker"} + issue := github.Issue{Repo: "org/repo", Number: 3, Title: "Sidebar anchors drift", Labels: []string{"tracker", "epic"}} + got := extractKeywordsFor(cfg, []github.Issue{issue}) + want := []string{"epic", "sidebar", "anchors", "drift"} + if !reflect.DeepEqual(got, want) { + t.Fatalf("keywords = %q, want %q", got, want) } } func TestSearchableTitle(t *testing.T) { cfg := &config.Config{} cfg.Agents = map[string]config.AgentConfig{"packager": {}} + filers := hiveFilers(cfg) for title, want := range map[string]string{ "[reviewer] Review backlog (security): token in log line": "security token in log line", + "[someone] Review backlog (style): long line": "style long line", "Review backlog (style): long line": "style long line", "[scanner] Sidebar anchors drift": "Sidebar anchors drift", "[selfreport] Agent pane froze": "Agent pane froze", @@ -68,84 +83,71 @@ func TestSearchableTitle(t *testing.T) { "[ACMM L0] Add a CONTRIBUTING file": "[ACMM L0] Add a CONTRIBUTING file", "Review the backlog of stale PRs": "Review the backlog of stale PRs", } { - if got := searchableTitle(cfg, title); got != want { + if got := searchableTitle(filers, title); got != want { t.Errorf("searchableTitle(%q) = %q, want %q", title, got, want) } } - if got := searchableTitle(nil, "[packager] Bump the spec"); got != "[packager] Bump the spec" { + if got := searchableTitle(hiveFilers(nil), "[packager] Bump the spec"); got != "[packager] Bump the spec" { t.Errorf("an unconfigured agent name was stripped as a filer: %q", got) } } -func TestIsNoiseLabel_HiveRoutingFamilies(t *testing.T) { - for _, l := range []string{"stage/010-actionable", "stage/stalled", "agent/reviewer", "hive/claimed-by-scanner", "hive: churn-triaged", - "origin/governor", "triage/needs-information", "size/l", "needs-human", "do-not-merge/hold", "dco-signoff: yes", - "sentinel-alert", "approved-direction", "hive-review", "lgtm", "claimed", "epic", "author/human", "hive-pause/h1"} { - if !isNoiseLabel(l) { - t.Errorf("%q is a hive routing label and should not be a search term", l) +func TestIsRoutingLabel(t *testing.T) { + for _, l := range []string{"kind/bug", "triage/accepted", "stage/010-actionable", "stage/stalled", "agent/reviewer", + "hive/claimed-by-scanner", "hive: churn-triaged", "origin/governor", "triage/needs-information", "size/l", + "needs-human", "do-not-merge", "do-not-merge/hold", "dco-signoff: yes", "sentinel-alert", "approved-direction", + "hive-review", "lgtm", "approved", "claimed", "author/human", "hive-pause/h1", "ok-to-test", "needs-ok-to-test", + "tide/merge-method-squash", "release-note-none", "cncf-cla: yes"} { + if !isRoutingLabel(l) { + t.Errorf("%q is a routing label and should not be a search term", l) } } - for _, l := range []string{"kind/cleanup", "priority/high", "area/packaging", "rpm", "stagehand", "agentic", "authoring", "epics-tracker"} { - if isNoiseLabel(l) { + for _, l := range []string{"kind/cleanup", "priority/high", "area/packaging", "rpm", "stagehand", "agentic", "authoring", "epic"} { + if isRoutingLabel(l) { t.Errorf("%q describes the work and should stay a search term", l) } } } -// The task's repo ranks its own entries first within a type: of two entries -// that match the issue equally, the one tagged with the task's repo comes -// first, a code map tagged with the bare repo name counts, and the confidence -// the kick shows is not changed by the ranking. The repo admits nothing: an -// entry that shares no word with the issue stays out however it is tagged. -func TestKnowledgeKick_TaskRepoRanksItsEntriesFirst(t *testing.T) { - for _, tc := range []struct{ name, taskTag string }{ - {"org/name tag", "projectbluefin/utah-packages"}, - {"bare code-map tag", "utah-packages"}, - } { - t.Run(tc.name, func(t *testing.T) { - vault := t.TempDir() - entry := func(name, repo string) { - body := "---\ntitle: Packaging conventions\ntype: gotcha\nlayer: project\ntags: [repo:" + repo + ", packaging]\n---\n" + - "Spec files use spaces for indentation, never tabs.\n" - if err := os.WriteFile(filepath.Join(vault, name+".md"), []byte(body), 0o644); err != nil { - t.Fatal(err) - } - } - entry("other-repo", "projectbluefin/bluefin-lts") - entry("task-repo", tc.taskTag) - logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) - store, err := knowledge.NewFileStore(vault, "vault", logger) - if err != nil { - t.Fatal(err) - } - primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger) - primer.AddFileStore("vault", store, knowledge.LayerProject) +// The issue's own terms match nothing in the wiki, but the terms earlier +// releases used do: the kick still gets the section it got before, from a +// second search with the full query. +func TestPrimeKnowledge_NoHitFallsBackToLegacyQuery(t *testing.T) { + var ( + mu sync.Mutex + queries []string + ) + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + q := r.URL.Query().Get("q") + mu.Lock() + queries = append(queries, q) + mu.Unlock() + results := []map[string]interface{}{} + if strings.Contains(q, "ci-maintainer") { + results = append(results, map[string]interface{}{ + "slug": "ci-lane-notes", "title": "CI lane notes", "score": 0.9, + "type": "gotcha", "confidence": 0.9, "snippet": "LEGACY-HIT: rerun lint once before repairing.", + }) + } + w.Header().Set("Content-Type", "application/json") + _ = json.NewEncoder(w).Encode(map[string]interface{}{"total": len(results), "results": results}) + })) + defer srv.Close() - task := github.Issue{Repo: "projectbluefin/utah-packages", Number: 879, Title: "Spec file mixes tabs and spaces"} - kc := kickContextFor(guidanceScheduler(t, "").cfg, "scanner", []github.Issue{task}) - if !reflect.DeepEqual(kc.Repos, []string{"projectbluefin/utah-packages"}) { - t.Fatalf("kick context repos = %q", kc.Repos) - } - plain := primer.PrimeForKick(context.Background(), nil, knowledge.KickContext{}, extractKeywords([]github.Issue{task})) - primed := primer.PrimeForKick(context.Background(), nil, kc, extractKeywords([]github.Issue{task})) - if len(primed.Facts) != 2 || len(plain.Facts) != 2 { - t.Fatalf("primed %d / %d facts, want both entries", len(primed.Facts), len(plain.Facts)) - } - if primed.Facts[0].Slug != "task-repo" { - t.Fatalf("ranking = %s, %s; want the task repo's entry first", primed.Facts[0].Slug, primed.Facts[1].Slug) - } - for _, f := range primed.Facts { - for _, g := range plain.Facts { - if f.Slug == g.Slug && f.Confidence != g.Confidence { - t.Errorf("%s: confidence %.3f with the repo boost, %.3f without; the boost must not change it", f.Slug, f.Confidence, g.Confidence) - } - } - } + logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) + s := newScheduler() + s.SetPrimer(knowledge.NewPrimer([]knowledge.LayerConfig{{Type: knowledge.LayerProject, URL: srv.URL, Shared: true}}, + knowledge.PrimerConfig{MaxFacts: 25}, logger)) + issue := makeIssue("projectbluefin/utah", 12, "[ci-maintainer] Flaky lint job", "", 5, + []string{"agent/ci-maintainer", "stage/010-actionable"}, false) - unrelated := primer.PrimeForKick(context.Background(), nil, kc, []string{"kernel", "panic"}) - if len(unrelated.Facts) != 0 { - t.Fatalf("the repo tag alone admitted %d facts for an unrelated query", len(unrelated.Facts)) - } - }) + got := s.primeKnowledge("ci-maintainer", []github.Issue{issue}) + mu.Lock() + defer mu.Unlock() + if !strings.Contains(got, "LEGACY-HIT") { + t.Fatalf("the kick lost the section the full query finds:\n%s\nqueries: %q", got, queries) + } + if len(queries) != 2 || queries[0] != "flaky lint job" || !strings.Contains(queries[1], "agent/ci-maintainer") { + t.Fatalf("queries = %q, want the issue's terms first and the full query second", queries) } }