GEWU/docs/LOCAL_AGENT_IMPLEMENTATION_REVIEW.md

Lessons from Jev and SCAR/Winnow for KB

12 October 2026 · Implementation and skill review · Companion PRD: 0.6

Recommendation

Build KB as its own service, borrowing Jev's shared-runtime engineering and Winnow's research procedures. Local agents remain the reasoning layer. KB owns canonical sources, schemas, scope, durable proposals, automatic acceptance policy, retrieval and the read-only web application. Neither reference implementation provides KB's complete evidence-and-acceptance boundary today.

Use patterns and selectively port small utilities after testing their assumptions. Do not make KB depend on Jev's semantic provider, lifecycle hooks, or Winnow's direct access to the canonical vault.

Review scope and evidence

Reference	Snapshot inspected	Evidence boundary
Jev	D:/01_GIT/Jev, HEAD bca82bb245389dc3ccdcef516878f33b11b71d47, with substantial existing modified/untracked implementation and test files	Findings describe the current working tree, not just that commit. Read contracts, registry, MCP transport, knowledge/verification/context code, storage claims, installer, diagnostics, selected tests and acceptance records.
SCAR/Winnow	D:/07_RESEARCH/SCAR/.agents is a symlink to .opencode; owning configuration repo HEAD d67763617a5c9f16689332737878e4d81b9c9f99, with clean reported status	Read canonical skills/protocols and source-processing wrappers/scripts. Skills are instructions for an external agent; a section called “State Machine” is not evidence of a persisted execution engine.
Current-turn probes	Eight isolated Python probes, with temporary files/SQLite and no provider calls	Results. No live MCP/harness, real PDF quality, VPS upload, concurrency or complete test suite was exercised.

The reference repositories were not edited or installed. A command-scoped safe.directory setting allowed read-only Git inspection of the administrator-owned Winnow configuration repo; no global Git settings changed. Existing Jev acceptance documents were read as historical records, not treated as current live verification.

What to take from Jev

Pattern and implementation evidence	What is already useful	Application to KB
Tool registry and MCP adapter	Tools declare handlers once and MCP exposure is generated. The probe resolved all eight registered tools to handlers.	Use one versioned operation catalog with request/response schema, read/propose/maintenance capability and allowed transport. HTTP exposes reads; MCP exposes proposals. A mutating flag alone is not authorization.
Neutral contracts	Core contracts carry workspace/session/agent/invocation identity and explicit capabilities.	Keep KB requests independent of harness-native events. Include project, run, proposal, source revision and authenticated actor; keep self-reported harness/model separate from authorization.
Context envelope	Current request, session objective and project goal are separate; output is bounded.	Supply local agents with explicit H1/H2 plus authoritative project context/H3 from KB. Avoid uploading entire transcripts. Never infer canonical project identity or owner intent from cwd or the first prose line of a README.
Replay claims	Claims use identity, operation digest and policy version. Same-operation replay and changed-digest re-evaluation were observed.	Adapt to proposal IDs plus payload digest/base revision/schema/policy versions. Add fencing for stale workers and atomic git/receipt recovery. Jev's single-process probe does not establish those stronger guarantees.
Owned config merge	The merge function preserves other MCP entries and existing skill paths; the installer has backup/manifest/uninstall machinery.	A KB connector installer should change only owned entries, preserve other tools, record installed versions and offer a copy/configuration fallback where symlinks are unavailable. Review exact rollback behavior before code reuse.
Diagnostics and acceptance protocol	Paths, identities, registered capabilities and explicit per-harness evidence are exposed.	Add diagnostics for service identity, local/VPS endpoint, authenticated capability, selected project, schema/skill versions, transfer limits and index lag. Separate “configured,” “connected,” and “workflow passed.”
Knowledge presentation tiers	Stronger matches can supply content; weaker ones become lightweight hints.	Adopt progressive disclosure: concise search cards, full nodes and bounded neighbors. Keep relevance separate from evidence confidence. Hooks that auto-inject content remain optional P2.

Jev behavior not suitable for direct reuse

