Skip to content

🐛 fix(taskmcp): knowledge answers multi-word queries and serves full bodies - #16919

Merged
hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/task-mcp-knowledge-query
Nov 6, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:fix/task-mcp-knowledge-query

Conversation

@Danathar

@Danathar Danathar commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Summary

Worker agents look up the hive's knowledge for their task with the task MCP knowledge tool, and most lookups came back empty. A fact that was found had its body cut off after 200 characters. The tool now returns what the knowledge store's own search finds for the task's repository, with each fact's complete body. repo_conventions now returns facts typed conventions whatever their text says. Both tools now check the page they read for a body against the repository and approval rules, which repo_conventions did not do.

What went wrong

The tool kept a fact only when the whole query was one unbroken piece of the fact's title, its first 200 characters or its tags. The knowledge store's own search had already found the fact. The tool threw it away.

Example: one approved fact for the task's repository, titled "Git workflow". Its body is 380 characters and first says "rebase" at character 303.

Query Before Now
Git workflow 1 fact 1 fact
rebase nothing 1 fact
git rebase workflow nothing 1 fact
how changes reach main nothing 1 fact

The one fact that did come back carried 203 of its 380 body bytes and ended in "…". No tool returned the rest. It now comes back whole.

What changes

  • Queries. A hit of the knowledge store's own search is kept as it is. The task MCP adds only its scope rules: approved facts, tagged for exactly the task's repository, checked before the limit.
  • Earlier matches stay. A fact whose title, first 200 characters or tags contain the query text is still returned, and comes first. The store's search misses some of these. It scores a page as a whole, so a long page that says a word once falls under its floor.
  • Bodies. knowledge reads each returned fact in full, as repo_conventions already did. A body over 16 KiB is cut on a character boundary and ends with [... truncated by hive: knowledge body is N bytes, cap is 16384 ...]. The result shape does not change.
  • Conventions. repo_conventions picks facts by type or kind:conventions tag, before its limit. The word "conventions" no longer has to appear in the text.
  • Re-reads stay in scope. A body is read by slug, and a slug can exist in two knowledge channels. The page read back is used only when it is approved, tagged for the task's repository and, for repo_conventions, still a convention. Otherwise the listed fact is served with its snippet. Before, repo_conventions served whatever page the slug reached, including a draft or another repository's page.
  • Knowledge store. The full-fact read now reports the lifecycle state of the page it read. It kept the state of the listing, so a draft page read this way still looked approved.

Files

  • src/pkg/dashboard/task_mcp_phase3.go: scopedKnowledgeFacts no longer applies the text filter to search hits and takes a keep rule that runs before the limit; repoConventionItems passes isRepoConventionFact; new fullKnowledgeFact, knowledgeFactInScope and capKnowledgeBody.
  • src/pkg/knowledge/api.go: FullFact and mergeFullFact carry the lifecycle fields of the page that was read.
  • src/pkg/dashboard/task_mcp_knowledge_query_test.go: new tests for both tools.
  • src/pkg/knowledge/full_fact_test.go: new tests for the full-fact read.
  • src/docs/design/task-mcp.md: new section "Knowledge matching and bodies"; the two table rows point to it.
  • changelog.d/fixed-task-mcp-knowledge-query.md: changelog entry.

Tests

Run with -run 'ContributeMCP|TaskMCP|Knowledge' in pkg/dashboard, and all of pkg/knowledge.

These fail without the change:

  • TestTaskMCPKnowledgeFindsMultiWordQuery
  • TestTaskMCPKnowledgeFindsWordPastTheSnippet
  • TestTaskMCPKnowledgeServesFullBody
  • TestTaskMCPKnowledgeCutsOversizedBodyWithMarker
  • TestTaskMCPKnowledgeRepoRuleRunsBeforeLimitOnSearchHits
  • TestTaskMCPRepoConventionsFindsTypedFact
  • TestTaskMCPRepoConventionsLimitCountsConventionsOnly
  • TestTaskMCPRepoConventionsRereadStaysInScope: another repository's copy, a draft copy, a copy that is not a convention
  • TestFullFactCarriesLifecycleOfThePageItRead and TestFullFactFromWikiLayerFollowsThePageStatus

These pass with and without the change. They guard rules that must hold on the new code paths:

  • TestTaskMCPKnowledgeQueryNeverServesOtherRepoFact: a matching fact of another repository is not served.
  • TestTaskMCPKnowledgeNeverServesUnapprovedFact: draft, deprecated and superseded facts are not served.
  • TestTaskMCPKnowledgeRereadStaysInScope: a re-read that lands on another repository's copy, or on a draft copy, is not served.
  • TestTaskMCPKnowledgeKeepsLiteralMatchStoreSearchMisses: a lookup the store's search cannot answer still works.

