fix(agent): bound Antigravity ingestion flow

protocols/CONTRIBUTIONS.md

@@ -2,6 +2,16 @@
 
 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.
 
+## 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.
@@ -16,7 +26,9 @@ Before creating a new node, search the explicit project and shared scope with mu
 
 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.
+`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.