Skip to content

✨ knowledge: scope block on entries and a kick-context filter in the Primer - #17060

Merged
clubanderson merged 2 commits into
v5from
knowledge-scope-filter
Nov 7, 2026
Merged

clubanderson merged 2 commits into
v5from
knowledge-scope-filter

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Fixes #17045 — phase 2 of #17043 (RFC: AGENTS.md carries tone only; knowledge becomes scoped skills surfaced on demand). Proposed by @gregoryhunt at the 2026-11-05 community meeting; owner Andy (@clubanderson).

What

  • scope: frontmatter block on knowledge entries, parsed by FileStore (parseObsidianFileDetailed) into a new Fact.Scope *FactScope{Paths, Labels, Lanes} (json:"scope,omitempty", so existing payloads are byte-identical). Inline lists only; block-list items inside scope: are skipped rather than leaking into tags. All-empty scope collapses to nil.
  • Primer.PrimeForKick(ctx, scope, KickContext{Lane, Labels, Paths}, keywords). After the lifecycle and agent_scopes filters, FilterByKickContext keeps a scoped fact only when at least one declared dimension matches the kick (OR across dimensions; ** globs for paths; case-insensitive labels/lanes). Unscoped facts are untouched. Graph-expanded neighbours are gated the same way. PrimeScoped is unchanged in signature and now delegates with Paths: filePaths.
  • Scheduler: primeKnowledge passes kickContextFor(cfg, agent, issues) — the base lane name (replicas resolve to their base) and the de-duplicated, lower-cased union of the primed issues' labels. Paths stay empty on the kick path (nothing there knows which files an agent will touch — that is the mid-task advisor, tracked separately).
  • Observability: PrimedKnowledge.ScopedOut and scoped_out on the existing knowledge primed log line.
  • Docs: src/docs/knowledge-toc.md → "Entry scope (scope: frontmatter)". Entry format and the entries themselves are in 🌱 AGENTS.md: keep tone and workflow rules; move repository facts into scoped knowledge entries #17051.
  • Cap: unchanged, knowledge.primer.max_bytes (default 4096) already exists; no second knob added.

Tests (table-driven, no time.Sleep)

  • scope_test.go: glob semantics; Admits (nil/empty scope, each dimension, OR, unevaluable dimension); FilterByKickContext; frontmatter parsing (inline lists, keys after the block still parsed, all-empty → nil, block items do not leak into tags, scope keys outside a block ignored); end-to-end PrimeForKick against a temp FileStore (scoped entry hidden without context, admitted by label or path, ScopedOut counts, PrimeScoped file paths double as kick paths).
  • kick_priming_scope_test.go: kickContextFor lane/replica/labels/nil-config.

Semantics worth a look

A declared dimension the kick cannot evaluate does not admit by default — a paths-only entry is never injected at kick time today. That is deliberate (the point of a scope is not paying for the fact on every kick); such entries are lookup targets for a CLI agent reading the directory, and become kick-injectable once a caller supplies paths.

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 7, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

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

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

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

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

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

PR Title Relation Files
#17079 ✨ knowledge: prime an agent's own drafts when agent_scopes.include_states lists draft CONFLICT src/pkg/knowledge/filestore.go

@hivecommons-hive

hivecommons-hive Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

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

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

  • the branch conflicts with the base and needs a rebase

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

…Primer

A knowledge entry can now say where it applies with a frontmatter scope:
block (paths, labels, lanes). FileStore parses it into Fact.Scope;
Primer.PrimeForKick takes the kick's lane, issue labels and known file
paths and keeps a scoped fact only when one dimension matches (OR), both
in the ranked set and in graph expansion. Unscoped facts are unchanged.
The scheduler passes the base lane name and the primed issues' labels;
paths stay empty on the kick path. The count excluded is reported as
PrimedKnowledge.ScopedOut and in the "knowledge primed" log line.

Proposed by @gregoryhunt at the 2026-11-05 community meeting.

Fixes #17045
Part of #17043

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@clubanderson
clubanderson force-pushed the knowledge-scope-filter branch from f54b598 to 18df130 Compare November 7, 2026 19:44
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 7, 2026
@clubanderson
clubanderson merged commit 0485b71 into v5 Nov 7, 2026
80 of 81 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the knowledge-scope-filter branch November 7, 2026 19:52
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

One verified gap from the rebase onto #17068, otherwise the scope filter reads correctly.

Lane-/label-scoped entries never surface through the mid-task advisor. knowledgeAdviser.Advise (src/cmd/hive/knowledge_adviser.go:87 at this head) calls primer.PrimeScoped(ctx, agentScope, paths, scope.Keywords), and PrimeScoped wraps that as KickContext{Paths: filePaths} (src/pkg/knowledge/primer.go:100) — no Lane, no Labels. FactScope.Admits (src/pkg/knowledge/scope.go) then only matches on kc.Paths, so an entry with scope: {lanes: [reviewer]} is scoped out for the reviewer agent mid-task, and labels:-scoped entries likewise. That is the inverse of what #17068 merged to do ("surface scoped knowledge mid-task"), and it is silent apart from the scoped_out counter. Advise already has agent, so the fix is small: build the context explicitly, e.g. primer.PrimeForKick(ctx, agentScope, knowledge.KickContext{Lane: cfg.BaseAgentName(agent), Paths: paths}, scope.Keywords). Labels aren't available in crux.KnowledgeScope, so that dimension staying unevaluable there is fine as long as the doc says so (the knowledge-toc.md paragraph currently only mentions paths being unknown on the kick path).

Checked and fine:

  • Admits returns true for an unscoped fact (IsZero), and dimensions are OR-ed exactly as knowledge-toc.md documents; matchSegments handles ** across zero or more segments and falls back to path.Match per segment, so src/scripts/** matches src/scripts and src/scripts/a/b.
  • kickContextFor (src/pkg/scheduler/kick_priming.go:382) lowercases and dedupes labels and uses cfg.BaseAgentName, matching containsFold on the scope side.
  • Graph-expanded related facts go through the same gate (expandWithGraph(prioritized, scope, kc)), so a scoped fact cannot sneak back in via a neighbour.
  • Frontmatter: inline lists only, block lists skipped — documented, and parseScopeList strips brackets/quotes as described.

No security surface. Changelog fragment and knowledge-toc.md are updated.

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

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

Labels

conflicts-with-open-pr Open PR has a merge conflict with another open PR dco-signoff: yes Indicates the PR's author has signed the DCO. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer

1 participant