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: }; 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.