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.

## Operator handoff and progress

Require the authenticated principal ID from the operator before capture or proposal work. Use it consistently for proposer_id, agent_id and assessor_id. Missing identity is a setup blocker: ask for the non-secret ID and stop. Do not search for it in credentials, environment variables, MCP configuration or service storage, and never read bearer-token files. A folder name or model name is not an identity.

For a resumed run, first resolve run_status and reuse its run identity, source references and unchanged pack pins. Work on one bounded learning unit, retain a compact cited draft, then prepare/evaluate/submit it and checkpoint coverage before changing source. A successful read of a new passage is progress even before a checkpoint; measure tool-level progress as well as durable state. After two identical read/status calls without a changed input or a stated recovery reason, stop that loop and checkpoint the exact blocker. On a time/tool budget boundary, checkpoint pending sections and return an honest partial report.

## Compact factual draft contract

Use the advertised tool schema for call arguments. For a factual learning bundle, the proposal operations are `{operation: "register_source", source: <exact returned candidate>}` when the revision is new, `{operation: "upsert_node", node: <complete node>}` for a new stable node, and `{operation: "update_node", target_id: <existing stable node ID>, node: <complete enriched node>}` when new source evidence supports an existing node. The complete proposal envelope is described below. Do not submit incomplete objects to discover their shape.

Despite its name, `upsert_node` creates a new stable node ID; it does not update an existing node. `update_node` is only for enrichment: retain the same node ID, project, type, creation time and summary; retain accepted claim IDs/text/types and all existing evidence, tags and facet values; append source-backed evidence and new facets/tags without changing prior assertions. New evidence needs its own support assessment attributed to the current proposer. Do not use enrichment to silently correct disputed knowledge. Correct accepted knowledge through a new evidence-backed node and an explicit `supersedes` relationship to the old node, preserving history. Evaluate that complete correction bundle against the applicable policies. If supersession requires owner review, keep the bundle held; do not remove its relationship to obtain automatic acceptance. Distinguish a prepared correction, a durably staged review proposal and an accepted replacement.

A node requires `node_id`, `project_id`, `node_type`, `title`, `summary`, `created`, `updated`, `review_state`, `lifecycle`, `confidence`, `claim_support`, `run_id`, `agent_id`, `model_id` and `claims`. Use timezone-aware ISO 8601 datetime strings for created/updated, review_state `draft`, lifecycle `active`, and confidence `low`, `medium` or `high` as justified. Classify node_type by meaning and inspect the actual acceptance policy outcome; never relabel to evade a hold. Optional lens_fit maps a project ID to `{score, horizon, reason, key_question}`.

Each claim requires `{claim_id, text, evidence_type, evidence, assessment}`; evidence_type `reported` means the source reports the assertion. Each evidence entry supplies `{source_revision_id, extraction_id, quote, locator, normalization_profile}`. Use the returned normalization profile; a PDF locator is `{kind: "pdf_page_span", block_id, start, end, page}`, while non-PDF text uses `{kind: "text_span", block_id, start, end}`. Offsets refer to the returned normalized text, with end exclusive. Each assessment supplies `{assessment_id, assessor_id, run_id, method, status, rationale}`; status is `supported`, `unsupported` or `unavailable` based on semantic support. The complete draft may omit assertion_path, assertion_digest, evidence_digests and payload_digest because proposal_prepare fills those dependent fields. The server still validates every other required field.

## Antigravity call argument reminders

