GEWU_agent/protocols/CONTRIBUTIONS.md

# Contributions and run recovery

Before a connected workflow, call `diagnostics` and use MCP discovery to confirm the required tools and their advertised input schemas. The schemas discovered from the active server are authoritative for this session. Do not open `manifest.json`, `contracts/service-v1.json`, record schemas, the README or helper-script source just to verify tool availability, arguments or checkpoint behavior. If a required tool is absent or a discovered schema causes a concrete mismatch, stop before mutation and inspect only the relevant pinned contract entry; report the drift if that does not resolve it. Diagnostics reports the authenticated role, authorized projects/capabilities, explicit selected scope, source-transfer limits, service/catalog versions and canonical/index revisions without returning credentials or principal IDs. `connection_status=authenticated` proves only this call; `workflow_status=not_verified` means native workflow acceptance remains separate. `proposal_evaluate` is the deterministic preflight for one complete, real proposal. Never probe it with a placeholder payload, zero digest or guessed identity; never call `proposal_status` with a fabricated proposal ID. The service's `proposal_submit` response remains authoritative. Owner decisions use a separate owner transport and are not available to agents. Runs are agent-owned, explicitly scoped service records; they do not schedule work or grant capability.

## Build attributable proposals

Use the stable principal ID assigned to the configured agent credential. The credential must have the `agent` role and grants for every affected project. Set `ProposalRevision.proposer_id`, each proposed node's `agent_id`, and each claim assessment's `assessor_id` to that principal ID. Do not substitute a model name, harness name or human display name. Diagnostics intentionally omits principal IDs; obtain the expected ID from the credential's operator-provided configuration, never guess it. If the identity is unknown or the service rejects attribution, stop and report the mismatch rather than changing IDs speculatively.

## Register sources and bind evidence

Capture tools stage and archive source material but do not register its source record. Before evaluating a proposal that cites a newly captured source, include the exact returned `source_candidate` as a `register_source` operation in the same proposal, or confirm that the source revision was already accepted and is readable. Use the candidate's exact `revision_id` as each citation's `source_revision_id`, and the capture's returned `extraction_id`; do not synthesize or copy IDs from another capture. A source operation and a node operation may be evaluated together.

Every source registration affects both the shared-source policy and each project in `source.ingested_for`; therefore proposal scope must set `include_shared=true` and explicitly include the project(s), and the agent credential must be authorized for that scope. A project-only scope is invalid for a newly registered source even if it is relevant only to that project.

Before creating a new node, search the explicit project and shared scope with multiple lexical queries: the proposed title, distinctive terms, aliases and likely synonyms. Inspect plausible matches with `get_node`. If the finding belongs to an existing node, preserve its stable ID and supported content when proposing an evidence-backed update; do not create a second node for the same concept. Keep materially different populations, time periods, settings, mechanisms or conclusions distinct. Similarity is only a review cue. The backend flags exact entity name/alias matches but does not detect duplicate notes, cases, concepts or datapoints; if likely duplicates remain unresolved after search, submit a non-blocking review flag and do not create another node yet.

Finalize claim text, evidence and locators, then call the read-only `proposal_prepare` MCP tool with the complete draft proposal. It fills each claim's exact typed `assertion_path`, assertion digest, evidence digests and final payload digest, and returns prepared `proposal_json`. Use that JSON unchanged for `proposal_evaluate`; after any edit, call `proposal_prepare` again. It does not evaluate, store or submit the proposal. Do not run shell commands or manually hash proposal content. If `proposal_prepare` is unavailable, stop before evaluation and report that deterministic digest preparation is missing.

`proposal_prepare` applies the canonical GEWU digest rules: UTF-8 canonical JSON, Unicode preserved, sorted keys, no insignificant whitespace and no NaN values. It binds assertions to normalized exact claim text, hashes complete evidence objects and hashes the final typed operations. Its server result is authoritative for dependent digest fields.

