docs: clarify proposal source and digest bindings

protocols/CONTRIBUTIONS.md

@@ -2,6 +2,18 @@
 
 Before a connected workflow, call `diagnostics` and compare the discovered MCP tool names and input schemas with `contracts/service-v1.json`; its catalog digest and record-schema hashes pin the local GEWU v1 contract. 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. The MCP tool inventory must match exactly. If tools are absent or schemas differ, stop before mutation and report the drift. `proposal_evaluate` is the deterministic preflight; 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.
+
+Finalize claim text and evidence before creating support assessments or digests. Every evidence `assertion_path` must name its exact typed claim field (`claims[n].text`, `assumptions[n].text` or `limitations[n].text`). Its `assertion_digest` must bind to that exact claim text. Set the assessment's `assertion_digest` to the same value and `evidence_digests` to the digests of the claim's final evidence objects. Any edit to claim text or evidence requires regenerating those dependent values and the proposal `payload_digest` before `proposal_evaluate`.
+
+Use the canonical GEWU digest rules, not a hash of the raw quote or raw request text. Canonical JSON is UTF-8 JSON with Unicode preserved, sorted keys, no insignificant whitespace and no NaN values. The assertion digest is SHA-256 of canonical JSON `{"assertion": normalized_text}`, where text has CRLF and CR converted to LF and is normalized to Unicode NFC. An evidence digest is SHA-256 of canonical JSON for the complete evidence object in schema JSON form. The assessment's `evidence_digests` must match those final evidence digests. The proposal payload digest is SHA-256 of canonical JSON for the final operations serialized as GEWU v1 contract records. Recompute it after adding/removing/changing any operation. If the client cannot reproduce these rules, stop before submission and report that digest generation is unavailable.
+
 `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.

protocols/EVIDENCE.md

@@ -2,6 +2,8 @@
 
 Read exact source revisions and immutable extraction maps supplied by the service. Bind each factual assertion or field to source/extraction IDs, location, quote and assertion digest under the published schema. For node claims, use the exact `claims[n].text`, `assumptions[n].text` or `limitations[n].text` assertion path that owns the statement; claim IDs must be unique across all three groups. A local extraction may help prepare a draft; it cannot impersonate the service's archived revision or locator map.
 
+Capture does not register a source. For new captures, use the exact returned source candidate in a `register_source` proposal operation, or cite a source revision already accepted and readable in GEWU. Cite the capture's exact source revision and extraction IDs. Finish the assertion text and evidence set before computing bindings: evidence `assertion_digest` and assessment `assertion_digest` bind to the normalized exact claim text, while assessment `evidence_digests` bind to the complete final evidence objects. If text or evidence changes, recompute all dependent digests and the containing proposal payload digest as described in [the contribution protocol](CONTRIBUTIONS.md#register-sources-and-bind-evidence).
+
 Record material assumptions and limitations as their own evidence-backed claim groups. Do not bury them in a summary or infer them from conditions on an edge. Each statement needs its own support assessment bound to its exact assertion and evidence, and it appears separately in the read interface. If the source does not establish a proposed assumption or limitation, keep it explicitly unsupported or omit it.
 
 Quote occurrence, semantic support, source reliability, model confidence and freshness are different assessments. A matching quote does not establish that the number, unit, population or qualifiers support the assertion. Record support rationale and the actual assessor. Routine same-agent assessment is allowed when policy permits; do not describe it as independent human review.

skills/kb-ingest/SKILL.md

@@ -6,10 +6,12 @@ description: Process explicitly selected sources for a GEWU project into evidenc
 
 Read the pack's [evidence](../../protocols/EVIDENCE.md), [scope](../../protocols/SCOPE.md) and [contribution](../../protocols/CONTRIBUTIONS.md) protocols, then use the [ingestion pipeline](../../pipelines/ingest.md).
 
-Inputs are the selected source(s), explicit project and the user's research objective. Use `get_project_context` for the project's north star, key questions, watch list, taxonomy extensions, research lenses and saved ingest guidance. Every project defaults to four research lenses: technical, conceptual, cultural-historical and financial-market. Treat these as coverage prompts, not quotas. Verify the supported tool/schema contract, including `ingest_review_create` when borderline-review intake is available. Use the connector for local byte transfer; it returns a typed source metadata candidate without exposing the selected path or bytes. Selected `.vtt` and `.srt` files produce timestamped transcript cues; cite exact cue start/end times and the quote span. A declared NotebookLM export label is metadata only and is not export verification. For text explicitly pasted by the user, use `source_capture_text` with a stable capture ID and source key; it accepts UTF-8 plain text or Markdown up to 1 MB, archives and extracts it, and returns a typed candidate marked `capture_method=pasted-text`. Retry uncertain calls with the same capture ID and identical inputs; changed input under that ID conflicts. It does not register the candidate. `source_capture_url` fetches only operator-allowlisted public hosts and stages supported text, Markdown, HTML or PDF bytes; it also returns a source metadata candidate but does not register it. Submit candidates with the normal typed proposal flow, and use `capture-failed` candidates only as bookmarks, never as factual evidence. URL source IDs follow the sanitized URL; local source IDs follow the connector's configured file ID; pasted-text source IDs are derived from the supplied stable key and revision IDs include the content digest. PDF extraction currently requires Linux bubblewrap, Poppler and prlimit. Unsupported formats and unavailable parsers must be reported without inventing an extraction. If the service is unavailable, report the blocked stage and only prepare an unaccepted local draft when that work was requested.
+Inputs are the selected source(s), explicit project and the user's research objective. Use `get_project_context` for the project's north star, key questions, watch list, taxonomy extensions, research lenses and saved ingest guidance. Every project defaults to four research lenses: technical, conceptual, cultural-historical and financial-market. Treat these as coverage prompts, not quotas. Verify the supported tool/schema contract, including `ingest_review_create` when borderline-review intake is available. Use the connector for local byte transfer; it returns a typed source metadata candidate without exposing the selected path or bytes. Selected `.vtt` and `.srt` files produce timestamped transcript cues; cite exact cue start/end times and the quote span. A declared NotebookLM export label is metadata only and is not export verification. For text explicitly pasted by the user, use `source_capture_text` with a stable capture ID and source key; it accepts UTF-8 plain text or Markdown up to 1 MB, archives and extracts it, and returns a typed candidate marked `capture_method=pasted-text`. Retry uncertain calls with the same capture ID and identical inputs; changed input under that ID conflicts. It does not register the candidate. `source_capture_url` fetches only operator-allowlisted public hosts and stages supported text, Markdown, HTML or PDF bytes; it also returns a source metadata candidate but does not register it. Add each new source's exact candidate as `register_source` in the proposal that cites it, or verify the source was already registered and readable. Use the candidate's `revision_id` and capture's `extraction_id`; never invent or substitute these IDs. Submit candidates with the normal typed proposal flow, and use `capture-failed` candidates only as bookmarks, never as factual evidence. URL source IDs follow the sanitized URL; local source IDs follow the connector's configured file ID; pasted-text source IDs are derived from the supplied stable key and revision IDs include the content digest. PDF extraction currently requires Linux bubblewrap, Poppler and prlimit. Unsupported formats and unavailable parsers must be reported without inventing an extraction. If the service is unavailable, report the blocked stage and only prepare an unaccepted local draft when that work was requested.
 
 Extract useful atomic assertions, problems, techniques or cases with their conditions across all four lenses where the source contains relevant material. Consider cultural history, philosophical context and market/financial evidence as project data when they explain the project's origins, concepts, adoption, audience, costs or viability; they are not automatically peripheral. First try to connect uncertain material to the north star, a key question, a saved rule or one of the lenses. Exclude only clearly unrelated material, unavailable evidence, or material the user explicitly excluded. Do not defer a section merely because its relevance is indirect, non-technical or historical. Continue normal evidence-backed proposal evaluation/submission for all plausible useful findings. When a human should review relevance or categorization, submit a bounded `ingest_review_create` flag with the exact extraction excerpt/locator, lens, summary and reason before finalizing the associated proposal facets. This persists for notification/filtering and never blocks the evidence-backed proposal flow.
 
+Before building each proposal, use the principal ID assigned to the configured agent credential for `proposer_id`, node `agent_id` and assessment `assessor_id`; do not use the model or harness name. Finish each claim and its evidence before computing `assertion_digest` or `evidence_digests`. Evidence assertion paths must point to their exact claim field. Recompute the evidence and assessment digests after any claim/evidence edit, then recompute `payload_digest` after any operation edit. Follow the exact canonical digest rules in [CONTRIBUTIONS.md](../../protocols/CONTRIBUTIONS.md#build-attributable-proposals) and [EVIDENCE.md](../../protocols/EVIDENCE.md). If the identity or digest inputs are unknown, stop and report the missing information rather than guessing.
+
 For `tags`, `audience`, `use_for` and `domain`, inspect the `facet_labels` catalog returned by `get_project_context`. Reuse a canonical project label when its meaning fits; do not create spelling, phrasing or singular/plural variants. Propose only useful, evidence-backed labels, with at most five tags and three labels in each other facet (14 total). Prefer `candidate_facet_labels` entries shaped as `{facet, value, definition}` so a genuinely new concept has a concise, distinguishing definition (500 characters max). Legacy `candidate_tags`, `candidate_audience`, `candidate_use_for` and `candidate_domain` fields remain valid for labels that do not need a definition. Leave uncertain labels out. Jev compares agent-proposed candidates with the closest project labels and chooses an existing label or the `new_label` option; it does not invent the proposed label text. The backend may add only a distinct new candidate that Jev ranks in that facet's configured top N (tags: up to five; other facets: up to three) and that clears its fit, new-label and confidence thresholds. An existing-label match is reused rather than duplicated. For the associated proposal, use Jev's selected canonical existing label for that facet. Use a new candidate as a project vocabulary label only when `added_to_project` is true; otherwise omit it from the proposal facets and leave its evidence-backed finding intact. Treat returned `jev_facet_resolutions` as the recorded decision; never claim a label was added unless `added_to_project` is true. Label promotion requires the server's local embedding model and Jev configuration; without them the candidate remains only a review signal. Label decisions only normalize facets; they do not gate evidence assessment, proposal submission or acceptance.
 
 If available, Jev also assesses relevance and lens in the same advisory call. Use the saved scores to focus human review; they are not evidence assessment or an instruction to silently rewrite accepted knowledge. When a reviewer decides, record the feedback and apply reusable project guidance only when the reviewer explicitly opts in. Preserve the service's exact source/extraction/location bindings. Map each factual field to evidence; assess semantic support separately. Record clear exclusions and genuinely skipped/deferred sections. Optimize for useful coverage rather than maximum note count.