docs: define modular local agent contracts

docs/PRD.md

@@ -4,9 +4,9 @@
 
 **Name:** GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Its interpretations vary across traditions. Here it evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse.
 
-Version 0.7 (draft) | 12 Oct 2026 | Status: target-alignment and release-readiness review; owner decisions pending
+Version 0.8 (draft) | 13 Oct 2026 | Status: local workspace-agent and modularity requirements added; remaining policy/operating decisions pending
 
-Current review: [Target alignment and release readiness](reviews/PRD_TARGET_READINESS.md). This revision clarifies acceptance and delivery gates without changing existing P0/P1 priorities. Earlier reviews below retain their historical scope.
+Current design: [Architecture](architecture/ARCHITECTURE.md), [local agent](architecture/LOCAL_AGENT.md) and [modularity protocol](development/MODULARITY_PROTOCOL.md). Revision 0.8 adds the owner-requested custom local workspace agent and replaceable-module requirement. Existing feature priorities remain; the agent pack does not promote P1 synthesis/advanced curation services to P0. The [target alignment and release readiness review](reviews/PRD_TARGET_READINESS.md) describes revision 0.7; earlier reviews retain their historical scope.
 
 Owner decisions confirmed during this review: a smaller pilot precedes full v1; the pilot projects are Dome interactive content and an interactive video platform/service, for up to five people initially. Routine notes may be extracted and support-assessed by the same local agent, with recorded assessment and quality sampling. Human roles are admin, editor and viewer. Each local agent receives its own API key and stable identifier. Project-restricted access follows later; all-team read access remains the initial target. “Editor” is interpreted as MCP proposal permission under the existing read-only web target.
 
@@ -41,7 +41,7 @@ Non-goals (v1)
 - Replacing project management, CRM or code search tools. KB feeds them knowledge but does not manage tasks or deals.
 - A general-purpose chatbot. Agents use KB as a tool, and the UI is for search, navigation and reading.
 - A story-map authoring editor (a canvas for drawing branching story flows) and an embedded in-UI copilot. Agents reach KB through MCP, and story authoring is a separate product.
-- An internal reasoning agent, autonomous research loop or server-hosted curator in the initial system. Ingest, interpretation, semantic linking and synthesis run in external local agents. Server parsing, indexing, retrieval and policy validation are ordinary service functions; embedding computation does not imply an agent inside KB.
+- A reasoning agent embedded in the knowledge service, autonomous server research loop or server-hosted curator in the initial system. Ingest, interpretation, semantic linking and synthesis run in local hosts, including the custom GEWU workspace-agent profile. A separate standalone GEWU reasoning runtime is not required. Server parsing, indexing, retrieval and policy validation are ordinary service functions; embedding computation does not imply an agent inside KB.
 ## Users and use cases
 
 | User | Typical needs | Example |
@@ -265,6 +265,7 @@ Priority: P0 required for v1, P1 important, P2 later.
 | FR-A8 | MCP resources (schema, project registry, node by ID) and prompts (per-project roles, for example an architecture advisor) alongside the tools. | P1 |
 | FR-A9 | Typed tools only. No raw query language (Cypher, SQL) is exposed to agents, and every write goes through a proposal. | P0 |
 | FR-A10 | Expose service/connector diagnostics and compatible tool/schema/skill versions, authenticated capability, selected scope, source-transfer limits, and index status without secrets. Distinguish configured, connected and workflow-verified clients. Installers preserve unrelated client configuration and support a non-symlink fallback. | P0 |
+| FR-A11 | Provide a custom GEWU local workspace-agent pack, following the RESEARCH workspace pattern: one canonical profile, shared protocols, replaceable ingest/query/curate/synthesize skills and coordinating pipeline procedures. Existing supported hosts supply the model/runtime. The pack discovers real MCP capabilities, preserves evidence and permissions, records versioned checkpoints and resumes using durable service receipts. Profile/skill presence alone is not integration acceptance; P1-dependent workflows report unavailable capabilities until implemented. | P0 |
 
 ### 7.5 Compilation and curation
 
@@ -293,10 +294,11 @@ Priority: P0 required for v1, P1 important, P2 later.
 
 1. Source of truth: markdown and YAML files in git.
 2. Derived index: SQLite with full text, vectors and an edges table for v1. It is disposable and rebuildable from canonical files and required source artifacts. Hosted clients use the service rather than opening the database file directly.
