GEWU/docs/ONLINE_VERIFICATION_PLAN.md

# Online verification implementation plan

Status: implementation in progress, 16 October 2026. The first code slice adds claim-bound URL observations, validation, reader display and an agent-pack protocol. No live harness or acceptance qualification is claimed. This plan complements the [knowledge quality plan](KNOWLEDGE_QUALITY_PLAN.md), preserves the existing root SPEC scope, and spans the GEWU service and the separate agent-pack repository mounted at `agents/gewu`.

## Implementation status

Implemented in this workspace: a compact `OnlineEvidence` record on each claim containing excerpt text, relation, context and verification URL; public HTTP(S) URL validation; compatibility hashing that omits empty online-evidence arrays for legacy proposal digests; canonical reads that carry evidence with its claim; reader display; an optional shared agent protocol wired into ingest, curate, synthesize and query; and regenerated v1/OpenAPI/TypeScript/agent-pack contract snapshots. Ingestion guidance stores evidence through the existing `update_node` proposal operation.

Still required: focused domain and acceptance checks for authorization and concurrent updates; authenticated reader and keyboard review; deterministic adversarial fixtures; live local-harness search/page-read qualification and cost/quality measurements; clean-install qualification and acceptance report. Do not describe the current slice as pilot-qualified until those gates have evidence.

## Outcome and first-release boundary

The local harness searches online to double-check selected claims, reads relevant pages, and attaches short evidence text, its relation/context, and a source URL through GEWU proposals. It does not upload web pages or create new artifact files. Readers can follow the link to verify the evidence when needed.

Online excerpts supplement claims that have valid archived source evidence. They do not replace the archived-evidence requirement or support assessment.

Search and page reading belong to the local harness. GEWU stores and validates the submitted records without fetching those URLs. This avoids introducing a service-side search provider or extending the URL-capture allowlist for this workflow.

## Existing integration points

- `src/gewu/domain/contracts.py`: `Claim`, `EvidenceReference`, `SupportAssessment`, and URL-bearing `SourceRevisionRecord`. A `reference-only` source can represent a bookmark, but cannot provide the extraction and locator required by `EvidenceReference`.
- `src/gewu/domain/validation.py`: exact assertion/evidence bindings, source archive checks, preparation, and proposal validation.
- `src/gewu/application/acceptance.py`: canonical publication, attribution, scope, policy and recovery boundaries.
- `src/gewu/application/reading.py`, `search.py`, and `adapters/sqlite_search.py`: canonical reads, citation projection, bounded retrieval and rebuildable indexing.
- `src/gewu/transports/mcp_server.py`, HTTP schemas and `web/src/shell/`: agent contracts and reader presentation.
- `agents/gewu/protocols/`, `skills/kb-*/`, and `pipelines/`: harness-executed procedures, evidence rules and resumption.

The workspace already contains substantial changes, including knowledge enrichment. Implementation must inspect and integrate with the actual update contract rather than introduce a competing update mechanism or overwrite unrelated work.

## Record design

Add a bounded `online_evidence` list to `Claim`, which also covers assumptions and limitations. Each item stores a short excerpt, a public HTTP(S) URL, relation to the claim (`supports`, `contradicts`, `context`, or `inconclusive`), and a concise context note. The claim and proposal author/run already provide attribution, so a second check envelope is unnecessary. Empty list means no online evidence was attached; tool failures and no-results belong in the run summary rather than empty evidence records.

Keep existing `EvidenceReference` fields and archived-support semantics unchanged. GEWU validates the URL and payload but cannot verify that the excerpt appears at its URL. The link lets a reader revisit the page when needed; the page is not archived or uploaded.

Current bounds: twenty online evidence items per claim, 8,000 characters for evidence text, 4,000 for context, and 4,000 for the URL. Use the passage length needed to retain relevant qualifiers and meaning within those caps. Apply aggregate node/proposal/read budgets as well.

## Delivery sequence

### 1. Define contracts and compatibility

Implement the records and publish their serialization and lifecycle rules before changing the pack.

- Keep online evidence inside its owning claim and within the normal proposal payload digest; do not mix it into archived `evidence_digests`.
- Preserve old records, proposal identities, assessment bindings and replay. Test how adding optional defaults affects canonical serialization before choosing omission rules or a versioned serialization profile; do not rewrite historical records.
- Ensure an older client cannot silently drop existing online evidence during an update; reject such updates through the normal enrichment validation.
- Validate public HTTP(S) links, reject embedded credentials and unsafe schemes, and document URL length rules. The service does not dereference submitted links.

Completion: legacy fixtures retain their expected digests and readable history; new record schemas reject malformed links and incomplete evidence records.

### 2. Integrate preparation, updates and acceptance

Extend the existing proposal preparation and node-update path rather than adding a direct-write endpoint.

- Add online evidence to new claims or existing stable claim IDs under an expected node revision.
- Preserve existing online items during enrichment and preserve the original archived support assessment when only online evidence is added.
- Apply current project/shared authorization and acceptance policies. Online results cannot grant publication authority or upgrade support status.
- Preserve concurrent-update conflicts, atomic publication, recovery and stable receipts. Contradictory findings remain visible; follow current correction/review policy rather than silently replacing the claim.