The existing TestContributeMCPKnowledgeRequiresExactRepoTagBeforeLimit still passes.

🤖 Generated with Claude Code

…bodies

The task MCP knowledge tool kept a fact only when the whole query was one
unbroken piece of its title, 200-character snippet or tags, so several
words, or a word later in the page, found nothing although the store's own
search had found the fact. It served that snippet as the body.
repo_conventions used the same filter and missed facts typed conventions.

Search hits are now kept under the scope rules alone: approved, tagged for
exactly the task's repo, before the limit. Literal matches stay. knowledge
serves full bodies, cut at 16 KiB with a marker. A body read by slug is used
only when the page read passes the same rules; repo_conventions served a
same-slug draft or another repo's page before. FullFact now carries the
lifecycle state of the page it read.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 6, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

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

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

@kubestellar-prow kubestellar-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

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

hivecommons-hive Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Read scopedKnowledgeFacts, fullKnowledgeFact, knowledgeFactInScope and capKnowledgeBody in src/pkg/dashboard/task_mcp_phase3.go at 7588ccd, plus FullFact/mergeFullFact in src/pkg/knowledge/api.go and resolveLifecycleState in lifecycle.go. The mechanism the body describes is real: on v6 every fact — including the store's own search hits — had to pass the substring factMatchesQuery, so a multi-word query that the store matched was dropped. The new split (i < listed → substring filter; search hits kept as the store ranked them, task_mcp_phase3.go:138-146) fixes that while knowledgeFactInScope still runs before the limit, so the #14546 approved-only rule and the exact-repo tag are preserved. Re-reading a slug through fullKnowledgeFact and re-checking the read page against the same scope rule (lines 165-176) closes the cross-store slug hole that repo_conventions had, and the FullFact lifecycle changes make that check meaningful: mergeFullFact now carries State/Supersedes/SupersededBy from the page, and the wiki branch clears them so EffectiveState() falls back to the page's Status — consistent with how listed wiki facts already resolve. go build ./pkg/dashboard/ ./pkg/knowledge/ is clean at this head. Looks correct to me.

One small inconsistency (low): knowledgeItems caps each served body at taskmcp.MaxTextBytes via capKnowledgeBody (line 104), but repoConventionItems serves the full re-read body uncapped (line 72: Body: fact.Body). A convention page over 16 KiB would therefore go out whole from repo_conventions while the same page from knowledge would be cut with the marker. Pre-existing for conventions, but since this PR introduces the cap it would be cheap to apply it in both places.

CI note for the maintainer: the red test check is shard test (agent 2/5) failing TestRestart_CancelsPendingAsyncKick (kick_cancel_test.go:299, "tmux session hive-worker not found") in pkg/agent, which this PR does not touch — looks like an environment flake rather than this change.

stage 080-awaiting-merge-admission → 072-returned-to-contributor: check-failure

Review findings from reviewer (folded here because this head already carries its hive review):

Read the diff against the v6 tree and the callers in task_mcp_phase3.go; this looks correct to me.

  • scopedKnowledgeFacts (src/pkg/dashboard/task_mcp_phase3.go:122-158): knowledgeFactInScope (approved + exact repo: tag) runs on every fact before the limit break, and factMatchesQuery is applied only to the listing half (i < listed), so store search hits survive multi-word queries while the pre-existing literal match still runs for listed facts. The seen dedup still keys on layer/slug, so a fact kept from the listing is not re-added from the search hits.
  • fullKnowledgeFact (:166-175): re-checks scope (and keep) on the page FullFact actually read and falls back to the listed fact otherwise — this closes the gap where repoConventionItems previously served whatever page the slug reached. FullFact now carrying State/Supersedes/SupersededBy from the page (src/pkg/knowledge/api.go:961-966) and clearing them on the wiki-layer path is what makes that re-check meaningful.
  • capKnowledgeBody (:309-320): the marker is subtracted from the budget first and the cut walks back to a utf8.RuneStart, so the result stays ≤ taskmcp.MaxTextBytes and never splits a rune.

One note, not a defect: repoConventionItems (:66-73) still serves fact.Body uncapped. The new design doc says the cap applies to knowledge only, so this is documented as deliberate — just flagging it in case the intent was to cap both.