1. The verifier is advisory, not an evidence gate. evaluate_verification returns verified: true with support_level: extrapolated when reference context or the provider is absent, and similarly on provider error. The missing-reference behavior was reproduced. KB must return pending/unavailable and hold acceptance when a required check is missing. Retrieval can degrade to keyword search; evidence validation cannot degrade into success.
2. Knowledge writes bypass the required KB boundary. learn creates/updates files directly, chooses a potential existing item using model confidence and appends prose. A direct call succeeded with empty evidence. knowledge_learn also catches audit-record failures after writing. KB needs complete proposal bundles, explicit dedupe decisions, preserved disagreements and acceptance receipts that are not best-effort telemetry.
3. Its search is a routing mechanism. The inspected path selects one item; the model candidate list is capped at 254 items. The no-provider keyword match uses ASCII word extraction and is capped at 0.69, yielding a hint. This is not multi-result, project-scoped hybrid retrieval for 100,000 nodes. Adopt the presentation idea, not this retrieval implementation.
4. Its budget is measured in characters. merge_results slices context strings to the remaining character count. The probe cut a citation mid-string. KB needs token accounting over complete serialized result groups, including citations and warnings.
5. Harness coverage is bounded. The inspected enum/adapters name Antigravity, Codex and OpenCode, not Claude. Shared MCP support may be portable, but it is not proof of all four KB client workflows. A stored Codex acceptance record reports a workspace-root mismatch; that historical issue was not retested here. It reinforces the need for explicit service/project identity and live receipts.

What to take from SCAR/Winnow

Procedure and source	Useful part	Required KB adaptation
Research pipeline	Separate intake, atomization, auditing and a final report.	External agents run these stages against MCP. Persist inputs, source revision, skill version, outputs and receipts so another agent can resume a run.
Skill template and concerns mapping	A skill declares only the protocols it needs; inputs, processing and outputs are explicit.	Maintain a portable KB skill pack with concerns such as evidence, scope, relationships, proposals and synthesis. Reference authoritative schemas rather than restating rules in every prompt.
Atomic shatterer	A source becomes reusable, linked units with traceable origins.	Produce claim/problem/technique/entity proposals with field-level evidence. Use goal relevance and bounded batches; account for skipped or deferred source sections rather than extracting every term without limit.
Concept consolidator	Preserve conflicting perspectives, explain how concepts interact, retain extracts, and redirect merged identities.	Use typed relationships with conditions and evidence. Keep separate claims/framings where they differ; merge only demonstrated duplicates. Derive incoming links instead of writing reciprocal edges into every node.
Epistemic auditor and fact grounder	Distinguish contradictions, methodological tension and claims missing references; audit statements individually.	Return structured assessments citing claim and source-revision IDs, method, assessor and rationale. Link presence is not support proof; supplementary web findings must first become checkable source captures.
Comparative matrix	Compare methodology, evidence/sample, findings and limitations; preserve agreement, discrepancy and gaps.	Use this as an external-agent synthesis skill and as guidance for web problem/solution pages. Tailor comparison fields to technical/math conditions; keep unknowns explicit.
Grounding protocol	Put citations directly beside claims, with granular locations.	Replace informal wikilink/page text with stable IDs and typed revision/location references; generate readable links from these records.

Winnow behavior not suitable for direct reuse

1. PDF extraction loses locators. pdf_conv.py concatenates page text and collapses blank lines without recording page IDs or source offsets. A two-page mocked extraction reproduced the loss of page boundaries. Keep original bytes and a page/block/span map with parser version and explicit extraction status. Real multi-column, mathematical and scanned-page quality still needs a labeled corpus; conversion success is insufficient.
2. arXiv retrieval creates cards, not an original-file archive. arxiv_fetch.py extracts metadata and links and strips the version from the separate arxiv_id field. The original URL is retained, but arxiv_puller.ts writes title-named cards; it does not download the PDF. KB must preserve versioned identifiers and source bytes when claiming an archived original. Use stable source identity rather than title-only paths, and do not overwrite reading notes on re-import.
3. Prompt instructions are not durable orchestration. The reviewed pipeline has numbered states in Markdown, but no executable state store or restart contract for those stages. KB should persist run manifests and receipts while leaving stage execution with external agents. Interrupted jobs resume from verified artifacts rather than conversational recollection.
4. Canonical sources should remain immutable. The shatterer prepends a table of contents to its input and writes new notes directly. In KB, such a table belongs in a source reading view or separate synthesis, never in archived source bytes.
5. Avoid the blanket git-safety pattern. git_safety_commit.ts stages all changes in the current repository. Its shell wrappers also interpolate file paths or messages into command strings. KB should use argument-vector subprocess calls where needed, bounded local artifacts and service-owned commits of exactly the accepted change set. Local agent skills must not stage unrelated user files.
6. Keep portability explicit. The skills share one canonical directory, but wrappers are OpenCode plugin tools and assume .opencode relative paths. Do not assume those tool names exist in Codex, Claude or Antigravity. A KB connector and skill manifest should expose the same contract through each client without requiring vault layout or symlinks.