Antigravity may expose MCP through a generic `call_mcp_tool` wrapper. Use the discovered server/tool names and its advertised schema; do not infer nested `scope` objects when the operation accepts flat scope fields. The wrapper's outer arguments are `ServerName`, `ToolName` and `Arguments`; `Arguments` contains only the target MCP tool's input object. For example, `get_source` is called as `{ServerName:"gewu-dome-pilot", ToolName:"get_source", Arguments:{project_id:"dome-performance", revision_id:"<exact revision id>"}}`. Do not nest the wrapper object inside `Arguments`. For common GEWU calls, the required arguments are: `gewu-dome-files/list_selected_files` `{}`; `upload_selected_file` `{file_id, project_id}`; `get_project_context` `{project_id}`; `get_source` `{project_id, revision_id}`; `source_extraction_block` `{project_id, extraction_id, block_id, offset, length}`; `list_sources` `{projects, include_shared, all_projects:false, limit, budget_tokens}`; `search` `{query, projects, include_shared, all_projects:false, limit, budget_tokens}`; `run_create` and `run_checkpoint` `{request_json}`; `proposal_prepare`, `proposal_evaluate`, and `proposal_submit` `{proposal_json}`; `ingest_review_create` `{review_json}`. The request/proposal/review values are serialized JSON strings that must follow their pinned record schemas. Never omit `project_id` from a selected-file upload or source read, or put `scope` inside search/list-source arguments. `get_source` reads registered sources only. A newly captured/uploaded source is staged; do not call `get_source` for it. Register its exact returned `source_candidate` in the same proposal that cites it, and read its evidence through the returned staged `extraction_id`.

For Antigravity, call `diagnostics`, `get_project_context` and `run_create` once each in that order. After a successful call, keep its returned IDs/context and move to the next stage. If a generic-wrapper call gets an argument validation error, inspect only the pinned entry for that tool, correct the outer wrapper once, and stop if the corrected call fails.

Use the agent's stable principal ID from operator-provided configuration; do not try the standalone Jev MCP server. Jev relevance and facet decisions run on the GEWU backend through `ingest_review_create`.

`run_create` is idempotent only for the same run ID and identical create payload. Create service run state through `run_create` with one `request_json` argument; the service is the source of truth, and no local `Runs/<run_id>` JSON file is required before creation. Do not search for or open a guessed local run file. On an uncertain response, reuse that exact request or check the real run ID with `run_status`. Never reuse a run ID with changed objective or pack pins. If the pack was reinstalled or upgraded after a run was created, leave that old run alone and start a new run with a unique ID and the current `.agents/gewu-install.json` `run_pins`. Read that receipt with the host's file-view tool; do not use shell to count or transform pins. In headless Antigravity, unapproved shell calls are denied and can consume model turns without advancing ingestion.

## 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. If Antigravity drops exactly the final outer `}` when copying the returned string, evaluation and submission can repair that one unambiguous truncation only when the repaired payload passes the full contract; the response then reports `input_repaired: true`. Any other malformed payload remains invalid.

Pass the returned `proposal_json` byte-for-byte to `proposal_evaluate`; do not retype, summarize, rebuild, or edit that serialized string. Keep proposals compact by grouping only one learning unit and including only the claims and evidence needed to support it. If evaluation returns `PROPOSAL_JSON_INVALID`, stop before submission and rebuild/re-prepare the draft once; never submit the malformed or previous payload. A valid evaluation with status `needs-review` (for example, finding `AUTO_ACCEPT_UNSPECIFIED`) is a policy hold requiring an owner decision, not a transport error or an instruction to bypass policy. Do not submit it as though it were eligible for automatic acceptance.

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. The MCP tool takes exactly one `request_json` string whose JSON object includes `run_id`, `objective`, `scope`, `lens`, `pack_id`, `pack_version`, `pack_snapshot_digest` and `module_pins`. In the scope object use `projects`, never `project_ids`, and set `include_shared` explicitly. For a project-only run use `{"projects":["<project-id>"],"include_shared":false}`. Do not include `include_shared:true` by default: shared access is both a sensitive read and (for agent credentials) a write authorization, so use it only when the task actually needs shared records. If validation returns field errors, correct those fields once; an invalid response does not create the run. 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. Store accepted receipts in proposals entries shaped as {proposal_id, revision, status: "accepted", receipt: <exact service receipt>}; last_receipt is not a service checkpoint field. In coverage, selected/included are arrays of strings; excluded/skipped are arrays of {item, reason} objects, not strings. Invalid run requests return status=invalid with field-level issues and do not advance the run; correct the named fields once before retrying. 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.