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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-knowledge-entry-scope.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Knowledge entries can carry a `scope:` frontmatter block (`paths`, `labels`, `lanes`); the kick primer surfaces a scoped entry only when the kick's lane, issue labels or known file paths match, so repository facts are injected on demand instead of on every kick (#17045).
38 changes: 38 additions & 0 deletions src/docs/knowledge-toc.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,44 @@ only unless `include_states` is set), and returns:
The dashboard Knowledge section has an **Effective knowledge** panel with an
agent picker that renders both lists and each exclusion reason.

### Entry scope (`scope:` frontmatter)

`knowledge.agent_scopes` says what an *agent* may see. An entry can also say
where *it* applies, with a `scope:` block in its frontmatter
(hivecommons/hive#17045):

```yaml
---
title: Editing src/scripts/ requires re-pinning TRUSTED_SCRIPTS_TREE
type: gotcha
layer: project
scope:
paths: [src/scripts/**, .github/scripts/integration-governance.cjs]
labels: [area/ci]
lanes: []
---
```

- `paths` are repo-relative globs (`**` matches any number of segments),
`labels` are issue labels and `lanes` are base agent names; `labels` and
`lanes` compare case-insensitively. Inline lists only — the frontmatter
parser is line-oriented and block lists (`- item`) inside `scope:` are
skipped.
- An entry **without** `scope:` behaves as before: keyword relevance plus the
agent's `knowledge.agent_scopes`.
- An entry **with** `scope:` is surfaced in a kick only when at least one
declared dimension matches the kick — its lane, a label on one of the primed
issues, or a file path the caller knows. Dimensions are OR-ed; a dimension the
kick cannot evaluate (file paths are not known on the kick path) simply does
not match. Related facts pulled in by graph expansion are gated the same way.
- The primer reports how many relevant entries the kick context excluded in the
`knowledge primed` log line (`scoped_out`) and in `PrimedKnowledge.ScopedOut`.

The full read (`GET /api/knowledge/entry/{id}`) returns the entry's `scope`
inside `fact`, so an operator can see why an entry does or does not reach a
kick. The agent-level filter (`agent_scopes`) applies first; the entry's own
scope can only narrow further.

### Prompt-size caps

- `limit` defaults to 50 and is clamped to 200.
Expand Down
31 changes: 31 additions & 0 deletions src/pkg/knowledge/filestore.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ type filePage struct {
Path string
ModTime time.Time
Embedding []float64
Scope *FactScope

// Lifecycle frontmatter (#11102); see resolveLifecycleState for defaults.
State LifecycleState
Expand Down Expand Up @@ -209,6 +210,9 @@ func (s *FileStore) reindex() {
page.State = parsed.state
page.Supersedes = parsed.supersedes
page.SupersededBy = parsed.supersededBy
if !parsed.scope.IsZero() {
page.Scope = parsed.scope
}
pages[slug] = page

return nil
Expand Down Expand Up @@ -496,6 +500,7 @@ type parsedObsidianFile struct {
state LifecycleState
supersedes string
supersededBy string
scope *FactScope
}

var wikilinkRe = regexp.MustCompile(`\[\[([^\]|]+)(?:\|[^\]]+)?\]\]`)
Expand Down Expand Up @@ -526,8 +531,33 @@ func parseObsidianFileDetailed(content string, fallbackTitle string) parsedObsid
frontmatter := content[4 : 4+endIdx]
parsed.body = strings.TrimSpace(content[4+endIdx+4:])

// The parser is line-oriented and trims indentation, so a nested
// `scope:` block is recognised by state: once "scope:" is seen, the
// keys paths/labels/lanes belong to it until the next unrelated key.
inScope := false
for _, line := range strings.Split(frontmatter, "\n") {
line = strings.TrimSpace(line)
if line == "scope:" {
inScope = true
if parsed.scope == nil {
parsed.scope = &FactScope{}
}
continue
}
if inScope {
if consumed := parsed.scope.setFromLine(line); consumed {
continue
}
if strings.HasPrefix(line, "- ") || line == "" {
// Block-list items are not supported inside scope:
// (documented); skip them rather than let them leak
// into tags.
continue
}
if strings.Contains(line, ":") {
inScope = false
}
}
if strings.HasPrefix(line, "title:") {
parsed.title = strings.TrimSpace(strings.TrimPrefix(line, "title:"))
parsed.title = strings.Trim(parsed.title, "\"'")
Expand Down Expand Up @@ -644,6 +674,7 @@ func (p filePage) effectiveLayer() LayerType {
// applyLifecycle copies the page's lifecycle and TOC metadata onto f, defaulting
// legacy pages without a recorded state to approved.
func (p filePage) applyLifecycle(f *Fact) {
f.Scope = p.Scope
f.Supersedes = p.Supersedes
f.SupersededBy = p.SupersededBy
f.State = resolveLifecycleState(p.State, p.Status, p.SupersededBy)
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/knowledge/knowledge_coverage_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -535,7 +535,7 @@ func TestPrimer_ExpandWithGraph(t *testing.T) {
p.SetGraphStore(gs)

facts := []Fact{{Slug: "seed", Title: "Seed Fact", Confidence: 0.9, Layer: LayerProject}}
expanded := p.expandWithGraph(facts, nil)
expanded := p.expandWithGraph(facts, nil, KickContext{})
if len(expanded) < 2 {
t.Fatalf("expected graph expansion to add related fact, got %d facts", len(expanded))
}
Expand All @@ -553,7 +553,7 @@ func TestPrimer_ExpandWithGraph(t *testing.T) {
func TestPrimer_ExpandWithGraph_NoGraph(t *testing.T) {
p := NewPrimer(nil, PrimerConfig{MaxFacts: 25}, covLogger())
facts := []Fact{{Slug: "a"}}
if got := p.expandWithGraph(facts, nil); len(got) != 1 {
if got := p.expandWithGraph(facts, nil, KickContext{}); len(got) != 1 {
t.Errorf("expected passthrough without graph, got %d", len(got))
}
}
Expand Down
26 changes: 22 additions & 4 deletions src/pkg/knowledge/primer.go
Original file line number Diff line number Diff line change
Expand Up @@ -97,9 +97,20 @@ func (p *Primer) Prime(ctx context.Context, filePaths []string, keywords []strin
// applied on top of the primer's lifecycle filter, so it can only narrow what
// the agent is shown, and graph expansion never pulls in an out-of-scope fact.
func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []string, keywords []string) *PrimedKnowledge {
return p.PrimeForKick(ctx, scope, KickContext{Paths: filePaths}, keywords)
}

// PrimeForKick is PrimeScoped with the kick's context (#17045): the lane, the
// labels of the issues being primed and, when the caller knows them, the file
// paths being touched. Facts that carry a `scope:` are kept only when the
// context matches one of its dimensions (FactScope.Admits); unscoped facts are
// selected by relevance exactly as before. kc.Paths also feed the search query,
// as filePaths did in PrimeScoped. The count of relevant facts the context
// excluded is reported in PrimedKnowledge.ScopedOut.
func (p *Primer) PrimeForKick(ctx context.Context, scope *TOCScope, kc KickContext, keywords []string) *PrimedKnowledge {
start := time.Now()

query := buildQuery(filePaths, keywords)
query := buildQuery(kc.Paths, keywords)
if query == "" {
return &PrimedKnowledge{}
}
Expand Down Expand Up @@ -145,18 +156,20 @@ func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []s
if scope != nil {
merged = scope.Filter(merged)
}
merged, scopedOut := FilterByKickContext(merged, kc)
reranked := p.rerankFisherRao(query, merged)
prioritized := p.applyPriority(reranked)

if len(prioritized) > p.config.MaxFacts {
prioritized = prioritized[:p.config.MaxFacts]
}

prioritized = p.expandWithGraph(prioritized, scope)
prioritized = p.expandWithGraph(prioritized, scope, kc)

elapsed := time.Since(start).Milliseconds()
p.logger.Info("knowledge primed",
"facts", len(prioritized),
"scoped_out", scopedOut,
"http_layers", len(p.layers),
"file_stores", len(p.fileStores),
"graph", p.graphStore != nil,
Expand All @@ -182,6 +195,7 @@ func (p *Primer) PrimeScoped(ctx context.Context, scope *TOCScope, filePaths []s
Hints: hints,
QueryTime: elapsed,
MaxBytes: p.config.MaxBytes,
ScopedOut: scopedOut,
}
}

Expand Down Expand Up @@ -275,8 +289,9 @@ const graphExpansionConfidenceDecay = 0.8

// expandWithGraph performs one-hop traversal from each primed fact's slug,
// pulling in related facts that aren't already in the result set. A non-nil
// scope excludes related facts outside it.
func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope) []Fact {
// scope excludes related facts outside it, and a related fact's own `scope:`
// must admit the kick context.
func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope, kc KickContext) []Fact {
if p.graphStore == nil || len(facts) == 0 {
return facts
}
Expand Down Expand Up @@ -308,6 +323,9 @@ func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope) []Fact {
if scope != nil && !scope.InScope(*relFact) {
break
}
if !relFact.Scope.Admits(kc) {
break
}
relFact.Confidence *= graphExpansionConfidenceDecay
expanded = append(expanded, *relFact)
break
Expand Down
168 changes: 168 additions & 0 deletions src/pkg/knowledge/scope.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
package knowledge

import (
"path"
"strings"
)

// FactScope says where a fact applies (hivecommons/hive#17045). It is the
// frontmatter `scope:` block of a knowledge entry:
//
// scope:
// paths: [src/scripts/**, .github/scripts/integration-governance.cjs]
// labels: [area/ci]
// lanes: [developer, reviewer]
//
// Each dimension is a list; an empty list places no constraint on that
// dimension. A fact with no scope at all applies everywhere and is selected by
// relevance alone, exactly as before scopes existed.
type FactScope struct {
// Paths are repo-relative globs; "**" matches any number of segments.
Paths []string `json:"paths,omitempty"`
// Labels are issue labels, compared case-insensitively.
Labels []string `json:"labels,omitempty"`
// Lanes are base agent / lane names, compared case-insensitively.
Lanes []string `json:"lanes,omitempty"`
}

// IsZero reports whether the scope constrains nothing.
func (s *FactScope) IsZero() bool {
return s == nil || (len(s.Paths) == 0 && len(s.Labels) == 0 && len(s.Lanes) == 0)
}

// 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.
type KickContext struct {
Lane string
Labels []string
Paths []string
}

// 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
}

// Admits reports whether a fact carrying scope s may be shown for kc. An
// unscoped fact is always admitted. A scoped fact is admitted when at least one
// declared dimension matches — the dimensions are OR-ed, so an entry scoped to
// both a path glob and a label surfaces for either trigger. A declared
// dimension the context knows nothing about (no paths at kick time, say) simply
// cannot match; it does not admit by default, because the point of a scope is
// that the fact is not paid for on every kick.
func (s *FactScope) Admits(kc KickContext) bool {
if s.IsZero() {
return true
}
if kc.Lane != "" && containsFold(s.Lanes, kc.Lane) {
return true
}
for _, l := range kc.Labels {
if containsFold(s.Labels, l) {
return true
}
}
for _, p := range kc.Paths {
for _, pattern := range s.Paths {
if scopeGlobMatch(pattern, p) {
return true
}
}
}
return false
}

// FilterByKickContext drops facts whose scope does not admit kc and reports how
// many it dropped. Unscoped facts pass unchanged; a zero context drops every
// scoped fact.
func FilterByKickContext(facts []Fact, kc KickContext) ([]Fact, int) {
kept := facts[:0:0]
dropped := 0
for _, f := range facts {
if f.Scope.Admits(kc) {
kept = append(kept, f)
continue
}
dropped++
}
return kept, dropped
}

// scopeGlobMatch matches a repo-relative path against a glob whose segments
// follow path.Match, with "**" matching zero or more whole segments. Both sides
// are normalised to forward slashes without a leading "./".
func scopeGlobMatch(pattern, p string) bool {
pattern = normaliseScopePath(pattern)
p = normaliseScopePath(p)
if pattern == "" || p == "" {
return false
}
return matchSegments(strings.Split(pattern, "/"), strings.Split(p, "/"))
}

func normaliseScopePath(s string) string {
s = strings.ReplaceAll(strings.TrimSpace(s), "\\", "/")
s = strings.TrimPrefix(s, "./")
return strings.Trim(s, "/")
}

func matchSegments(pattern, segs []string) bool {
for len(pattern) > 0 {
if pattern[0] == "**" {
// "**" at the end matches whatever remains, including nothing.
if len(pattern) == 1 {
return true
}
for i := 0; i <= len(segs); i++ {
if matchSegments(pattern[1:], segs[i:]) {
return true
}
}
return false
}
if len(segs) == 0 {
return false
}
if ok, err := path.Match(pattern[0], segs[0]); err != nil || !ok {
return false
}
pattern, segs = pattern[1:], segs[1:]
}
return len(segs) == 0
}

// parseScopeList parses the inline-list value of one scope key ("[a, b]" or a
// bare "a, b"); entries are trimmed and unquoted, empties dropped.
func parseScopeList(value string) []string {
value = strings.TrimSpace(value)
value = strings.TrimSuffix(strings.TrimPrefix(value, "["), "]")
var out []string
for _, item := range strings.Split(value, ",") {
item = strings.Trim(strings.TrimSpace(item), "\"'")
if item != "" {
out = append(out, item)
}
}
return out
}

// setFromLine applies one trimmed frontmatter line inside a `scope:` block and
// reports whether the line was a scope key.
func (s *FactScope) setFromLine(line string) bool {
key, value, ok := strings.Cut(line, ":")
if !ok {
return false
}
switch strings.TrimSpace(key) {
case "paths":
s.Paths = parseScopeList(value)
case "labels":
s.Labels = parseScopeList(value)
case "lanes":
s.Lanes = parseScopeList(value)
default:
return false
}
return true
}
Loading
Loading