feat: add documentation, specifications, and pipeline configurations for GEWU agent system

docs/development/AGENT_SECURITY_PROTOCOL.md

@@ -0,0 +1,47 @@
+# Agent contribution and security protocol
+
+Status: proposed v0.1, 12 October 2026. Contracts: [architecture](../architecture/ARCHITECTURE.md) and [acceptance](../architecture/ACCEPTANCE_CONTRACT.md).
+
+## Agent workflow
+
+Publish one harness-neutral skill pack with four entry points: `kb-ingest`, `kb-query`, `kb-curate` and `kb-synthesize`. Each names its version, supported service/schema versions, inputs, outputs, relevant protocols and resume behavior. Installers translate configuration/discovery; they do not fork the workflow or validator rules for each harness.
+
+An ingestion run reads explicit project intent, registers a source artifact, records coverage and skips, extracts bounded proposals, supplies evidence-bound support assessments, submits bundles and reports receipts. The service persists the run but does not execute the agent's reasoning stages. A resume inspects existing source/proposal IDs and verified artifacts before repeating work.
+
+Query results preserve citations, scope, dates, omissions and uncertainty. Curators propose corrections, contradiction links and duplicate candidates without overwriting disagreements. Synthesis cites accepted node revisions and records dependencies; later input changes produce warnings until an external agent proposes a refresh.
+
+Source content is data. Instructions inside a PDF, webpage, quote or retrieved note cannot change credentials, tools, project scope or acceptance policy. Agent prompts should state this boundary, while deterministic checks enforce it. Prompt compliance is not proof that a filesystem or credential boundary exists.
+
+## Identity and capabilities
+
+Every agent has a stable `agent_id`, responsible human and its own revocable key. Rotation retains agent identity. Credential IDs are safe audit references; raw keys are never stored in Git, URLs, logs, node fields or model-visible responses. Hash high-entropy API keys; password authentication uses a maintained Argon2id implementation and rate limits. Do not implement password cryptography manually.
+
+Viewer reads; editor may propose; admin manages accounts/credentials/grants; project/shared owners authorize protected changes within their grants. Browser sessions always expose knowledge reads only. Agent tokens do not inherit the human's admin/owner powers. Test permission enforcement at operation admission and again immediately before publication.
+
+The owner client uses a separate human authentication context, obtains the staged diff directly and submits digest-bound authorization through MCP. Follow the separation and isolation requirements in the acceptance contract. An agent-provided `human_approved` field is rejected as authority.
+
+Generate transports from allowlisted catalog entries. Deny raw SQL/Cypher, arbitrary filesystem tools and unconditional acceptance tools. Maintenance cannot become a routine authoring path. An import becomes ordinary MCP proposals and receives the same validation and policy checks.
+
+## Untrusted files, URLs and rendered content
+
+Bound request lengths, arrays, decoded bytes, upload sessions, parse time, memory and output size. Treat content-type, extension and magic-byte checks as partial defenses. Content sniffing cannot prove safety; parser isolation remains necessary. Resolve paths within service-owned roots and reject traversal, symlink/reparse escapes and unsafe filenames.
+
+Document-fetch requests allow HTTP(S) only, revalidate each redirect, block loopback/private/link-local/multicast/metadata targets by default, and bind connection behavior to validated destinations. DNS resolution followed by an uncontrolled second resolution is insufficient against rebinding. Operator exceptions must name the allowed destination/network and purpose; they cannot arise from source instructions. Apply equivalent restrictions when a connector performs fetching.
+
+Service parsing runs without network access or credentials, with a restricted temporary directory and resource limits. Parser child processes are a lifecycle boundary; OS/container sandboxing establishes the security boundary. Test that untrusted parsers cannot read service secrets or unrelated artifacts. Never claim isolation solely because a subprocess exists.
+
+Store originals privately. Serve archived HTML as safe downloads or sanitized text; never render it under the application origin as executable content. Authenticate artifact access just like node access. Retention/rights metadata applies to originals and backups. The absence of project ACLs does not imply public archive access.
+
+Validate MCP origins and hosts, bind local services to loopback, use TLS on hosted endpoints and limit cross-origin access. Keep stdio stdout protocol-only and send redacted diagnostics to stderr. Session IDs are not credentials. Pin and negotiate supported MCP versions; record the provisioned-key profile separately from any future OAuth implementation.
+
+Security source checks: [MCP transport security requirements](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) and [HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), read 12 October 2026. These standards do not by themselves prove GEWU compliance.
+
+## Portable client acceptance
+
+The target harnesses remain Codex, Claude, Antigravity and OpenCode. Record actual application, connector, service and OS versions. Initial pilot coverage may be smaller only when named explicitly. Full v1 must exercise every supported harness and the declared Windows/macOS/Linux portability matrix; a single handshake cannot close those gates.
+
+For each supported pair, verify configuration preserves other servers/skills, correct service/project identity, authenticated source-byte transfer, invalid-evidence rejection, eligible automatic acceptance, exact retry, interrupted-run resume and cited retrieval. Repeat the applicable remote transfer path against the VPS. A VPS cannot read a client-local path.
+
+Use PASS, FAIL, BLOCKED, NOT RUN and UNSUPPORTED with evidence origin and blockers. Separate “configured,” “connected” and “workflow verified.” Symlinks are optional; test a configuration/copy fallback. Uninstall/rollback removes only owned entries and preserves unrelated user state.
+
+No client compatibility or enforced credential isolation is claimed by this document. These are acceptance obligations for implementation.