Evidence bundle `#169199997795` sha256:33c545c47add898792c8eab6123788d211c9f195cb0eebe630f92fbd5c1250c2 — download from the dashboard or `hivectl review evidence #16919`.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified the mechanism against the v6 tree rather than the diff alone.

The defect is real. At the base, scopedKnowledgeFacts appends the store's search hits to the unfiltered listing (task_mcp_phase3.go:120-126) and then runs every element through factMatchesQuery (:133), which is a single strings.Contains of the whole query against title + body + tags (:283-290). So a hit the store found by term scoring was discarded unless the literal phrase also appeared in the listed snippet — exactly the "rebase at character 303" case in the table. The new i < listed split keeps that literal filter for listed facts only and trusts the store's hits; the append order those indices depend on is unchanged.

Conventions. At the base isRepoConventionFact ran in repoConventionItems after scopedKnowledgeFacts had already applied limit with the literal word "conventions" as the query (:62-66), so a typed fact with no such wording never arrived, and non-convention facts consumed the limit. Passing it as keep before the limit fixes both.

Lifecycle on re-read. FullFact is called from exactly one place in the tree (task_mcp_phase3.go:69 at base — confirmed by grepping src/ for .FullFact(), so copying State/Supersedes/SupersededBy from the page in mergeFullFact and clearing them on the wiki path cannot change any other caller's filtering. With them cleared, resolveLifecycleState (knowledge/lifecycle.go:64-78) derives the state from the page's Status, and fullKnowledgeFact re-applies knowledgeFactInScope/keep on the result — a cross-store slug collision now falls back to the listed snippet instead of serving another repo's or a draft page.

capKnowledgeBody. taskmcp.MaxTextBytes is 16 KiB (crux/taskmcp/taskmcp.go:38); the marker is well under 100 bytes, so cut stays positive and the utf8.RuneStart walk-back is safe.

Looks correct to me. Test list in the body matches the tests in the diff; I did not wait on the still-running CI shards.

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

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • check-failure

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (12 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Check report (hive scanner, read-only — fork branch, nothing pushed) for head 7588ccd.

The red test (agent 2/5) (and the downstream test / coverage aggregates) is not caused by this diff. The only failure is crux/agent.TestRestart_CancelsPendingAsyncKick, 3/3 runs, at kick_cancel_test.go:299:

follow-up SendKickAsync = (false, tmux session hive-worker not found), want a queued delivery

This PR changes nothing under crux/agent (files: pkg/dashboard/task_mcp_phase3.go, pkg/knowledge/api.go, tests, docs, changelog), and the same shard is green on v6 at fe043a2, 0033d8c and d3c9ce9. The test depends on a runner-side tmux session (hive-worker) that was not present on this job — an environment flake, not a code cause. The branch is 2 commits behind v6; an update-branch/rebase (or a fresh run) is all that is needed to re-roll the shard. Nothing in this diff needs changing. Deferring.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

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

…query

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <Danathar@users.noreply.github.com>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the new scopedKnowledgeFacts path and FullFact against the v6 tree; the change looks correct to me.

  • The listed boundary (src/pkg/dashboard/task_mcp_phase3.go:128,146) is what fixes the multi-word case: factMatchesQuery is applied only to indices below listed (the unqueried listing), while search hits appended at :134 pass through knowledgeFactInScope only. seen is set only when a fact is kept, so a listing row dropped by the text filter does not shadow the same slug arriving as a search hit.
  • The scope rule (approved && factForRepo) runs before the limit break, so TestContributeMCPKnowledgeRequiresExactRepoTagBeforeLimit semantics survive.
  • fullKnowledgeFact (task_mcp_phase3.go:166-175) falls back to the listed fact when the by-slug read lands on an out-of-scope copy; that only works because mergeFullFact (src/pkg/knowledge/api.go:964-966) and the wiki branch (:945) now carry the read page's lifecycle. Previously a draft copy read by slug kept the listing's approved state, so repo_conventions could serve it. Good catch and the pairing is necessary.
  • capKnowledgeBody cuts on a rune boundary and the marker is included in the budget; with MaxTextBytes = 16 KiB and an ~80-byte marker cut stays positive.

Suggestion, not a defect: repo_conventions still serves uncapped bodies (task_mcp_phase3.go:72). The design doc section says only knowledge caps, so this is consistent and pre-existing, but a follow-up could apply capKnowledgeBody there too.

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

@hivecommons-hive
hivecommons-hive Bot merged commit 19f1b75 into hivecommons:v6 Nov 6, 2026
68 of 69 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant