docs: define modular local agent contracts

docs/architecture/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # GEWU architecture
 
-Status: proposed baseline v0.2 after [independent review](../reviews/ARCHITECTURE_SENIOR_REVIEW.md). Drafted 12 October, revised 13 October 2026. Product authority: [GOAL](../GOAL.md) and [PRD](../PRD.md). Related: [acceptance contract](ACCEPTANCE_CONTRACT.md).
+Status: proposed baseline v0.3, 13 October 2026. The [independent review](../reviews/ARCHITECTURE_SENIOR_REVIEW.md) covers the v0.2 acceptance foundation; v0.3 adds the owner-required [local agent](LOCAL_AGENT.md) and [module replacement protocol](../development/MODULARITY_PROTOCOL.md). Product authority: [GOAL](../GOAL.md) and [PRD](../PRD.md). Related: [acceptance contract](ACCEPTANCE_CONTRACT.md).
 
 ## Decision
 
@@ -8,6 +8,8 @@ Build a modular Python service and a React reading application in the GEWU code
 
 Local agents reason about sources and submit proposals. The service validates their structure, source locations, permissions and policy eligibility, then records accepted changes. People can search and follow evidence without an agent running. The service contains no reasoning agent, autonomous research loop or general-purpose chat endpoint.
 
+Provide a custom GEWU local agent in the same workspace-profile form as Winnow/Praxis in the RESEARCH folder: a role, shared protocols, modular skills and coordinating pipelines running inside an existing host. The [source pack](../../agents/gewu/README.md) is maintained separately from development instructions. Host/model and transport adaptations can change without duplicating the skill logic; no new standalone reasoning runtime is required.
+
 The starting deployment is one host, one service instance and one canonical writer. This fits the five-person pilot and makes the acceptance boundary inspectable. Capacity remains a measurement gate; five people does not specify simultaneous agent load.
 
 ## Technology choices and reasons
@@ -17,7 +19,8 @@ These are proposed baselines, not installed versions. Use Python 3.12 as the ini
 | Boundary | Choice | Why for GEWU | Alternative and reconsideration trigger |
 | --- | --- | --- | --- |
 | Service | Python, FastAPI, Pydantic, Uvicorn; `uv` for environment/locking | Typed validation and the document-processing ecosystem; consistent with useful AAA/Jev patterns. | A TypeScript-only service saves a language but complicates Python parser integration. Revisit if parser requirements disappear. |
-| Domain core | Plain typed Python modules, explicit dependency injection | The same scope, evidence and proposal rules serve MCP, reads and maintenance. | No generic pipeline/plugin framework until distinct implementations need one. |
+| Domain core | Plain typed Python modules, explicit dependency injection and public ports | The same scope, evidence and proposal rules serve MCP, reads and maintenance; implementations can be replaced behind tested contracts. | No generic plugin framework or process per module. Introduce distribution mechanisms only for a demonstrated extension need. |
+| Custom local agent | Canonical workspace profile, `SKILL.md` modules and versioned pipeline procedures | Matches the owner's RESEARCH workflow; reuses existing hosts/models while keeping GEWU-specific reasoning procedures portable. | A standalone agent engine adds a runtime to maintain and is outside the selected form. |
 | MCP | Official Python MCP SDK; local stdio connector, service Streamable HTTP | One contract across agent harnesses; connector can read selected local files and upload bytes. | Direct remote connections remain a tested option for clients that support the chosen auth profile; a remote path is never a file upload. |
 | Canonical knowledge | UTF-8 Markdown with YAML frontmatter, YAML records, native Git CLI | Reviewable records, exact history, portable exports. | A database as canonical storage conflicts with the present PRD. |
 | Private artifacts | Content-addressed filesystem by SHA-256 | Retain originals without growing Git with PDFs/media. Git records hashes and manifests. | Object storage only after one-host capacity/backup measurements justify it. |
@@ -39,7 +42,8 @@ The exact dependency inventory is a scaffolding deliverable. Model selection and
 flowchart LR
     H[Human reader] --> W[React website]
     W --> R[Read HTTP adapter]
-    A[Local agent harness] --> C[Local stdio MCP connector]
+    PAK[GEWU profile, skills and pipelines] --> A[Existing local agent host]
+    A --> C[Local stdio MCP connector]
     A --> R
     C --> M[Service MCP adapter]
     O[Human owner client] --> M
@@ -59,6 +63,8 @@ flowchart LR
 
 Imports point inward: transport -> application -> domain. Adapters implement storage, Git, clock, parser and embedding interfaces used by application services. Domain code imports neither FastAPI nor MCP nor React. A small lifespan-owned composition root creates services and closes resources. Each application service owns a complete use case; routes translate protocol messages and enforce transport admission.
 
+Every substantial module exposes a versioned public contract and owns its implementation/state. Consumers cannot import its private internals or provider-specific SDK types. The [modularity protocol](../development/MODULARITY_PROTOCOL.md) defines module descriptors, dependency checks, compatible replacement tests and migration/rollback. This applies equally to service components, UI features, skills and pipeline coordinators. Compatible replacement changes composition/configuration rather than unrelated business logic; a breaking replacement declares a consumer migration.
+
 Recommended code layout:
 
 ```text
@@ -69,6 +75,12 @@ src/skb/
   transports/      # MCP, read HTTP, operator/maintenance CLI
   bootstrap/       # configuration and lifespan assembly
 connector/         # local stdio client bridge; uses shared contract package
+agents/gewu/       # actual source pack; installed into a research workspace
+  AGENTS.md        # research role, separate from repository development rules
+  manifest.json    # pack/skill/pipeline versions and verified compatibility
+  protocols/       # evidence, scope and contribution concerns
+  skills/          # kb-ingest, kb-query, kb-curate, kb-synthesize
+  pipelines/       # host-executed coordination and checkpoint procedures
 web/src/
   app/             # routes, providers, shell
   features/        # search, reading, sources, problems, history
@@ -124,7 +136,7 @@ Human browser sessions are expiring HttpOnly, Secure, SameSite cookies. The read
 
 For the initial controlled-team connector, document a GEWU provisioned-key authentication profile over TLS. Do not describe this as generic OAuth interoperability. HTTP MCP authorization has its own specification; supporting arbitrary remote OAuth clients requires a separately implemented and tested authorization-server/resource-server profile. The local stdio connector avoids assuming all four harnesses support the same remote authentication flow.
 
-Protected changes use the human-authenticated owner MCP client and a digest-bound decision described in the contract. The proposed owner profile uses a short-lived opaque session obtained by password and TOTP reauthentication in a separate human terminal; it is an GEWU-controlled client profile, not a claim of generic OAuth support. Production separates the human owner credential from the agent's OS account/credential store. Owner-level unrestricted filesystem agents cannot be claimed to be isolated by prompt instructions.
+Protected changes use the human-authenticated owner MCP client and a digest-bound decision described in the contract. The proposed owner profile uses a short-lived opaque session obtained by password and TOTP reauthentication in a separate human terminal; it is a GEWU-controlled client profile, not a claim of generic OAuth support. Production separates the human owner credential from the agent's OS account/credential store. Owner-level unrestricted filesystem agents cannot be claimed to be isolated by prompt instructions.
 
 Local operation uses the same core and directory layout as the VPS. Development may run on the user's account with disposable data; enforced pilot/team operation uses a separate service identity. VPS publication requires an independent restore test, HTTPS, private volumes and client workflow evidence. Moving authority to the VPS freezes local writes first; there is no independently writable local replica synchronization in v1.
 
@@ -135,6 +147,7 @@ Local operation uses the same core and directory layout as the VPS. Development
 | M0 contract slice | Schemas, state machine, safe file records, scope/policy fixtures; pin dependencies | Seeded invalid evidence/authority rejected; public schemas generated; decisions below settled for affected boundary. |
 | Pilot end-to-end | Proposed starting point: Windows/Codex, text/Markdown, two projects plus shared, lexical search first | Upload -> proposal -> automatic acceptance -> committed read -> citation; crash/replay tests; read-only browser. Client/format choice remains recommended. |
 | Full P0 service | Hybrid index, all required input types, four harnesses, portability and protected decisions | Per-client transfer/rejection/acceptance/retry/retrieval receipts; no scope or authority bypass. |
+| Custom agent and module gates | Install GEWU profile/skills into an isolated research workspace; enforce dependency boundaries and pinned module/skill versions | Native host ingestion/query and interrupted-run recovery; compatible module swap passes contract/consumer tests. Instruction-pack presence alone cannot close this gate. |
 | Team release | VPS migration, backup/restore, quality sampling, capacity/security acceptance | All selected PRD P0 gates plus measured retrieval, evidence and human reading tasks. |
 | P1 follow-up | Rich comparisons, graph canvas, promotion/import/export and synthesis/curation | Explicitly selected requirements and their own acceptance evidence. |
 

docs/architecture/LOCAL_AGENT.md

@@ -66,6 +66,8 @@ For a connected run, service run identity, proposal revisions and acceptance rec
 
 Pin the installed pack snapshot for an active run. If that version is unavailable after an upgrade, pause with a compatibility finding or explicitly start a successor run. Reuse previous outputs only when their hashes, evidence bindings and new stage contracts still hold; revalidate downstream stages after changes. Install/version manifests alone cannot enforce this in arbitrary hosts; native workflow tests must demonstrate it.
 
+The pack manifest supplies per-module implementation and instruction-contract versions, dependencies, compatible checkpoint contracts and file hashes for the profile, shared protocols, skills and pipelines. Run checkpoints retain the snapshot digest and resolved module IDs/contracts/hashes. Its service-capability requirements remain explicitly unbound until wire schemas exist; empty capability arrays are not a declaration of compatibility. The draft checkpoint fields and snapshot calculation are specified in the pack README.
+
 A pipeline has a bounded work/correction budget, explicit coverage and a resumable stop. Two unchanged validation failures are a default stop for diagnosis, not permission to relax checks. Network uncertainty triggers status lookup, not a fresh proposal identity. Protected decisions leave the agent workflow for the separate human owner client. No continuous watcher, automatic external messaging or unbounded research loop is introduced.
 
 ## Acceptance and sequencing