vasily
78033bb830
Adds claim-bound online evidence records and citation verification scripts, node removal transport/adapter, retrieval benchmark and owner-review tooling, GraphCanvas/SourceDetail knowledge browser UI, and the ingest handoff helper. Bumps the agents/gewu pack to the online-verification branch.
GEWU architecture and engineering handbook
Started 12 October 2026; revised 14 October 2026. Architecture proposal v0.3. The backend, authenticated HTTP/MCP workflows, a read-only research UI, and a modular GEWU agent pack are implemented to varying levels of local verification. Consult the implementation status and acceptance ledger for evidence and open gates.
Tagline: Investigate. Connect. Remember.
GEWU (格物) draws on géwù zhìzhī (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Interpretations vary; the name evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse. GEWU is a shared research library with a read-only website and an MCP contribution workflow. The goal and PRD own product requirements. This handbook translates them into a proposed implementation and working protocols. It does not change their priorities or claim that M0 is complete.
Read in this order
For a local setup and first browser session, start with the getting started guide. It uses a disposable synthetic registry and does not claim pilot qualification.
Start delivery planning with the implementation plan: work packages, pilot/full-v1 boundaries, decision gates and PRD traceability.
For the project knowledge UI, use the knowledge browser implementation plan: Luna's handoff for browsing, node details and cross-links, and graph exploration.
- Reference review: which practices to borrow, adapt or reject.
- Architecture: components, technology choices, alternatives and deployment.
- Acceptance and evidence contract: records, authority, replay, crash recovery and source integrity.
- Development protocol: implementation workflow, module boundaries, verification and documentation.
- Visual design protocol: the owner-selected editorial research direction and its review gates.
- Agent and security protocol: agent workflows, permissions, untrusted inputs and client acceptance.
- Operations protocol: persistence, deployment, backup, migration and incident response.
- Local agent and source pack: RESEARCH-style workspace profile, modular skills and pipeline procedures.
- Module replacement protocol: public contracts, dependency boundaries, replacement tests, state migration and rollback.
The independent architecture review records findings and corrections for the v0.2 acceptance foundation. The local-agent and modularity addition records the v0.3 scope and verification separately.
The project knowledge browser implementation and remaining acceptance work are tracked in the knowledge browser plan and acceptance note.
Decision status
| Status | Meaning here |
|---|---|
| Product requirement | Already stated in GOAL/PRD; this proposal must satisfy it. |
| Owner-selected direction | Warm editorial research workspace, confirmed in this conversation. Exact tokens and layouts remain proposed. |
| Owner-required additions | Custom local agent in the RESEARCH workspace style; modular development across all components with tested replacement paths. |
| Architecture recommendation | Concrete engineering default for review; no implementation or measured acceptance implied. |
| Open owner decision | A policy, staffing, capacity or content choice that engineering cannot present as approved. |
Protocol language describes the intended implementation standard if this baseline is adopted. The reference projects' instructions have no authority over GEWU. Repository-specific Symbia consultations, agent-hook behavior, terminal aesthetics and approval requirements were reviewed as source material rather than activated.
Next implementation boundary
The disposable local vertical slice now uploads a selected source through MCP, validates and accepts an evidence-backed note under a test policy, reads the committed revision, and opens its citation in the browser. Retry, recovery and scoped-read cases have local tests. The test policy is not the production policy. Remaining work includes real pilot source and question qualification, protected owner authorization, selected native-client workflows, portability and accessibility acceptance; see the implementation plan and ledger for the next gates.
Before that boundary becomes a pilot deployment, settle the open decisions listed in the architecture. Implementing a smaller slice does not reduce the PRD's full-v1 requirements for hybrid retrieval, supported source formats, four agent harnesses and portable operation.
Runtime versions are locked in the Python and web workspaces. The agent pack has a contract/version manifest, local checkpointing, and an additive installer; native-client discovery and workflow acceptance remain open. The service exposes authenticated reads and contribution workflows, and the browser reads accepted knowledge with citations. Pilot corpus evaluation, protected owner authorization, cross-platform qualification, deployment, and accessibility gates remain open. Skill-file validation is separate from installed discovery and live workflow acceptance.