Recommended division of responsibilities

Component	Owns	Does not own
Local KB skill pack	Source triage, atomic extraction, semantic support assessment, typed links, comparisons and synthesis proposals	Canonical writes, policy overrides, user-global safety commits
Local MCP connector	Explicit file selection/read, bounded transfer, endpoint/auth configuration and compatibility diagnostics	Reasoning, semantic acceptance decisions or independent knowledge storage
KB service	Artifact integrity, immutable revisions, schema/scope/evidence-location checks, run state, proposal policy, durable receipts, git and derived indexing	An embedded agent or unrecorded semantic judgments
Read-only web app	Search, source/quote reading, problem/solution/topic navigation, labeled related suggestions and history	Ingesting, editing, approving or generating knowledge

Initial external-agent skill pack

Use four public entry points with shared protocols and internal stages, rather than installing every Winnow writing skill:

• kb-ingest: identify source/project, capture/upload, fetch project intent, triage, extract evidence-backed nodes, assess support, propose links, submit bounded bundles and report accepted/pending outcomes.
• kb-query: retrieve scoped results, inspect evidence and neighbors, answer with citations and freshness; explicitly identify insufficient evidence.
• kb-curate: find duplicates, contradictions, stale records and orphan nodes; propose links, corrections or reversible merges under policy.
• kb-synthesize: assemble a cited comparison or guide from accepted node revisions and submit a synthesis proposal; preserve conditions, disagreements and missing data.

Each skill declares its version, compatible KB schema/tool versions, concerns, input/output contracts and resume behavior. Skills stay outside the server reasoning path. No hooks, embedded model, or automatic watcher is needed to exercise the complete v1 workflow.

Bounded acceptance recommendations

• Permit automatic acceptance of eligible additive knowledge with all required evidence/support records. A high routing confidence or a “verified” boolean from an external tool cannot substitute for the KB contract.
• Persist semantic support as an external assessment, including assessor identity, cited revision and rationale. Missing or failed assessment is pending/unavailable, not successful. The service enforces completeness and deterministic checks without claiming to independently prove meaning.
• Separate transient diagnostics from durable acceptance receipts. Optional telemetry loss must not undo accepted work; missing canonical acceptance evidence must never be silently ignored.
• Bind replay to operation content and authoritative revisions. Persist enough information outside the disposable search index to recover after reindexing or a commit/index crash. Do not assume an SQLite hook lease solves git publication concurrency.

Applied to PRD 0.6

1. Made external-agent skills and versioned protocol/schema discovery explicit.
2. Added P0 durable external-run manifests and resumable, bounded ingestion (FR-I11).
3. Added P0 client/service capability diagnostics and version compatibility checks (FR-A10).
4. Strengthened missing-evidence failure semantics, page-map extraction, bounded atomization and preservation of disagreements.
5. Required operation-catalog transport permissions, digest-bound replay, durable receipts, citation-safe budgets and per-harness workflow evidence.

These updates refine the existing product boundary. They do not add an internal agent, a writeable web UI, mandatory manual approval, or a dependency on Jev/Winnow at runtime.

Verification and remaining uncertainty

The probe receipt records eight observed behaviors, including mismatches with KB requirements. Those observations are not a blanket pass for either project. Jev tests were read but its full suite was not run; the MCP SDK registration path and all four client integrations were not exercised. Winnow skill quality, complete source processing and PDF extraction fidelity remain unmeasured by this review. Historical acceptance reports include qualified and user-reported results and are not proof of the current working tree.

The next implementation gate is one local source-to-proposal-to-read workflow with exact evidence, replay and restart checks; then demonstrate it through each supported harness and the VPS transfer path. Use the findings here as design and test inputs rather than assuming copied code is already accepted for KB.