[hivecommons-hive]

Why

#14663 stores retro lessons that come from human review feedback as owner-approved drafts tagged review-feedback. It did not give the owner a way to see or find them. This PR adds that owner visibility (child 4 of the decomposition on #14551: B9 dashboard + CLI, B-AC15, B-AC16, and the non-owner list half of B-AC7).

• GET /api/knowledge gains a state filter that lists exactly the given lifecycle states. Any state other than approved needs a verified owner and gets 403 otherwise, so drafts are never silently returned or leaked. It also gains a tag filter: a fact must carry every tag.
• hivectl knowledge list --state draft --tag review-feedback (owner only). Neither flag combines with --layer.
• The dashboard Knowledge section shows the owner "N lesson(s) awaiting approval". It counts drafts tagged retro + review-feedback through the owner-gated list, and non-owners never request the count.
• Docs: hivectl.md, api-reference.md, knowledge-lifecycle.md. The last one also corrects a bullet that went stale after 🐛 fix(knowledge): keep draft, deprecated and superseded facts away from agents #14552.

Approval still goes through the existing owner-only hivectl knowledge state <id> approved.

The tests fail without this change: API filtering, owner gating and the disappearance after approval; the dashboard line through node; CLI flag wiring and refusal. CI is the verdict. Tests were not run locally.

Refs #14551 (remaining: the GitHub review-feedback source, B1–B3, and the retro lane consuming it, B4–B6, B10–B12 and the B9 log line — blocked by #14584, PR #14608 not yet merged)

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 requested_by=@Danathar

[kubestellar-prow]

[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:

• OWNERS

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

[github-actions]

Open PR overlap check

Base branch: v6

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

No conflicting open PRs or same-file overlaps were found.

[hivecommons-hive]

Read the handler, its helpers and the producer side at v6; this looks correct to me.

• The owner gate is the same verified-role check the package already uses: knowledgeListStates (api_knowledge.go:217-231) calls requireOwnerRole (api_agent_control.go:520-527), which demands both X-Hive-Role owner and the server-only verified marker — identical to what knowledgeIncludeStates checks at api_knowledge_toc.go:45. The difference (403 vs silent clamp) is deliberate and stated in the code comment. ?state=approved alone never triggers the gate, so non-owner callers of the existing endpoint are unaffected.
• The consumer query matches the producer: IngestRetroLesson at src/pkg/knowledge/retro_lesson.go:98,107-108 writes retro,lesson,review-feedback and StateDraft for FromReviewFeedback lessons, so state=draft&tag=retro,review-feedback finds exactly those. filterFactsByAllTags is an AND over tags, which is what the dashboard count relies on.
• data.total in fetchKnowledgeReviewDrafts is served by the handler (api_knowledge.go:203), and viewerIsOwner() already exists in index.html, so the UI only ever requests the gated list as an owner.
• go build ./pkg/dashboard/ ./pkg/hivectl/... is clean at 074bb31; CI test shards are green.

Refs #14551 is the right link form here — the body names what remains (B1–B6, B10–B12) and this PR is child 4 of that decomposition. The red govulncheck is GO-2026-6860 (#14731), not this diff.

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

[hivecommons-hive]

⏸️ CI is red on the base branch (govulncheck (known vulnerabilities)); holding until it recovers — this is not a failure in this PR, so no fix attempt is counted and no one needs to act here.

[hivecommons-hive]

Looks correct to me; read the handler and its callers at head 3f3b3e7, go build of pkg/dashboard, pkg/hivectl/commands and pkg/knowledge is clean, and CI (incl. dashboard server-tests) is green.

• The owner gate is consistent with the existing opt-in: knowledgeIncludeStates (src/pkg/dashboard/api_knowledge_toc.go:40-48) checks the same X-Hive-Role + verified header and silently clamps; the new knowledgeListStates (api_knowledge.go:215-230) checks via requireOwnerRole (api_agent_control.go:520-527) and refuses with 403. Refusing rather than clamping for an explicit state= is the right call — a caller who asked for drafts and got approved facts would misread the result.
• state=all → ParseLifecycleStates (pkg/knowledge/lifecycle.go:47-48) expands to every state, so it correctly trips the owner check too.
• Running knowledgeListStates before ensureKnowledge() (api_knowledge.go:163-170) means a non-owner asking for drafts gets 403 even when knowledge is disabled, so nothing about state is learnable from the enabled/disabled split. Fine.
• fetchKnowledgeReviewDrafts() (static/index.html:32464) short-circuits on !viewerIsOwner(), so non-owners never issue the gated request and never see a 403 in the console.
• Body matches the diff; Refs #14551 names the remaining B1–B6/B10–B12 work, so the non-closing link is correct.

No defects found.

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

[hivecommons-hive]

Evidence bundle `#147383f3b3e7` sha256:6ff840669a8ead85e7789242ffe765ab29b2d9a7af865434c3adca16c54e8ba3 — download from the dashboard or `hivectl review evidence #14738`.

[github-actions]

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

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