-3. KB service: one scoped core with a typed MCP contribution/retrieval interface and a read-only HTTP API for the website. CLI utilities support diagnostics, validation, rebuild and maintenance, not knowledge authoring. Only the MCP proposal path can initiate new knowledge changes; the service validates, applies acceptance policy and commits them.
-4. Skills: judgment procedures (capture, triage, digest, analyze, link, verify, compile, report), kept as one canonical set with a shared concerns to protocol mapping.
+3. KB service: one scoped core with a typed MCP contribution/retrieval interface and a read-only HTTP API for the website. Service maintenance CLI utilities support diagnostics, validation, rebuild and maintenance, not knowledge authoring. A local agent host may have its own CLI, but contributions from it still enter through MCP proposals; the service validates, applies acceptance policy and commits them.
+4. Local agent: a custom workspace profile and canonical skill/pipeline pack, executed by an existing local host. Judgment procedures (capture, triage, digest, analyze, link, verify, compile, report) remain modular, with shared concern-specific protocols and versioned inputs/outputs. There is no additional standalone reasoning runtime in this requirement.
 5. UI: a read-only client for search, navigation and knowledge display. Its credentials and API surface cannot submit, edit or accept knowledge.
 6. Principle: deterministic strictness lives in code (validator, indexer), not in prompts, so different agents and models are held to the same floor.
+7. Modularity: service, agent-pack, connector and UI responsibilities have public contracts and private implementations. Replacements pass shared contract/consumer tests, with explicit version/state migration and rollback. Configuration/composition selects concrete implementations; unrelated modules do not import their internals.
 Reuse from existing work: Jev's contracts, tool registry, owned configuration merging, replay patterns and diagnostics; Winnow's concern-specific protocols, atomic extraction, claim audits and relational synthesis procedures. The [reference review](LOCAL_AGENT_IMPLEMENTATION_REVIEW.md) records limits: Jev's advisory verification/direct writes/character truncation and Winnow's direct vault writes/flattened extraction/prompt-only stages do not satisfy KB's gates. Reimplement those boundaries against KB contracts; no wholesale runtime import is assumed.
 Storage decision (v1). Files in git plus SQLite (full text, vectors and an edges table). A graph server is deferred to limit operational complexity; using one as a derived index would not inherently move the source of truth out of git. Revisit after measured graph-query or scale limits. Cloud document parsers, separate entity-tagging models and heavy entity-matching pipelines are also deferred. Agents get typed tools only, never a raw query language.
 
@@ -310,6 +312,8 @@ One versioned operation catalog declares schemas, handlers, required capabilitie
 
 Provide a canonical, harness-neutral pack with four initial entry points: ingest, query, curate and synthesize. Skills declare concerns and load only relevant protocols (evidence, scope, relationships, proposals and synthesis). They reference service-published schemas and tool versions instead of copying validator rules. Harness setup translates discovery/connection details; it does not duplicate business logic or require lifecycle hooks. Claude requires its own verified client path rather than inheriting a claim of support from another harness.
 
+The owner selected the workspace-agent pattern used by Winnow in SCAR and Praxis in CV. The [GEWU pack](../agents/gewu/README.md) supplies a role, protocols, skill entry points and separate pipeline instructions for an existing local host. Keep the research profile separate from application-development instructions. Model/provider execution belongs to the host; local files do not imply local-only inference. A pipeline document is not a durable scheduler: service run records and receipts, supplemented by private local checkpoints, govern resume and acceptance. Installing a newer skill cannot silently change an active run's pinned instructions.
+
 The local agent reads authoritative project intent and scope through MCP. H1/H2 are explicit task/run context; client cwd and inferred README descriptions are not authority for project selection or H3. External ingestion stages persist source capture, extraction references, triage, bounded note proposals, support assessments and proposed links, then receive validation/acceptance receipts. Resume uses those records instead of conversation history. If lease-based stage ownership is used, an expired worker cannot publish a stale result without revalidation and the current fence.
 
 Atomization optimizes for relevant, reusable knowledge rather than maximum note count. Record source coverage and reasons for skipped/deferred portions; do not silently claim exhaustive processing after a budget limit. Curation keeps incompatible perspectives and conditions separate, uses explicit merge/redirect proposals for duplicates and derives backlinks from stored forward edges. Strong similarity or common sources alone do not establish equivalence.
@@ -317,7 +321,7 @@ Atomization optimizes for relevant, reusable knowledge rather than maximum note
 The capability acceptance matrix records each affected OS/harness pair as PASS, FAIL, BLOCKED, NOT RUN or UNSUPPORTED, with application/connector/service versions and evidence origin. Listing tools or parsing configuration is not the v1 gate: each supported client must perform source transfer, invalid-proposal rejection, eligible automatic acceptance, retry/resume and cited retrieval on the tested deployment. Record local and VPS evidence separately.
 ### Deployment and execution boundary
 