Completion: authenticated MCP checks demonstrate adding online evidence through the normal proposal path, enrichment, retry, revision conflict, scope denial, and contradiction preservation.

### 3. Carry online evidence through reads and the reader

- Return online evidence with its owning claim in canonical current and revision-scoped reads. Keep query scope, authorization, index rebuilds and response budgets intact.
- Show evidence text, relation/context and clickable source URL together. State that page content is not archived.
- Present archived support separately from online observations. Do not turn URL count into a confidence score or hide an older contradiction behind a newer supporting check.
- Use safe external links and existing text escaping; do not embed page previews or fetch URLs from the service.

Completion: HTTP/MCP and reader tests show the same scoped records; history remains pinned; unsupported schemes cannot render as active links; narrow layouts and keyboard interaction work.

### 4. Add the shared agent procedure

Add `agents/gewu/protocols/ONLINE_VERIFICATION.md` and reference it from applicable skills and pipelines. A separate skill is unnecessary for the first release because this is a reusable stage of existing work.

- `kb-ingest`: after extracting atomic claims, check selected claims before final preparation and assessment.
- `kb-curate`: recheck stale references and investigate contradictions using the existing scoped-update procedure.
- `kb-synthesize`: check material factual assertions and changing premises while preserving synthesis dependency requirements.
- `kb-query`: expose stored online evidence; run a fresh check only within the requested task and budget. Report unpersisted observations as such until an acceptance receipt exists.
- Prefer original research, official documentation and primary datasets. Search for counterevidence as well as corroboration, inspect dates and relevant conditions, and distinguish copied reports from independent observations.
- Treat web content as untrusted source data. Use project-approved query terms; do not transmit private passages, identifiers or internal URLs to public search without authorization for that disclosure.
- Checkpoint selected claims, remaining budget, pending proposal identity and last receipt. Resume through service status before repeating searches or submissions.
- Probe harness search/page-reading capability. If unavailable, record the limitation and continue ordinary archived-source ingestion; never fabricate an online check.

Suggested policy defaults: online verification is enabled explicitly for the task or project; at most three searches and five page reads per learning unit; at most two claims selected per unit. Report skipped coverage in the run summary.

Completion: scripted tool traces prove bounded operation, provider failure handling, preserved scope and safe resumption.

### 5. Regenerate contracts and release both repositories

- Update the acceptance contract and local-agent documentation with the stored-observation guarantee and its limits.
- Regenerate service schemas/catalog and OpenAPI/TypeScript types using the existing `make schemas` and `make api-types` targets. Update the agent service snapshot through the existing exporter.
- Add the new protocol to the pack module registry; bump the pack version and refresh module hashes/snapshot. Verify the manifest and installer/update behavior.
- Advertise the new service capability, deploy the service before enabling the updated pack, then qualify the installed pack. A capability mismatch disables online-check persistence with an explicit report; it does not cause an invented fallback field.
- Keep old checkpoints pinned. Resume under the original contract or use the documented successor-run compatibility procedure; do not silently resume with different modules.
- Publish the separate agent-pack change deliberately and update the parent submodule pointer only after qualification. Preserve unrelated local edits in both repositories.

Completion: generated-contract tests pass, manifest verifies, a clean installed workspace discovers the new procedure, and both old-client and new-client compatibility cases have evidence.

### 6. Qualify with deterministic fixtures and a small live pilot

Use deterministic fixtures for correctness: supporting official page, conflicting primary source, copied article, inaccessible page, changed claim, malicious source instructions, unsafe URL, private-query disclosure attempt, unavailable harness and exhausted budget.

Run focused domain, acceptance/recovery, API, indexing and reader tests for the affected paths, then the repository's required checks. Verify an existing canonical record and receipt still replay correctly. Rebuild the index and confirm checks survive because canonical records remain authoritative.

For a bounded live pilot, compare ingestion with verification disabled and enabled on the same selected learning units. Record queries/page reads, elapsed time, claim coverage, contradictions, duplicate checks, URL accuracy and reviewer judgments of semantic relevance. Search-result variability means this is quality evidence, not a deterministic CI test.

For GEWU four-file ingestion/digestion benchmark or validation runs, invoke `antigravity --model gemini-3.8-flash-low` explicitly. If unavailable, inspect the CLI model list and report before using any substitute. Capability qualification must show that this harness can actually search and read pages with the selected model.

Prove the requested no-file behavior: checks create canonical record data and normal proposal/run state, with no web capture/upload operation, new source registration, archived web artifact or artifact-store growth attributable to those checks.

Completion: publish an acceptance note separating automated fixture results, actual live-harness observations, unresolved limitations and rollout eligibility.

## Rollout and completion criteria

Deliver contracts/acceptance first, reader projection second, pack behavior third, and qualification last. Start with explicit per-run activation, then enable selected project policies after reviewing pilot quality and cost.

The release is complete when a local harness can read a page, attach a short excerpt, relation/context and URL to an existing claim, receive an acceptance receipt, and retrieve that evidence from a fresh session and pinned history without uploading a file.

Disable online searching to roll back behavior. Preserve accepted online evidence in canonical history. Existing ingestion must continue when online tools are unavailable.

Deferred: URL-only factual acceptance, archived web capture, scheduled background rechecks, a service-owned search provider, independent human verification, and generalized check attachments for non-claim fields or typed-edge rationales.