Repository navigation
Description
Second half of @gregoryhunt's knowledge-scoping investigation from the 2026-11-05 community meeting (the first half, drafts reaching their author's agent, is tracked separately). Design issue: file anchors below, no PR yet.
Gaps
Today the only access control on knowledge is knowledge.agent_scopes (src/pkg/config/knowledge_config.go, knowledge.AgentScope in src/pkg/knowledge/toc.go): an allow-list per agent over layers / repos / types / tags / include_states. Two things cannot be expressed:
- Who may read an entry, stated on the entry. There is no notion of audience on the fact itself. An operator cannot write "this entry is for the maintainer's agents only, never for a contributor-container agent" or "only the claude family may see this" without inventing a tag and remembering to mirror it in every agent's
tags:allow-list — and tag allow-lists are any-match, so a single shared tag re-admits the entry. The public MCP (src/pkg/dashboard/mcp_knowledge.go,knowledge.public.tags) and the contributor-container path (🔒 security(contribute): container mode stages the contributor's entire ~/.claude (all transcripts, prompt history, paste cache, memory, CLAUDE.md) into the agent sandbox — only the credential file is needed #7836 family) have the same problem: visibility is decided by the reader's config, not by the entry. - Repo auto-scope.
agent_scopes.reposhidesrepo:<name>-tagged entries from an agent, but a kick is not filtered by the repos of the issues it is about:primeKnowledgeStats(src/pkg/scheduler/kick_priming.go) only passes keywords, so an entry about repo X is offered to a kick for repo Y whenever the keywords match (documented as such insrc/docs/agent-knowledge-and-memory.md, "By the work, not the repo"). ✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045 addsscope.paths/labels/lanesbut not repos.
Proposal
audience: frontmatter
audience: [maintainers] # default when absent: maintainers + their agents
audience: [contributors] # also readable from contributor containers
audience: [agents: [developer, scanner]] # inline map form, or audience_agents: [developer, scanner]
audience: [families: [claude, codex]] # or audience_families: [claude, codex]
audience: [public] # eligible for the public MCP (still gated by knowledge.public.tags)Flat keys (audience, audience_agents, audience_families) are preferred because the frontmatter parser in filestore.go is line-oriented and the scope: block in #17045 already shows the cost of nesting.
Semantics — a reader is a tuple (role, agent, family); an entry is visible when every declared dimension admits the reader (AND across dimensions, OR within a list):
role:maintainers(hive-owned agents and operator reads),contributors(contributor-container agents),public(unauthenticated MCP). Absent →maintainers.contributorsimpliesmaintainers;publicimplies both.agents: base agent names (Config.BaseAgentName); absent → any agent.families: CLI family of the agent (claude,codex,gemini,bob, …, from the agent'scliconfig); absent → any.
Enforcement points
FactAudiencetype +Admits(reader)in a newsrc/pkg/knowledge/audience.go; parse inparseObsidianFileDetailed(filestore.go), carried onFact.- Kick path:
Primer.PrimeForKick(✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045) gets the reader onKickContext(Agent,Family,Role: maintainers);expandWithGraphgates related facts the same way. - Pull path:
handleKnowledgeTOC/handleKnowledgeEntry/handleKnowledgeEffective(src/pkg/dashboard/api_knowledge_toc.go) derive the reader fromagent=+ the caller's dashboard role; the effective view reportsExcludedAudienceas a new exclusion reason alongsidelifecycle|layer|repo|type|tag(TOCScope.ExclusionReason). - Public MCP (
mcp_knowledge.go):knowledge_toc/knowledge_getrequirepublicin the audience in addition to the existingknowledge.public.tagsgate. - Contributor containers: the kick built for a contributor-container agent sets
Role: contributors.
repo auto-scope
- Extend ✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045's
FactScopewithRepos []string; an entry withscope.reposis admitted only for a kick whose issues are on one of those repos (github.Issue.Repo, passed viaKickContext.ReposfromprimeKnowledgeStats).repo:<name>tags keep their current meaning foragent_scopes.repos. - Entries indexed from a repo's
src/docs/knowledge/(the project-knowledge directory ofsrc/docs/knowledge-entries.md) inheritscope.repos: [<org>/<repo>]and arepo:<org>/<repo>tag when they declare neither, so a repo's own facts are never offered to another repo's kick.
Non-goals
- No change to
agent_scopessemantics; the agent allow-list still applies first, the entry's audience can only narrow. - Entries without
audience:behave exactly as today for maintainers; the only behaviour change for unannotated entries is thatpublicMCP reads additionally require an explicitpublicaudience — to be decided (could default to today's tag-only gate behind aknowledge.public.require_audienceflag).
Tests to write
Table-driven on FactAudience.Admits (role implication, agents, families, AND across dimensions); primer test that a contributors entry reaches a contributor kick and a maintainers entry does not; TOC effective test showing audience as the exclusion reason; kick test that a scope.repos: [org/x] entry is dropped for an org/y issue and kept for org/x.
Activity
clubanderson commentedon Nov 7, 2026
Parking this: per-entry audience/RBAC is premature while hives are single-owner. Revisit when a hive has multiple humans with different rights (team-collaboration gap). Draft-visibility piece continues in #17079.