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-14551.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Owners can now find retro lessons learned from human review that are waiting for approval: the dashboard Knowledge section shows "N lessons awaiting approval", and `hivectl knowledge list --state draft --tag review-feedback` lists them. `GET /api/knowledge` gains `state` and `tag` filters, and asking for unapproved states without the owner role is refused.
2 changes: 1 addition & 1 deletion src/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ Read the result from `GET /api/kick/{agent}/status`, which returns `status` of `

| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
| `GET` | `/api/knowledge` | Dashboard auth/session | Paginated knowledge facts: `type` filter, `limit` (default 50, max 200; invalid/non-positive values use the default), `offset` (default 0). Returns `enabled`, `facts`, `count` (this page), `total`, `limit`, `offset`, `has_more`; ordered by layer then slug. Offsets are not snapshot cursors: concurrent edits may shift pages. | `pkg/dashboard/api.go:379` |
| `GET` | `/api/knowledge` | Dashboard auth/session | Paginated knowledge facts: `type` filter, `tag` (comma-separated; a fact must carry every tag), `state` (comma-separated lifecycle states or `all`; only facts in those states are listed, and any state other than `approved` requires a verified owner and returns 403 otherwise), `limit` (default 50, max 200; invalid/non-positive values use the default), `offset` (default 0). Returns `enabled`, `facts`, `count` (this page), `total`, `limit`, `offset`, `has_more`; ordered by layer then slug. Offsets are not snapshot cursors: concurrent edits may shift pages. | `pkg/dashboard/api.go:379` |
| `GET` | `/api/knowledge/export` | Dashboard auth/session | Knowledge Export | `pkg/dashboard/api.go:380` |
| `POST` | `/mcp/knowledge` | Public (read-only) when the dashboard setting or `HIVE_PUBLIC_KNOWLEDGE` is on; 404 otherwise | Public Knowledge MCP endpoint — `initialize`, `tools/list`, `tools/call` for `knowledge_search`/`knowledge_toc`/`knowledge_get`/`knowledge_export` ([docs](public-knowledge-mcp.md)) | `pkg/dashboard/api.go:388` |
| `GET` | `/api/knowledge/search` | Dashboard auth/session | Knowledge Search | `pkg/dashboard/api.go:381` |
Expand Down
7 changes: 7 additions & 0 deletions src/docs/hivectl.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ hivectl knowledge search "user journey" --limit 20
hivectl knowledge list --limit 200 --offset 0 -o json # first page across all layers
hivectl knowledge list --limit 200 --offset 200 -o json # next page
hivectl knowledge list --layer project # layer: personal|project|org|community
hivectl knowledge list --state draft --tag review-feedback # owner only: lessons awaiting approval
hivectl knowledge get project create-project
hivectl knowledge stats
hivectl knowledge health # knowledge engine health check
Expand All @@ -156,6 +157,12 @@ Without `--layer`, `knowledge list` returns one page: `--limit` defaults to 50
increasing `--offset` by `--limit`. `--type` applies before pagination.
With `--layer`, the command still lists the entire layer; combining `--layer`
with `--limit` or `--offset` is an error.
`--tag` (repeatable or comma-separated) lists only facts carrying every given
tag. `--state` (comma-separated `draft`, `approved`, `deprecated`,
`superseded` or `all`) lists only facts in those lifecycle states; any state
other than `approved` needs the owner role, and the server refuses the request
otherwise. Neither flag combines with `--layer`. Approve a listed draft with
`hivectl knowledge state <id> approved`.

`graph` reads the knowledge graph (`--root` optional; `--depth` defaults to 2
and must be greater than zero). `import` posts Markdown or structured content
Expand Down
10 changes: 8 additions & 2 deletions src/docs/knowledge-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,14 @@ Remote wiki layers only carry a `status`, which is mapped the same way.
- **`GET /api/knowledge/toc`** and **`GET /api/knowledge/entry/{id}`** apply
the same default and `include_states` opt-in; see
[Scoped knowledge table of contents](knowledge-toc.md).
- `GET /api/knowledge` (the dashboard inventory) still lists every fact, and
vault facts report their `state`, so operators can review and restore them.
- `GET /api/knowledge` (the dashboard inventory) applies the same default and
`include_states` opt-in, and vault facts report their `state`. An owner can
list exactly one set of states with `state`, e.g.
`state=draft&tag=retro,review-feedback` lists retro lessons derived from
human review that await approval (`hivectl knowledge list --state draft
--tag review-feedback`). Asking for any state other than `approved` without
the owner role is refused with 403. The dashboard Knowledge section shows
the owner "N lessons awaiting approval" when such drafts exist.

## Changing a fact's state

Expand Down
81 changes: 80 additions & 1 deletion src/pkg/dashboard/api_knowledge.go
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,10 @@ func (s *Server) handleBeadSynthToggle(w http.ResponseWriter, r *http.Request) {
}

func (s *Server) handleKnowledgeList(w http.ResponseWriter, r *http.Request) {
states, ok := knowledgeListStates(w, r)
if !ok {
return
}
if !s.ensureKnowledge() {
jsonResponse(w, map[string]interface{}{"enabled": false, "facts": []interface{}{}})
return
Expand All @@ -172,7 +176,14 @@ func (s *Server) handleKnowledgeList(w http.ResponseWriter, r *http.Request) {
}
limit, offset := knowledgeListPagination(r)
typeFilter := r.URL.Query().Get("type")
facts := knowledge.FilterByLifecycle(s.deps.Knowledge.SearchAllWithVaults(s.deps.Ctx, "", typeFilter, 0), includeStates)
all := s.deps.Knowledge.SearchAllWithVaults(s.deps.Ctx, "", typeFilter, 0)
var facts []knowledge.Fact
if len(states) > 0 {
facts = filterFactsByExactState(all, states)
} else {
facts = knowledge.FilterByLifecycle(all, includeStates)
}
facts = filterFactsByAllTags(facts, splitCSV(r.URL.Query().Get("tag")))
// Search merges multiple stores; impose a stable order before slicing pages.
sort.SliceStable(facts, func(i, j int) bool {
if facts[i].Layer != facts[j].Layer {
Expand All @@ -197,6 +208,74 @@ func (s *Server) handleKnowledgeList(w http.ResponseWriter, r *http.Request) {
})
}

// knowledgeListStates parses the list's ?state= filter, a comma-separated
// list of lifecycle states (or "all") that the listed facts must be in.
// Listing any state other than approved exposes unapproved knowledge, so it
// requires a verified owner and is refused, not silently clamped, otherwise.
func knowledgeListStates(w http.ResponseWriter, r *http.Request) ([]knowledge.LifecycleState, bool) {
states, err := knowledge.ParseLifecycleStates(r.URL.Query().Get("state"))
if err != nil {
jsonError(w, err.Error(), http.StatusBadRequest)
return nil, false
}
for _, st := range states {
if st != knowledge.StateApproved {
if !requireOwnerRole(w, r) {
return nil, false
}
break
}
}
return states, true
}

// filterFactsByExactState keeps only facts whose effective lifecycle state is
// listed in states, with State populated.
func filterFactsByExactState(facts []knowledge.Fact, states []knowledge.LifecycleState) []knowledge.Fact {
out := make([]knowledge.Fact, 0, len(facts))
for _, f := range facts {
st := f.EffectiveState()
for _, want := range states {
if st == want {
f.State = st
out = append(out, f)
break
}
}
}
return out
}

// filterFactsByAllTags keeps facts carrying every tag (case-insensitive).
func filterFactsByAllTags(facts []knowledge.Fact, tags []string) []knowledge.Fact {
if len(tags) == 0 {
return facts
}
out := make([]knowledge.Fact, 0, len(facts))
for _, f := range facts {
if factHasAllTags(f, tags) {
out = append(out, f)
}
}
return out
}

func factHasAllTags(f knowledge.Fact, tags []string) bool {
for _, want := range tags {
found := false
for _, t := range f.Tags {
if strings.EqualFold(strings.TrimSpace(t), want) {
found = true
break
}
}
if !found {
return false
}
}
return true
}

// knowledgeListPagination bounds list responses, including omitted or invalid limits.
func knowledgeListPagination(r *http.Request) (limit, offset int) {
limit, _ = strconv.Atoi(r.URL.Query().Get("limit"))
Expand Down
141 changes: 141 additions & 0 deletions src/pkg/dashboard/api_knowledge_review_drafts_14551_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
package dashboard

import (
"encoding/json"
"io"
"log/slog"
"net/http"
"os"
"path/filepath"
"strings"
"testing"

"github.com/hivecommons/hive/pkg/knowledge"
)

// reviewDrafts14551Server holds one review-derived retro draft, one retro
// draft from another writer and one approved fact carrying the same tags.
func reviewDrafts14551Server(t *testing.T) *Server {
t.Helper()
logger := slog.New(slog.NewTextHandler(io.Discard, &slog.HandlerOptions{Level: slog.LevelError}))
s := NewServerWithAuth(0, "", logger)
s.RegisterAPI(testDeps(t))

vault := filepath.Join(t.TempDir(), "vault")
if err := os.MkdirAll(vault, 0o755); err != nil {
t.Fatal(err)
}
files := [][2]string{
{"review-draft.md", "---\ntitle: Review Draft Lesson\ntype: pattern\ntags: [retro, lesson, review-feedback]\nstate: draft\nlayer: project\n---\nReviewers expect tests.\n"},
{"other-draft.md", "---\ntitle: Other Draft Lesson\ntype: pattern\ntags: [retro, lesson]\nstate: draft\nlayer: project\n---\nOther writer.\n"},
{"approved-review.md", "---\ntitle: Approved Review Lesson\ntype: pattern\ntags: [retro, lesson, review-feedback]\nlayer: project\n---\nAlready approved.\n"},
}
for _, f := range files {
if err := os.WriteFile(filepath.Join(vault, f[0]), []byte(f[1]), 0o644); err != nil {
t.Fatal(err)
}
}
api := knowledge.NewKnowledgeAPI(nil, knowledge.KnowledgeConfig{Enabled: true, Engine: "file"}, logger)
if err := api.ConnectVault(vault, "vault"); err != nil {
t.Fatalf("ConnectVault: %v", err)
}
s.deps.Knowledge = api
return s
}

type reviewDraftsList struct {
Total int `json:"total"`
Facts []struct {
Title string `json:"title"`
State knowledge.LifecycleState `json:"state"`
} `json:"facts"`
}

func decodeReviewDraftsList(t *testing.T, body string) reviewDraftsList {
t.Helper()
var out reviewDraftsList
if err := json.Unmarshal([]byte(body), &out); err != nil {
t.Fatalf("decode: %v body=%s", err, body)
}
return out
}

const reviewDraftsQuery = "/api/knowledge?state=draft&tag=retro," + knowledge.ReviewFeedbackTag

// TestKnowledgeListOwnerFiltersReviewDrafts: the owner lists exactly the
// review-derived drafts with state + tag, and no approved fact (B-AC16).
// After approval the draft is no longer listed (B-AC15).
func TestKnowledgeListOwnerFiltersReviewDrafts(t *testing.T) {
s := reviewDrafts14551Server(t)

for _, target := range []string{reviewDraftsQuery, "/api/knowledge?state=draft&tag=review-feedback"} {
code, body := lifecycle14546Get(t, s, target, "owner", true)
if code != http.StatusOK {
t.Fatalf("%s status = %d body=%s", target, code, body)
}
got := decodeReviewDraftsList(t, body)
if got.Total != 1 || len(got.Facts) != 1 || got.Facts[0].Title != "Review Draft Lesson" || got.Facts[0].State != knowledge.StateDraft {
t.Fatalf("%s = %+v, want only the review draft", target, got)
}
}

code, body := lifecycle14546Get(t, s, "/api/knowledge?state=draft", "owner", true)
if code != http.StatusOK {
t.Fatalf("state=draft status = %d", code)
}
if got := decodeReviewDraftsList(t, body); got.Total != 2 || strings.Contains(body, "Approved Review Lesson") {
t.Fatalf("state=draft = %s, want both drafts and no approved fact", body)
}

if rec := doKnowledgeStatePut(s, "review-draft", "owner", true, `{"state":"approved"}`); rec.Code != http.StatusOK {
t.Fatalf("approve status = %d body=%s", rec.Code, rec.Body.String())
}
_, body = lifecycle14546Get(t, s, reviewDraftsQuery, "owner", true)
if got := decodeReviewDraftsList(t, body); got.Total != 0 {
t.Fatalf("after approval = %s, want no drafts awaiting approval", body)
}
}

// TestKnowledgeListRefusesNonApprovedStateToNonOwner: asking for unapproved
// states without a verified owner is refused and leaks nothing (B-AC16,
// B-AC7 non-owner half).
func TestKnowledgeListRefusesNonApprovedStateToNonOwner(t *testing.T) {
s := reviewDrafts14551Server(t)
for _, tc := range []struct {
role string
verified bool
}{{"read", false}, {"merger", false}, {"owner", false}} {
for _, target := range []string{reviewDraftsQuery, "/api/knowledge?state=all", "/api/knowledge?state=approved,draft"} {
code, body := lifecycle14546Get(t, s, target, tc.role, tc.verified)
if code != http.StatusForbidden {
t.Errorf("role=%q verified=%v %s status = %d, want 403", tc.role, tc.verified, target, code)
}
if strings.Contains(body, "Draft Lesson") {
t.Errorf("role=%q %s leaked a draft: %s", tc.role, target, body)
}
}
}
}

// TestKnowledgeListApprovedStateAndTagForNonOwner: approved-only listing and
// tag filtering stay open to every reader, and never include drafts.
func TestKnowledgeListApprovedStateAndTagForNonOwner(t *testing.T) {
s := reviewDrafts14551Server(t)
for _, target := range []string{"/api/knowledge?state=approved&tag=review-feedback", "/api/knowledge?tag=review-feedback"} {
code, body := lifecycle14546Get(t, s, target, "read", false)
if code != http.StatusOK {
t.Fatalf("%s status = %d body=%s", target, code, body)
}
got := decodeReviewDraftsList(t, body)
if got.Total != 1 || got.Facts[0].Title != "Approved Review Lesson" {
t.Fatalf("%s = %s, want only the approved review lesson", target, body)
}
}
}

func TestKnowledgeListRejectsInvalidState(t *testing.T) {
s := reviewDrafts14551Server(t)
if code, body := lifecycle14546Get(t, s, "/api/knowledge?state=pending", "owner", true); code != http.StatusBadRequest {
t.Fatalf("status = %d body=%s, want 400", code, body)
}
}
58 changes: 58 additions & 0 deletions src/pkg/dashboard/knowledge_review_drafts_ui_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
package dashboard

import (
"os/exec"
"strings"
"testing"
)

// TestKnowledgeReviewDraftsUI: the Knowledge section shows the owner how many
// review-derived retro lessons await approval; non-owners never request the
// count or see the line (B-AC15).
func TestKnowledgeReviewDraftsUI(t *testing.T) {
node, err := exec.LookPath("node")
if err != nil {
t.Skip("node unavailable")
}
b, err := staticFS.ReadFile("static/index.html")
if err != nil {
t.Fatal(err)
}
html := string(b)
start := strings.Index(html, " async function fetchKnowledgeReviewDrafts() {")
if start < 0 {
t.Fatal("missing fetchKnowledgeReviewDrafts")
}
end := strings.Index(html[start:], " async function fetchKnowledgeStats() {")
if end < 0 {
t.Fatal("missing fetchKnowledgeStats")
}
render := html[strings.Index(html, " function renderKnowledge() {"):]
if !strings.Contains(render[:strings.Index(render, "\n }\n")], "kbReviewDraftsHTML(_kbCache._reviewDrafts, viewerIsOwner())") {
t.Fatal("renderKnowledge does not render the awaiting-approval line")
}
script := `
const assert = require('node:assert/strict');
let owner = false;
const viewerIsOwner = () => owner;
let urls = [];
global.fetch = async url => { urls.push(url); return {ok: true, json: async () => ({total: 3})}; };
` + html[start:start+end] + `
(async () => {
assert.equal(kbReviewDraftsHTML(1, true).includes('>📝 1 lesson awaiting approval<'), true);
assert.match(kbReviewDraftsHTML(2, true), /2 lessons awaiting approval/);
assert.equal(kbReviewDraftsHTML(0, true), '');
assert.equal(kbReviewDraftsHTML(1, false), '');
assert.equal(await fetchKnowledgeReviewDrafts(), 0);
assert.equal(urls.length, 0);
owner = true;
assert.equal(await fetchKnowledgeReviewDrafts(), 3);
assert.deepEqual(urls, ['/api/knowledge?state=draft&tag=retro,review-feedback&limit=1']);
global.fetch = async () => ({ok: false, status: 403});
assert.equal(await fetchKnowledgeReviewDrafts(), 0);
})().catch(e => {console.error(e); process.exit(1);});
`
if out, err := exec.Command(node, "-e", script).CombinedOutput(); err != nil {
t.Fatalf("knowledge review drafts: %v\n%s", err, out)
}
}
Loading
Loading