-During development, the service, repository, private archives, index and web app run locally. For team operation they run on the owner’s VPS; ingestion, reasoning and synthesis agents continue to run in local Codex, Claude, Antigravity and OpenCode sessions. The VPS serves retrieval, validates submitted artifacts/proposals, applies policy, commits accepted records and maintains the derived index. Initially KB hosts no reasoning agent or autonomous curator. Semantic support assessments and proposed connections come from external agents; the server checks required records, deterministic evidence rules and policy, without claiming to independently prove semantic truth. Reading and relationship navigation work when no local agent is running; new semantic analysis and synthesis refresh wait for an external agent run.
+During development, the service, repository, private archives, index and web app run locally. For team operation they run on the owner’s VPS; ingestion, reasoning and synthesis agents, including the GEWU profile, continue to run in local Codex, Claude, Antigravity and OpenCode sessions. The VPS serves retrieval, validates submitted artifacts/proposals, applies policy, commits accepted records and maintains the derived index. The KB service hosts no reasoning agent or autonomous curator. Semantic support assessments and proposed connections come from local agents; the server checks required records, deterministic evidence rules and policy, without claiming to independently prove semantic truth. Reading and relationship navigation work when no local agent is running; new semantic analysis and synthesis refresh wait for a local agent run.
 
 Migration to the VPS transfers canonical records, private source artifacts, proposal/run/audit records and configuration, then rebuilds or verifies the index. The local service stops accepting writes before the VPS becomes authoritative; v1 does not promise synchronization between independently writable local and VPS copies. Agent MCP endpoint/credential settings change without changing the contribution contract. Local operation remains supported, but remote VPS access requires connectivity.
 
@@ -372,7 +376,7 @@ The full v1 release gate covers every P0 requirement plus backup/restore of cano
 | --- | --- | --- |
 | M0 Foundations | Node schema, evidence/edge contracts, project registry, validator, proposal/review API and team capability contracts; 20 hand-guided sources across two projects, with the deep-research report as an ingest fixture once supplied (graded as a secondary, AI-synthesized source) | Validator catches seeded errors. Notes validate. Support-review fixtures distinguish quote presence from supported claims. Required pilot sources and expected answers are supplied and labeled. |
 | M1 Service | Index, hybrid search, scoped MCP and read-only HTTP, authentication, durable proposals and automatic acceptance policy | Agents can search, transfer source artifacts and propose from all four harnesses. An eligible proposal is accepted without human action; web writes, unauthorized mutations, scope escape and duplicate acceptance fail. Index-lag recovery is demonstrated. |
-| M2 Ingest | capture, triage, digest, verify, link, run logs, task brief | Cross-agent convergence test passes. |
+| M2 Ingest | capture, triage, digest, verify, link, run logs, task brief; custom local profile, modular skills and coordinating pipelines | Cross-agent convergence test passes. The custom pack completes the source-to-proposal-to-read workflow, records exact versions, and resumes an uncertain operation without duplicate acceptance. Missing P1 capabilities remain explicit. |
 | M3 UI | Read-only project switcher, search, node/source and problem/topic pages, evidence/history, related-node suggestions and staleness | With no agent running, a member opens a problem, explores multiple approaches and their conditions, and follows a citation to an archived source. Suggested matches remain distinguishable from accepted links. Web credentials cannot capture, edit or accept knowledge. |
 | M4 Synthesis | analyze, compile, brief, matrix, timeline, curator report | Briefs produced for each audience. |
 | M5 Multi-project hardening | Promotion to shared, cross-project edge hardening, export and import; acceptance receipts extended to portability workflows | Three projects live on one base without unintended scope mixing. P0 scope enforcement and acceptance receipts already pass at M1. |
@@ -515,3 +519,9 @@ MCP additionally needs typed source-artifact transfer and proposal operations to
 - Added M0 decision gates and a full v1 release gate; retained existing priorities and distinguished confirmed pilot domains from suggested registry IDs.
 - Recorded owner decisions: smaller pilot, two named projects, up to five people, same-agent support with quality sampling, admin/editor/viewer roles and per-agent API keys/identifiers. Project-restricted access remains later.
 - No implementation or runtime acceptance is claimed. Exact pilot client/formats, quality-sampling rules and operating targets remain open.
+
+## Revision notes (0.8)
+
+- Added the owner-requested custom local agent as a workspace profile with skills and pipelines, matching the RESEARCH pattern. Existing local hosts provide execution; the service remains free of an embedded reasoning agent.
+- Added FR-A11 and made replaceable modules a non-functional requirement across service, agent pack, connectors and UI. Public contracts, isolated implementations, replacement tests and migration/rollback are part of acceptance.
+- Added an initial portable instruction pack and linked its design. Structural validation, installation, connection and live workflow acceptance are separate evidence levels; no service or harness pass is implied by these files.