The proposal envelope must include `schema_version`, `proposal_id`, `revision`, `initiating_project_id`, `scope`, `base_commit`, `payload_digest`, `proposer_id`, `run_id` and `operations`. `proposal_prepare` fills dependent digests; it does not invent the run, scope, principal, base revision or proposal metadata. Do not add unsupported envelope fields such as `created_at` or `reason`. For a PDF citation, use `locator.kind="pdf_page_span"` and the page from the extraction block; `text_span` is for non-PDF text and cannot include a page. Do not call `proposal_evaluate` unless `proposal_prepare` returns `status="prepared"`; evaluate only its returned `proposal_json` unchanged. If preparation returns `status="invalid"`, correct the named issue and retry once. Never probe preparation with `{}` or another incomplete draft.

A claim's `assessment` uses the GEWU fields `assessment_id`, `assertion_digest`, `evidence_digests`, `assessor_id`, `run_id`, `method`, `status` and `rationale`. Do not add guessed fields such as `support_level`, `confidence` or `assessed_at`; `proposal_prepare` reports typed validation issues but does not translate another schema.

`list_projects` exposes authorized IDs, and `get_project_context` returns the selected authorized project's north star, key questions, watch list, taxonomy extensions, research lenses and explicitly saved ingest guidance without exposing its autonomy policy. Projects default to technical, conceptual, cultural-historical and financial-market lenses. These are coverage prompts, not quotas. Use this context for ingest/curation; keep objective and scope explicit and never infer authority from a folder or project name.

When available, `ingest_review_create` stores a source-bound review flag. Submit it after or alongside normal proposal processing, never as a reason to wait on human review before evaluating/submitting plausible findings. Bind it to the durable run and an extraction owned by the submitting agent and granted project; the exact excerpt and locator must match the staged extraction. A queue entry is a notification/filter and feedback record, not a proposal, source registration, acceptance result or publication. Human reviewers may confirm relevance, mark it irrelevant or defer feedback. Reusable project guidance is added to future context only when a human explicitly saves a rule. If the review operation is absent, preserve and report plausible uncertain material rather than silently deferring it.

The `ingest_review_create` MCP tool takes one `review_json` string, not review fields as top-level tool arguments. Its request requires `review_id`, `project_id`, `run_id`, `source_revision_id`, `extraction_id`, `locator`, `excerpt`, `lens`, `summary` and `relevance_rationale`; use `candidate_facet_labels` for defined label candidates. The field is `relevance_rationale`, not `reason`. A call invokes advisory Jev relevance/lens and facet judgments when configured and returns any `jev_facet_resolutions`; it is not a prerequisite for ordinary proposal acceptance. Use this call when a label needs explicit Jev normalization or human categorization review, and treat its saved item as a non-blocking notification.

Current capability gaps that must be reported when relevant: retrieval is lexical only; URL capture requires an exact operator-allowlisted public host. URL and selected-file intake support UTF-8 text/Markdown/HTML and PDF; selected `.vtt` and `.srt` files are parsed into timestamped cues and tagged `capture_method=transcript`. Transcript evidence must cite the exact text span and matching cue start/end milliseconds. `source_capture_text` accepts explicitly supplied UTF-8 plain text or Markdown up to 1 MB. It requires a stable capture ID, stores the completed metadata candidate in a private bounded receipt journal, returns the same candidate for an exact retry, and conflicts if the same ID is reused with changed inputs. Source records distinguish URL fetch, local-file, transcript, declared NotebookLM-export and pasted-text capture methods; the NotebookLM label does not verify export provenance. HTML citations refer to the visible-text extraction, not markup-byte offsets. PDF extraction is qualified only on Linux in a sandbox; scanned PDFs return `PDF_NO_TEXT`. Failed URL captures can be registered as artifact-free references, and source records include publisher, author, publication date, license and reliability fields. supplied NotebookLM exports, Windows/macOS PDF extraction, native host workflows and real-source location checks remain unqualified. There are no vector/hybrid search or project-export/import operations. Duplicate review can nominate exact entity name/alias matches only within the caller-readable explicit scope; it does not merge records. Reversible merge, protected owner decisions, promotion and synthesis-dependency warnings remain unavailable. Do not describe these as implemented merely because a pipeline or record schema can represent related data.

Use read tools for retrieval and typed MCP proposals for contributions. Source upload completion establishes a staged artifact, not an accepted source. Treat policy acceptance and index visibility as separate outcomes. Corrections append revisions; accepted records are corrected through new linked proposals.

Create the service run with `run_create` before capture or proposal submission. Persist returned run identity and operation input digests in the private local checkpoint, then append service checkpoints with `run_checkpoint`; `run_status` is authoritative after uncertain calls and returns the latest revision. Each update uses `expected_revision`; retry the same checkpoint unchanged after uncertainty. The local helper remains a private host-side recovery mirror and is useful when offline. Checkpoints include pack/skill/pipeline versions and hashes, explicit project/shared scope and lens, source/extraction references, stage, output hashes, included/excluded/skipped coverage, pending side effects and last receipt. The helper rejects credential/source-body fields and verifies pinned module hashes on resume. The pack does not provide a host scheduler.

Create the service run immediately after diagnostics, project context and explicit scope, before source transfer or proposal work. `run_create` takes `request_json`; supply a JSON object with `run_id`, `objective`, `scope`, `lens`, `pack_id`, `pack_version`, `pack_snapshot_digest` and `module_pins`. Use the compact `run_pins` object in `.agents/gewu-install.json` for the four pack fields; the installer writes the required `module_id`, `implementation_version` and `sha256` for every module there. Do not inspect the manifest, run schemas or helper implementation to reconstruct these values. If `run_pins` is absent, inspect only the manifest's pack identifiers, snapshot digest and module entries. Persist the returned run identity and operation input digests in the private local checkpoint after the service run exists, then append service checkpoints with `run_checkpoint`; `run_status` is authoritative after uncertain calls and returns the latest revision. Each update uses `expected_revision`; retry the same checkpoint unchanged after uncertainty. The `sources` field is an array of objects with `source_revision_id` and `status` (`selected`, `captured`, `extracted`, `unavailable` or `failed`); include `artifact_sha256` and `extraction_id` when known. Do not store source revision IDs as bare strings. Checkpoints include explicit project/shared scope and lens, stage, output hashes, included/excluded/skipped coverage, pending side effects and last receipt. The helper rejects credential/source-body fields and verifies pinned module hashes on resume. The pack does not provide a host scheduler.

Both `run_create` and `run_checkpoint` take one `request_json` string containing their complete request object. A checkpoint object must include `run_id` and the exact current `expected_revision` from `run_status`, plus `stage`; include source references as objects and a coverage object. Do not send checkpoint fields as top-level MCP arguments or omit the run identity/revision. Update local checkpoint files only through the host's approved file tools; if those tools are unavailable, the service checkpoint is authoritative and must still be recorded.

When upload completion is uncertain, call `source_upload_status` with the saved upload ID and resume only from its verified offsets. When proposal submission is uncertain, call `proposal_status` with the same proposal ID and revision. If accepted, reuse the returned receipt and do not resubmit. If evaluated but not accepted, inspect findings; if withdrawn, that proposal revision cannot be submitted. Never generate a fresh proposal ID to hide network uncertainty. Resume from preserved artifacts and service receipts; changed content requires a new proposal revision. Do not rerun a model and assume it reproduces the same output.

Bound work by source/batch size, stage/model budget and correction attempts. After two unchanged validation failures, stop for diagnosis and report findings. Coverage/skips remain explicit at any stop. Cancellation cannot undo an accepted proposal; check status when a call may have completed.

Only the service decides acceptance. Report accepted, held/rejected, index-pending and blocked work separately. Human-owned intent/policy changes need a distinct authenticated owner decision; the agent cannot supply it or hold owner credentials. An installed skill grants no authority beyond the user's task and current service credential.