fix(coding-agents): exclude external facts from knowledge pages - #3484
Open
Sanderhoff-alt wants to merge 1 commit into
Open
fix(coding-agents): exclude external facts from knowledge pages#3484Sanderhoff-alt wants to merge 1 commit into
Sanderhoff-alt wants to merge 1 commit into
Conversation
Sanderhoff-alt
force-pushed
the
fix/knowledge-page-external
branch
4 times, most recently
from
August 14, 2026 10:15
d89ae89 to
cb5d086
Compare
Add knowledge:external as an explicit entity-label value for facts whose subject is another project's own implementation, configuration, or decision. The label guidance makes external mutually exclusive with the five normal project-knowledge categories, while dependency decisions about this project remain in the normal categories. Give every seeded Knowledge Page a compound refresh scope that requires its normal knowledge:* label and excludes knowledge:external. The exclusion is implemented with deterministic tag groups, not source text. Make page seeding idempotently repair existing pages by matching names and PATCHing only missing or changed triggers. Existing page IDs, content, and synthesized history are preserved. Expose the existing backing mental-model trigger through the Knowledge Base API, including tree responses and PATCH updates. Explicit trigger:null is rejected with a clear 400 response instead of becoming a silent no-op. Decode string-valued JSONB and CLOB triggers before building KnowledgeNode responses, and compare plugin tag groups with key-order-independent JSON. Use generated SDK models through the Python wrapper's from_dict mapping so nested tag_groups are preserved for mental-model and page operations. Add regression coverage for database response decoding, null-trigger rejection, key-order-independent page synchronization, and all nested Python mappings. Add knowledge-base update --trigger <JSON> to the CLI, including nested tag_groups, and regenerate the OpenAPI contract and client documentation. Keep older plugins and older servers compatible: clients ignore an unknown tree response field, and page synchronization skips unsupported newer operations. Validate with the full knowledge-base tests, coding-agents tests, Python wrapper tests, CLI coverage, OpenAPI compatibility, client generation, docs generation, lint hooks, and whitespace checks.
Sanderhoff-alt
force-pushed
the
fix/knowledge-page-external
branch
from
August 14, 2026 10:23
cb5d086 to
79fe095
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Knowledge Pages can currently summarize a dependency's implementation or decisions as if they belonged to the repository being worked on. This happens because document attribution records where a fact was captured, but does not identify what project the fact is about. This PR adds an explicit external-knowledge classification and prevents those facts from entering the repository's standard Knowledge Pages.
Fixes #3476
What changed
The coding-agents plugin adds
knowledge:externalto the entity-label vocabulary. The extraction guidance says to use it only when the fact is about another project's own implementation, configuration, or decision. A decision about how the current repository uses or integrates a dependency remains normal project knowledge. The external label is explicitly exclusive with the otherknowledge:*categories.Each seeded Knowledge Page now refreshes from its normal category tag and excludes
knowledge:externalwith a deterministic compound tag filter. The exclusion is therefore enforced by the refresh query instead of relying on wording in the page's natural-language source query.Existing pages are upgraded in place. On startup the plugin reads the Knowledge Base tree, matches the fixed root pages by name, and patches a page only when its trigger is missing or different. Page IDs, existing content, and synthesized history are preserved. New pages receive the trigger when they are created, and repeated startup runs are idempotent.
The Knowledge Base API now exposes the page trigger in tree responses and accepts an optional
triggerfield in node PATCH requests. The route forwards that field to the existing backing mental-model update logic. The field is optional, so older clients and older page behavior remain compatible.The CLI now exposes the same capability as
knowledge-base update BANK NODE --trigger <JSON>. The argument accepts the complete trigger object, including nestedtag_groups, and is included in the CLI OpenAPI coverage check.The Rust SDK does not commit generated source files. Its
build.rsgenerates the models fromhindsight-docs/static/openapi.jsonat build time, soKnowledgeNode.trigger,UpdateNodeRequest.trigger, and nested trigger tag groups are available after rebuilding. The service's native MCP has no Knowledge Base CRUD operation, so it has no corresponding parameter to add. The coding-agents MCP also keeps page CRUD internal to the plugin.The OpenAPI specification and generated Python, TypeScript, and Go clients are updated together with the control-plane types and wrappers.
Compatibility
The deprecated per-harness plugins continue to use their existing mental-model endpoints and are not changed by this PR. They remain operational, but they do not automatically gain the new external classification. The current unified plugin upgrades pages created by earlier versions of that same plugin when the server exposes the trigger field. Historical facts are not reclassified automatically; newly extracted facts use the new label.
When an older server does not expose the Knowledge Base surface, the plugin treats 404, 405, and 501 responses as an unavailable optional capability. It skips page creation or upgrade and continues with bank configuration and memory operations. Older servers that return a tree without
triggerare not sent a trigger PATCH, so their existing page behavior is preserved.Verification
The coding-agents test suite passed with 504 tests, including 31 Knowledge Page tests. The CLI trigger parsing test passed, the CLI compiled successfully, and the OpenAPI coverage check reported all 89 operations and 115 request parameters covered. Client and documentation generation, repository lint hooks, and whitespace checks passed. The server Knowledge Base integration tests were not run because this temporary worktree does not include
pg0-embedded, so its test database cannot start.