GEWU/docs/acceptance/2026-10-16-knowledge-quality-demo.md

# Knowledge quality implementation and demo report

Date: 16 October 2026  
Status: the demo records, search-budget fix, and automated checks pass; autonomous ingestion and the broader qualification plan remain open.

## Problem addressed

The live-store review recorded in [the plan](../KNOWLEDGE_QUALITY_PLAN.md) found empty classification facets, one citation per node, short explanations, no typed knowledge links, and source excerpts without contextual navigation. The change tested the service and agent workflow against those failure modes without editing the production corpus.

## Delivered in this slice

- Added the additive `update_node` proposal operation. It preserves stable identity, lifecycle, prior claims and evidence, and requires the proposer to assess new evidence. Facets may be added without silently replacing existing material. The installed GEWU_agent contribution protocol documents the behavior.
- Corrected project-only source registration and policy scoping, so a project-scoped agent can register sources for that project while shared writes remain separately authorized.
- Fixed strict JSON parsing in prepared edge evidence.
- Added contract/schema/type exports and refreshed and verified the installed agent pack.
- Created a private demo project, synthetic four-file corpus (two PDFs, HTML, Markdown), and separate viewer/agent credentials. The project and credentials are intentionally retained for the user's UI review. No credential values are included here.
- Accepted five richly described, classified knowledge nodes, one evidence-backed typed relationship, and seven source revisions across PDFs, HTML and Markdown. The existing authoring-cost node was enriched in place with eleven page-7 evidence spans from a second PDF; stable identity and prior claims were preserved.
- Verified source locations from node citations. Text sources open the stored passage; PDF citations expose page 1 and the exact extracted quote. This is page-and-excerpt navigation, not a native PDF visual highlight.

The fixtures are explicitly synthetic and do not establish real-world research findings. The agent read the exact four source blocks using the required Antigravity model pin `gemini-3.8-flash-low`. A combined agent proposal turn timed out; after validating those passages and offsets, proposals were completed with the authenticated typed MCP workflow. This validates the contract and resulting records, but does not count as a successful end-to-end autonomous agent ingestion run.

## Demo record and benchmark

Persistent project: `narrative-knowledge-demo`. The original durable run `kb-quality-demo-20261016-01` remains completed at revision 7. Follow-up runs added a Riedl narrative-analysis node, enriched the existing authoring-cost node from the empirical study, and added a WhatIF authoring-tool node. The current project has five nodes, one edge, and seven source revisions. The new Riedl node has three supported claims with fifteen exact PDF page citations. The authoring-cost update preserved the stable node ID and added one distinct claim supported by eleven page-7 excerpts; the source reports twelve participants and measures authoring time, clicks and perceived difficulty while comparing SG and IBT, with its study limits retained. The WhatIF node has two claims with eight HTML text-span citations and records the source's small study samples and limits. All five nodes have tags, audience, use and domain facets.

A six-question hand-authored smoke set returned its intended target first for all six questions at an 8,000-codepoint budget after the compact-search fix. Results used 4,048–6,489 codepoints; warmed median search latency was 6.3 ms, with a 1.33 s first query while the local index initialized. These questions are not blind or independently judged and do not establish general retrieval quality. The previous full-evidence response for the empirical-study query used 28,143 codepoints and could not fit at 8,000; the compact response uses 6,489 codepoints. Compact rows retain claim text and per-claim evidence counts, and omit citation quotes. Full citations remain available by setting `include_evidence=true` or opening the canonical node. The API retains full-evidence behavior by default for compatibility.

The authenticated graph endpoint returned all three nodes and the accepted edge. The UI initially showed an empty graph because the graph request was never started when the tab opened; adding the load effect then exposed a race with unrelated reader requests sharing one generation counter. Graph loading now has its own request generation and starts on initial/direct graph routes as well as tab selection. A regression test covers tab activation, and the shared UI preview now shows **3 nodes · 1 link**.

## Verification

Completed checks after the search-contract change: `./scripts/python-tool pytest -q` passed (239 tests); `npm --prefix web run check` passed TypeScript, ESLint and all 30 web tests; `./scripts/python-tool mypy src` passed; generated OpenAPI, MCP contract, agent manifest and TypeScript exports verified. The backend health endpoint previously returned 200.

Earlier on this date, the full web check had six failing UI tests. The current check passes all 30 tests; those failures are resolved in the current workspace.

## Remaining qualification work

## Extended source-batch attempt (16 October 2026)

To test beyond the original synthetic four-file corpus, seven additional inputs were prepared under `.data/gewu/demo-workspace/Inbox/More/`: four published research documents (three PDFs and one HTML page), the pinned Ink Markdown guide, a field-overview PDF, and a synthetic WebVTT locator fixture. Local extraction using the production `LocalSourceExtractor` succeeded for all seven; the VTT parser returned four timestamped cues. The source index records origin, scope, intended review questions, and SHA-256 digests. The VTT file is explicitly a locator test fixture and is not research evidence.

