diff --git a/changelog.d/added-knowledge-draft-kicks.md b/changelog.d/added-knowledge-draft-kicks.md new file mode 100644 index 0000000000..5fec8c8c28 --- /dev/null +++ b/changelog.d/added-knowledge-draft-kicks.md @@ -0,0 +1 @@ +- An agent whose `knowledge.agent_scopes..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)). diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index c2e6853490..7528d9d3f7 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -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): diff --git a/src/docs/knowledge-curator.md b/src/docs/knowledge-curator.md index 5eb823b5d3..d12d8189c2 100644 --- a/src/docs/knowledge-curator.md +++ b/src/docs/knowledge-curator.md @@ -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. diff --git a/src/docs/knowledge-entries.md b/src/docs/knowledge-entries.md index a76128cb04..6ee6a5bdfe 100644 --- a/src/docs/knowledge-entries.md +++ b/src/docs/knowledge-entries.md @@ -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:/` — 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: diff --git a/src/docs/knowledge-lifecycle.md b/src/docs/knowledge-lifecycle.md index ee50c82f0f..c3f978211f 100644 --- a/src/docs/knowledge-lifecycle.md +++ b/src/docs/knowledge-lifecycle.md @@ -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`. diff --git a/src/docs/knowledge-toc.md b/src/docs/knowledge-toc.md index a52711a170..b959faad78 100644 --- a/src/docs/knowledge-toc.md +++ b/src/docs/knowledge-toc.md @@ -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 diff --git a/src/pkg/knowledge/filestore.go b/src/pkg/knowledge/filestore.go index 31afcd3a64..7b2a1caf0b 100644 --- a/src/pkg/knowledge/filestore.go +++ b/src/pkg/knowledge/filestore.go @@ -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. @@ -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 @@ -501,6 +503,7 @@ type parsedObsidianFile struct { supersedes string supersededBy string scope *FactScope + author string } var wikilinkRe = regexp.MustCompile(`\[\[([^\]|]+)(?:\|[^\]]+)?\]\]`) @@ -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:")), "\"'") } @@ -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) diff --git a/src/pkg/knowledge/lifecycle.go b/src/pkg/knowledge/lifecycle.go index 4aa20f6b33..8ac574db3d 100644 --- a/src/pkg/knowledge/lifecycle.go +++ b/src/pkg/knowledge/lifecycle.go @@ -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 @@ -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. diff --git a/src/pkg/knowledge/primer.go b/src/pkg/knowledge/primer.go index f75c3eb2be..ff9ed0e4b0 100644 --- a/src/pkg/knowledge/primer.go +++ b/src/pkg/knowledge/primer.go @@ -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) } @@ -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) { diff --git a/src/pkg/knowledge/primer_render.go b/src/pkg/knowledge/primer_render.go index 27740fdee3..64f0000af0 100644 --- a/src/pkg/knowledge/primer_render.go +++ b/src/pkg/knowledge/primer_render.go @@ -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) + ")") } diff --git a/src/pkg/knowledge/toc.go b/src/pkg/knowledge/toc.go index cc88cd653b..d8b1b2b054 100644 --- a/src/pkg/knowledge/toc.go +++ b/src/pkg/knowledge/toc.go @@ -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 diff --git a/src/pkg/knowledge/types.go b/src/pkg/knowledge/types.go index a084dc97e6..8ba97a9408 100644 --- a/src/pkg/knowledge/types.go +++ b/src/pkg/knowledge/types.go @@ -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. diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index a16b04324e..47740c3a2b 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -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) @@ -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) diff --git a/src/pkg/scheduler/kick_priming_draft_test.go b/src/pkg/scheduler/kick_priming_draft_test.go new file mode 100644 index 0000000000..ceb147a19d --- /dev/null +++ b/src/pkg/scheduler/kick_priming_draft_test.go @@ -0,0 +1,131 @@ +package scheduler + +import ( + "log/slog" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// TestPrimeKnowledge_DraftsReachTheirAuthor proves the kick-path draft rule +// (#17076): a draft is primed only when the agent's agent_scopes entry lists +// draft in include_states and the draft's author is the agent, its base agent +// or an owner login; it is rendered with a "(draft)" marker; approved-only +// stays the default for every other agent. +func TestPrimeKnowledge_DraftsReachTheirAuthor(t *testing.T) { + dir := t.TempDir() + write := func(name, title, state, author string) { + t.Helper() + content := "---\ntitle: " + title + "\ntype: gotcha\nlayer: project\nstate: " + state + "\n" + if author != "" { + content += "author: " + author + "\n" + } + content += "---\nRelevant to the webhook retry path.\n" + if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + write("approved.md", "Webhook retry approved fact", "approved", "") + write("dev-draft.md", "Webhook retry developer draft", "draft", "developer") + write("owner-draft.md", "Webhook retry owner draft", "draft", "alice") + write("other-draft.md", "Webhook retry scanner draft", "draft", "scanner") + write("anon-draft.md", "Webhook retry anonymous draft", "draft", "") + + logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) + store, err := knowledge.NewFileStore(dir, "vault", logger) + if err != nil { + t.Fatal(err) + } + primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger) + primer.AddFileStore("vault", store, knowledge.LayerProject) + + s := newScheduler() + s.cfg.Dashboard.AuthorizedUsers = []string{"github:alice", "bob:viewer"} + s.cfg.Agents = map[string]config.AgentConfig{"developer-2": {ReplicaOf: "developer"}} + s.cfg.Knowledge.AgentScopes = map[string]config.KnowledgeAgentScope{ + "developer": {IncludeStates: []string{"draft"}}, + "architect": {IncludeStates: []string{"all"}}, + "quality": {Layers: []string{"project"}}, + "reviewer": {IncludeStates: []string{"deprecated"}}, + } + s.SetPrimer(primer) + issues := []github.Issue{makeIssue("org/repo", 1, "Webhook retry fails", "", 5, []string{"webhook", "retry"}, false)} + + const ( + approved = "Webhook retry approved fact" + devDraft = "Webhook retry developer draft" + ownerDraft = "Webhook retry owner draft" + otherDraft = "Webhook retry scanner draft" + anonDraft = "Webhook retry anonymous draft" + ) + tests := []struct { + name string + agent string + want []string + deny []string + }{ + {"unscoped agent: approved only", "outreach", []string{approved}, []string{devDraft, ownerDraft, otherDraft, anonDraft}}, + {"scope without include_states: approved only", "quality", []string{approved}, []string{devDraft, ownerDraft, otherDraft, anonDraft}}, + {"include_states without draft: approved only", "reviewer", []string{approved}, []string{devDraft, ownerDraft, otherDraft, anonDraft}}, + {"draft opt-in: own and owner drafts, not others", "developer", []string{approved, devDraft, ownerDraft}, []string{otherDraft, anonDraft}}, + {"replica inherits base agent identity", "developer-2", []string{approved, devDraft, ownerDraft}, []string{otherDraft, anonDraft}}, + {"all opt-in without a matching author: owner drafts only", "architect", []string{approved, ownerDraft}, []string{devDraft, otherDraft, anonDraft}}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got := s.primeKnowledge(tc.agent, issues) + for _, w := range tc.want { + if !strings.Contains(got, w) { + t.Errorf("%s: missing %q in:\n%s", tc.agent, w, got) + } + } + for _, d := range tc.deny { + if strings.Contains(got, d) { + t.Errorf("%s: unexpected %q in:\n%s", tc.agent, d, got) + } + } + drafts := strings.Count(got, "(draft)") + wantDrafts := 0 + for _, w := range tc.want { + if w != approved { + wantDrafts++ + } + } + if drafts != wantDrafts { + t.Errorf("%s: %d \"(draft)\" markers, want %d in:\n%s", tc.agent, drafts, wantDrafts, got) + } + if strings.Contains(got, "**"+approved+"** (draft)") { + t.Errorf("%s: approved fact marked as draft", tc.agent) + } + }) + } +} + +func TestKickDraftAuthors(t *testing.T) { + cfg := &config.Config{} + cfg.Agents = map[string]config.AgentConfig{"scanner-3": {ReplicaOf: "scanner"}} + cfg.Dashboard.AuthorizedUsers = []string{"github:alice", "carol:owner", "bob:viewer"} + + tests := []struct { + agent string + want []string + }{ + {"scanner", []string{"scanner", "alice", "carol"}}, + {"scanner-3", []string{"scanner-3", "scanner", "alice", "carol"}}, + {"", []string{"alice", "carol"}}, + } + for _, tc := range tests { + got := kickDraftAuthors(cfg, tc.agent) + if strings.Join(got, ",") != strings.Join(tc.want, ",") { + t.Errorf("kickDraftAuthors(%q) = %v, want %v", tc.agent, got, tc.want) + } + } + if got := kickDraftAuthors(nil, "dev"); len(got) != 1 || got[0] != "dev" { + t.Errorf("nil config: got %v, want [dev]", got) + } +}