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-draft-kicks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- An agent whose `knowledge.agent_scopes.<agent>.include_states` lists `draft` is now primed with the draft knowledge entries it authored (`author:`/`owner:` frontmatter matching the agent, its base agent or a hive owner login), each marked `(draft)` in the kick; every other kick stays approved-only ([#17076](https://github.com/hivecommons/hive/issues/17076)).
17 changes: 12 additions & 5 deletions src/docs/agent-knowledge-and-memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,18 @@ them through a git source, connector or code map
`Primer.PrimeScoped` *after* the lifecycle filter and can only narrow; graph
expansion never pulls in an out-of-scope fact. A replica inherits its base
agent's entry (`Config.KnowledgeAgentScope`). No entry means unrestricted.
- *By lifecycle:* kicks carry **approved facts only**. The kick primer is built
with no `IncludeStates` (`newKnowledgePrimer` in `src/cmd/hive/main.go`), so
`draft`, `deprecated` and `superseded` never reach a kick; `agent_scopes.
include_states` only widens API/TOC reads that already asked for those
states ([knowledge-lifecycle.md](knowledge-lifecycle.md)).
- *By lifecycle:* kicks carry **approved facts only** by default. The kick
primer is built with no `IncludeStates` (`newKnowledgePrimer` in
`src/cmd/hive/main.go`), so `deprecated` and `superseded` never reach a kick
and `agent_scopes.include_states` only widens API/TOC reads that already
asked for those states ([knowledge-lifecycle.md](knowledge-lifecycle.md)).
The one kick-path exception is an agent's **own drafts** (#17076): when the
agent's `agent_scopes` entry lists `draft` (or `all`) in `include_states`,
drafts whose `author:` (or `owner:`) frontmatter is that agent, its base
agent or one of the hive's owner logins are primed too, each marked
`(draft)` in the kick (`kickDraftAuthors` in `kick_priming.go`,
`TOCScope.DraftAuthors`). Drafts by anyone else, and drafts with no author,
are still excluded.

**Size caps** (all drop whole units, never clip, and leave a visible marker):

Expand Down
4 changes: 3 additions & 1 deletion src/docs/knowledge-curator.md
Original file line number Diff line number Diff line change
Expand Up @@ -625,7 +625,9 @@ overwritten on the next change, so do not edit these pages.
Maps an agent name to the `layers`, `repos`, `types`, `tags` and
`include_states` that agent's kick primer and agent-identified knowledge reads
are restricted to. A missing agent or an empty field is unrestricted (the
default). Unknown layer or lifecycle state names fail config load. See
default). Listing `draft` in `include_states` additionally lets the agent's
kicks carry the drafts it authored (`author:` frontmatter), marked `(draft)`.
Unknown layer or lifecycle state names fail config load. See
[Per-agent scopes](knowledge-toc.md#per-agent-scopes) for the intersection
rules, and [agent-knowledge-and-memory.md](agent-knowledge-and-memory.md) for
how the scope is applied on the kick path end to end.
Expand Down
1 change: 1 addition & 0 deletions src/docs/knowledge-entries.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ A PR that edits anything under `src/scripts/` must re-pin …
| `state` | Lifecycle (`approved`, `draft`, `deprecated`, `superseded`); only `approved` is primed by default. See [knowledge-lifecycle.md](knowledge-lifecycle.md). |
| `tags` | Inline list. Always include `repo:<org>/<name>` — that is how `knowledge.agent_scopes.repos` recognises the entry's repository. |
| `source` | Where the fact came from, so a reader can trace a moved `AGENTS.md` line to exactly one entry. |
| `author` | Who wrote the entry — an agent name (`developer`) or a login (alias `owner`). A `draft` reaches a kick only for the agent that matches this and has opted into drafts; see [knowledge-toc.md](knowledge-toc.md#per-agent-scopes). |
| `scope` | **Where the fact applies.** `paths` are repo-relative globs (`**` supported), `labels` are issue labels, `lanes` are base agent/lane names. An empty list means "no constraint on that dimension". |

Rules of thumb:
Expand Down
4 changes: 3 additions & 1 deletion src/docs/knowledge-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@ Remote wiki layers only carry a `status`, which is mapped the same way.

- **Kick primers** include approved facts only. Set
`knowledge.PrimerConfig.IncludeStates` (`include_states`) to admit other
states.
states. An agent whose `knowledge.agent_scopes` entry lists `draft` is also
primed with the drafts it (or the hive owner) authored, marked `(draft)`;
see [Per-agent scopes](knowledge-toc.md#per-agent-scopes).
- **`GET /api/knowledge/search`** returns approved facts only unless the
operator passes `include_states`, e.g. `include_states=deprecated,superseded`
or `include_states=all`.
Expand Down
9 changes: 9 additions & 0 deletions src/docs/knowledge-toc.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,15 @@ only when the agent scope lists that state (or leaves `include_states` empty)
too. An agent scope therefore never admits a state the operator did not ask
for.

The kick primer makes one exception for an agent's own drafts (#17076). When
an agent scope lists `draft` (or `all`) explicitly, a kick for that agent also
carries draft entries whose `author:` (alias `owner:`) frontmatter matches the
agent name, its base agent (for replicas) or an owner login from
`dashboard.authorized_users`; they are rendered with a `(draft)` marker.
Drafts by other authors, and drafts without an author, remain excluded, and an
empty `include_states` does not opt in. TOC and entry reads are unaffected —
they keep the intersection rule above.

Config load rejects unknown layer names (`personal`, `project`, `org`,
`community`) and unknown state names (`draft`, `approved`, `deprecated`,
`superseded`, `all`). The scopes can also be read and replaced with
Expand Down
8 changes: 8 additions & 0 deletions src/pkg/knowledge/filestore.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ type filePage struct {
State LifecycleState
Supersedes string
SupersededBy string
Author string
}

// NewFileStore creates a store that indexes markdown files under rootDir.
Expand Down Expand Up @@ -213,6 +214,7 @@ func (s *FileStore) reindex() {
if !parsed.scope.IsZero() {
page.Scope = parsed.scope
}
page.Author = parsed.author
pages[slug] = page

return nil
Expand Down Expand Up @@ -501,6 +503,7 @@ type parsedObsidianFile struct {
supersedes string
supersededBy string
scope *FactScope
author string
}

var wikilinkRe = regexp.MustCompile(`\[\[([^\]|]+)(?:\|[^\]]+)?\]\]`)
Expand Down Expand Up @@ -580,6 +583,10 @@ func parseObsidianFileDetailed(content string, fallbackTitle string) parsedObsid
if strings.HasPrefix(line, "superseded_by:") {
parsed.supersededBy = strings.Trim(strings.TrimSpace(strings.TrimPrefix(line, "superseded_by:")), "\"'")
}
if strings.HasPrefix(line, "author:") || strings.HasPrefix(line, "owner:") {
_, value, _ := strings.Cut(line, ":")
parsed.author = strings.Trim(strings.TrimSpace(value), "\"'")
}
if strings.HasPrefix(line, "source:") {
parsed.source = strings.Trim(strings.TrimSpace(strings.TrimPrefix(line, "source:")), "\"'")
}
Expand Down Expand Up @@ -677,6 +684,7 @@ func (p filePage) applyLifecycle(f *Fact) {
f.Scope = p.Scope
f.Supersedes = p.Supersedes
f.SupersededBy = p.SupersededBy
f.Author = p.Author
f.State = resolveLifecycleState(p.State, p.Status, p.SupersededBy)
f.Updated = p.ModTime
f.BodySize = len(p.Body)
Expand Down
37 changes: 36 additions & 1 deletion src/pkg/knowledge/lifecycle.go
Original file line number Diff line number Diff line change
Expand Up @@ -101,10 +101,19 @@ func lifecycleAllowed(st LifecycleState, include []LifecycleState) bool {
// is listed in include. With a nil/empty include only approved (current)
// knowledge survives. Retained facts have State populated.
func FilterByLifecycle(facts []Fact, include []LifecycleState) []Fact {
return FilterByLifecycleFor(facts, include, nil)
}

// FilterByLifecycleFor is FilterByLifecycle that additionally keeps draft
// facts authored by one of draftAuthors (#17076). It is the kick-path filter:
// the scheduler lists the kicked agent's identities when that agent's
// knowledge.agent_scopes entry opts into drafts, so an agent is primed with
// the drafts it wrote while every other draft is still excluded.
func FilterByLifecycleFor(facts []Fact, include []LifecycleState, draftAuthors []string) []Fact {
out := make([]Fact, 0, len(facts))
for _, f := range facts {
st := f.EffectiveState()
if !lifecycleAllowed(st, include) {
if !lifecycleAllowedFor(f, st, include, draftAuthors) {
continue
}
f.State = st
Expand All @@ -113,6 +122,32 @@ func FilterByLifecycle(facts []Fact, include []LifecycleState) []Fact {
return out
}

// lifecycleAllowedFor is lifecycleAllowed plus the author-matched draft rule
// of FilterByLifecycleFor.
func lifecycleAllowedFor(f Fact, st LifecycleState, include []LifecycleState, draftAuthors []string) bool {
if lifecycleAllowed(st, include) {
return true
}
return st == StateDraft && DraftAuthoredBy(f, draftAuthors)
}

// DraftAuthoredBy reports whether f carries an author and that author is one
// of authors (case-insensitive, surrounding space ignored). An authorless
// fact never matches, so drafts from sources that record no author stay
// hidden.
func DraftAuthoredBy(f Fact, authors []string) bool {
author := strings.TrimSpace(f.Author)
if author == "" {
return false
}
for _, a := range authors {
if strings.EqualFold(strings.TrimSpace(a), author) {
return true
}
}
return false
}

// SetLifecycleState records state on the fact identified by slug by rewriting
// its frontmatter. Setting a state other than superseded clears any
// superseded_by link so the fact is not implicitly re-superseded on load.
Expand Down
14 changes: 12 additions & 2 deletions src/pkg/knowledge/primer.go
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,13 @@ func (p *Primer) PrimeForKick(ctx context.Context, scope *TOCScope, kc KickConte

// Filter after the precedence merge so a higher-precedence layer that
// deprecates a slug hides it rather than surfacing a lower layer's copy.
merged := FilterByLifecycle(p.mergeWithPrecedence(allFacts), p.config.IncludeStates)
// An agent that opted into its own drafts (TOCScope.DraftAuthors, #17076)
// gets those on top of what the primer's lifecycle filter admits.
var draftAuthors []string
if scope != nil {
draftAuthors = scope.DraftAuthors
}
merged := FilterByLifecycleFor(p.mergeWithPrecedence(allFacts), p.config.IncludeStates, draftAuthors)
if scope != nil {
merged = scope.Filter(merged)
}
Expand Down Expand Up @@ -317,7 +323,11 @@ func (p *Primer) expandWithGraph(facts []Fact, scope *TOCScope, kc KickContext)
for _, ls := range p.fileStores {
if relFact, err := ls.store.ReadPage(relSlug); err == nil {
relFact.Layer = ls.layerType
if !lifecycleAllowed(relFact.EffectiveState(), p.config.IncludeStates) {
var draftAuthors []string
if scope != nil {
draftAuthors = scope.DraftAuthors
}
if !lifecycleAllowedFor(*relFact, relFact.EffectiveState(), p.config.IncludeStates, draftAuthors) {
break
}
if scope != nil && !scope.InScope(*relFact) {
Expand Down
8 changes: 6 additions & 2 deletions src/pkg/knowledge/primer_render.go
Original file line number Diff line number Diff line change
Expand Up @@ -146,11 +146,15 @@ func (pk *PrimedKnowledge) Render() (string, PrimerOmitted) {
return b.String(), omitted
}

// renderPrimerFact renders one fact as a list entry: title, optional
// confidence and source, then the body indented beneath it.
// renderPrimerFact renders one fact as a list entry: title, a "(draft)"
// marker for uncurated facts (#17076), optional confidence and source, then
// the body indented beneath it.
func renderPrimerFact(f Fact) string {
var b strings.Builder
b.WriteString("- **" + f.Title + "**")
if f.EffectiveState() == StateDraft {
b.WriteString(" (draft)")
}
if f.ConfidenceScored && f.Confidence < 1.0 {
b.WriteString(" (confidence: " + formatConfidence(f.Confidence) + ")")
}
Expand Down
20 changes: 20 additions & 0 deletions src/pkg/knowledge/toc.go
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,26 @@ type TOCScope struct {
// IncludeStates admits non-approved lifecycle states; approved entries are
// always visible.
IncludeStates []LifecycleState
// DraftAuthors lets the kick primer carry draft facts written by one of
// these identities even though the primer itself admits approved facts
// only (#17076). The scheduler sets it from the kicked agent's name, its
// base agent and the hive's owner logins when the agent's agent_scopes
// entry lists draft in include_states. TOC and API reads leave it empty.
DraftAuthors []string
}

// ListsDraft reports whether an include_states config list opts into drafts
// explicitly, via "draft" or "all". An empty list does not: AgentScope treats
// it as "defer to the request or primer", which never admits drafts on the
// kick path.
func ListsDraft(includeStates []string) bool {
for _, st := range includeStates {
st = strings.ToLower(strings.TrimSpace(st))
if st == string(StateDraft) || st == "all" {
return true
}
}
return false
}

// AgentScope builds the scope an agent is bound to by knowledge.agent_scopes
Expand Down
8 changes: 6 additions & 2 deletions src/pkg/knowledge/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -267,8 +267,12 @@ type Fact struct {
Layer LayerType `json:"layer"`
Sources []Source `json:"sources,omitempty"`
Related []string `json:"related,omitempty"`
UsageCount int `json:"usage_count"`
LastUsed time.Time `json:"last_used,omitempty"`
// Author is the entry's `author:` (or `owner:`) frontmatter: the agent or
// person who wrote it. The kick primer uses it to let a draft reach the
// agent that owns it (#17076); empty for sources that record no author.
Author string `json:"author,omitempty"`
UsageCount int `json:"usage_count"`
LastUsed time.Time `json:"last_used,omitempty"`

// State is the lifecycle state (draft, approved, deprecated, superseded).
// Empty means the fact predates lifecycle states; see EffectiveState.
Expand Down
36 changes: 36 additions & 0 deletions src/pkg/scheduler/kick_priming.go
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,9 @@ func (s *Scheduler) primeKnowledgeStats(agentName string, issues []github.Issue)
var scope *knowledge.TOCScope
if sc, ok := cfg.KnowledgeAgentScope(agentName); ok {
agentScope := knowledge.AgentScope(sc.Layers, sc.Repos, sc.Types, sc.Tags, sc.IncludeStates)
if knowledge.ListsDraft(sc.IncludeStates) {
agentScope.DraftAuthors = kickDraftAuthors(cfg, agentName)
}
scope = &agentScope
}
primed := primer.PrimeForKick(context.Background(), scope, kickContextFor(cfg, agentName, issues[:limit]), keywords)
Expand Down Expand Up @@ -338,6 +341,39 @@ func (s *Scheduler) primeKnowledgeStats(agentName string, issues []github.Issue)
return inj
}

// kickDraftAuthors lists the identities whose draft knowledge a kick for
// agentName may carry once that agent's agent_scopes entry opts into drafts
// (#17076): the agent itself, its base agent for a replica, and the hive's
// owner logins, so an operator's hand-written draft reaches the agents they
// opted in. Owner entries are stored as "alice" or "github:alice"; the
// provider prefix is dropped so either form matches an author: line.
func kickDraftAuthors(cfg *config.Config, agentName string) []string {
var out []string
add := func(name string) {
name = strings.TrimSpace(name)
if name == "" {
return
}
for _, have := range out {
if strings.EqualFold(have, name) {
return
}
}
out = append(out, name)
}
add(agentName)
if cfg != nil {
add(cfg.BaseAgentName(agentName))
for _, login := range cfg.Dashboard.OwnerLogins() {
if _, bare, ok := strings.Cut(login, ":"); ok {
login = bare
}
add(login)
}
}
return out
}

// logKnowledgeInjection emits the one knowledge line per kick (#17049):
//
// knowledge: injected N bytes from M entries (skipped K for cap)
Expand Down
Loading
Loading