The user authorized creation of a new demo-scoped ingest credential and use of GEWU_agent. Antigravity was pinned to `gemini-3.8-flash-low`. Diagnostics, project context, and `run_status` succeeded. The durable run `run-demo-20261016-narrative-01` is active at revision 0. Initial MCP calls exposed two argument/scope errors: `run_create` rejected `scope.project_ids` and required `scope.projects`; `list_sources` was called with `include_shared: true`, outside the project authorization. Although a corrected continuation was started, the CLI spent its time repeatedly reading out-of-workspace files and did not reach source capture before it was interrupted. It did not capture or register any of the seven sources, submit proposals, or produce acceptance receipts. Therefore, this batch adds no accepted knowledge and is not counted as an end-to-end agent ingestion success.

The retained database remains at the verified baseline of three accepted nodes, one typed edge, and four source revisions. No existing records were deleted or replaced. The seven source files remain available in the demo workspace. Since no batch was accepted, the prior five-question retrieval smoke score and existing source-navigation results remain the only measured benchmarks; no new benchmark score is claimed.

## Scope-instruction repair and retry (16 October 2026)

The previous blanket instruction to include shared scope for every source was incorrect. Backend validation uses the source's explicit `ingested_for` domains: a source registered for this project alone affects only the project's policy and can be accepted with `scope.include_shared=false`. The demo credential therefore remains project-only; adding `shared` to its grant list would also grant this agent shared write authority. The GEWU pack is updated to v0.20.16: ingestion instructions now require explicit project-only scope by default, document the correct `run_create` request field (`scope.projects`), and distinguish response-size budgets from provider context. The installed pack manifest and local install integrity hashes were refreshed and verified.

Focused backend verification passed: `test_project_only_source_registration_does_not_write_shared_knowledge`. A fresh Antigravity run, pinned to `gemini-3.8-flash-low`, passed diagnostics, project context, run creation, and project-only source listing. It still did not upload the selected Riedl PDF. The agent then attempted to read old repository reports/tests outside the research workspace and requested permission to run a shell command that would inspect Antigravity MCP configuration; that command was denied. No credential/configuration contents were exposed by the denied command. The initial run `run-demo-20261016-narrative-01` remains active at revision 0; the fresh run `kb-more-riedl-20261016-01` was created for the one-source retry. Neither has accepted source or proposal receipts. The agent still needs a host-level connector discovery/call correction before the ingestion and benchmark request is complete.

- Complete structured explanation sections (including evidence-bound math, figures, and safe rendering); the current records contain richer claim/evidence content but not the planned structured content format.
- Native PDF source archival, multicolumn/page-coordinate mapping, and geometric highlights; current demo supports page plus exact extracted quote fallback only.
- Run actual autonomous ingestion and curation through the installed GEWU_agent with the pinned model, without proposal harness completion; diagnose the combined-turn timeout and demonstrate resume/retry behavior.
- Build a frozen, independently scored withheld benchmark and compare repeated/reordered runs, multiple principals, authorization failures, reliability, cost, and larger corpus latency. Current five-question run is smoke evidence only.
- Run the installed GEWU_agent autonomously through capture, evidence-grounded proposal, evaluation and accepted receipt. The manual typed-MCP acceptance path works, but the bounded autonomous retry below timed out without an agent report.
- Build a frozen, independently judged retrieval benchmark; the six-question run is only a smoke benchmark. The separate four-file qualification, protected owner decisions and reserved/repetition phases remain open and must retain their original gates.
- Complete native PDF page rendering/highlights and the remaining browser, boundary, security, migration, VPS and production-corpus qualification gates.
- The four-file release qualification, VPS deployment, and existing production corpus migration have not been performed.

## Compact search response and bounded retry (16 October 2026)

The response-size limit is measured as canonical-JSON Unicode codepoints, despite the `budget_tokens` field name. Search used to repeat every citation inside the node's claims and again in the envelope-level citations array. The API now has an explicit `include_evidence` option. Its default remains `true` for existing callers. With `false`, claims retain their text and `evidence_count`, the result row marks `evidence_included: false`, and citation quote payloads are omitted. The GEWU `kb-query` skill now requests compact search, then calls `get_node` before citing or inspecting the strongest result. The benchmark runner follows the same contract. Full source excerpts, exact PDF page labels and claim-to-evidence relationships remain available in the canonical node read.

For the authoring-study query, compact search returned one node in 6,489 codepoints at an 8,000 budget. Full-evidence mode used 28,143 codepoints at 50,000 and returned no node at 8,000. This closes the response-fit defect for the tested query while preserving full-evidence API behavior by default. It does not change the budget unit into model tokens.

The GEWU pack was bumped to v0.20.19, the query instructions and MCP/OpenAPI contracts were refreshed, and the updated pack was installed in the retained demo workspace with the previous copy backed up. The Antigravity CLI lists the required `gemini-3.8-flash-low` model. A one-source autonomous retry was started with that explicit pin, project-only scope and strict workspace boundaries; it produced no response within the 120-second print window and its local process was stopped. The canonical database head remained `a236bfe205f63b19e10305582d1eb86d9c72586a`, so the retry added no source or proposal. The successful source additions and existing-node enrichment documented above were submitted and accepted through authenticated typed MCP, not through a successful autonomous GEWU_agent turn.