docs: require protocol contract evidence

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: false
+contact_links: []

.github/ISSUE_TEMPLATE/general.yml

@@ -0,0 +1,35 @@
+name: General issue
+description: Report a bug or request work that does not change EntryPoint/UMDF contracts
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For EntryPoint/UMDF templates, fields, enums, or schema changes, use a Protocol form instead.
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Describe the problem, evidence, and affected behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Expected outcome
+      description: Describe the result without prescribing unsupported protocol contracts.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+    validations:
+      required: true
+  - type: checkboxes
+    id: protocol
+    attributes:
+      label: Protocol scope
+      options:
+        - label: This issue does not add or change an EntryPoint/UMDF template, field, enum value, or schema.
+          required: true

.github/ISSUE_TEMPLATE/protocol-change.yml

@@ -0,0 +1,59 @@
+name: Protocol implementation
+description: Implement an EntryPoint/UMDF contract proven in a published B3 schema
+title: "protocol: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This form is only for contracts that already exist in a published B3 schema.
+        If the requested template or field is absent, use the Protocol research form.
+  - type: dropdown
+    id: source
+    attributes:
+      label: Contract source
+      options:
+        - Existing vendored B3 schema
+        - Published B3 schema upgrade
+    validations:
+      required: true
+  - type: input
+    id: schema
+    attributes:
+      label: Schema file and version
+      placeholder: schemas/b3-market-data-messages-2.2.0.xml, schema version 16
+    validations:
+      required: true
+  - type: input
+    id: template
+    attributes:
+      label: Template name and ID
+      placeholder: SecurityStatus_3, template ID 3
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Field and enum evidence
+      description: Cite exact schema fields, enum members, generated types, and source links.
+    validations:
+      required: true
+  - type: textarea
+    id: dependency
+    attributes:
+      label: Cross-repo implementation evidence
+      description: Link the merged upstream PR/commit. An upstream issue proposal is insufficient.
+      placeholder: Not applicable, or link to merged implementation
+    validations:
+      required: true
+  - type: checkboxes
+    id: gates
+    attributes:
+      label: Contract checks
+      options:
+        - label: I verified that the requested template, fields, and enum values exist in the cited schema.
+          required: true
+        - label: I will not hand-edit a vendored schema or invent a proprietary SBE contract.
+          required: true
+        - label: If implementation differs from this proposal, I will correct the issue before downstream work depends on it.
+          required: true

.github/ISSUE_TEMPLATE/protocol-research.yml

@@ -0,0 +1,47 @@
+name: Protocol research
+description: Investigate a contract that is absent or uncertain in current B3 schemas
+title: "research(protocol): "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Research issues do not authorize implementation. They must end with either
+        published schema evidence or a documented blocked/not-planned conclusion.
+  - type: textarea
+    id: need
+    attributes:
+      label: Product need
+      description: Describe the behavior needed without prescribing a new wire message.
+    validations:
+      required: true
+  - type: textarea
+    id: current-schema
+    attributes:
+      label: Current schema evidence
+      description: Cite the vendored schema version and the closest existing templates/fields.
+    validations:
+      required: true
+  - type: textarea
+    id: sources
+    attributes:
+      label: Published-source investigation
+      description: List B3 schema releases, changelogs, and specifications that must be checked.
+    validations:
+      required: true
+  - type: textarea
+    id: trigger
+    attributes:
+      label: Implementation trigger
+      description: State the exact published template/field evidence required before implementation can begin.
+    validations:
+      required: true
+  - type: checkboxes
+    id: gates
+    attributes:
+      label: Research boundary
+      options:
+        - label: This issue will not create a proprietary SBE template or modify a vendored schema.
+          required: true
+        - label: Any later implementation issue will cite the published schema and exact contract members.
+          required: true

.github/copilot-instructions.md

@@ -117,7 +117,15 @@ Layered projects under `src/` (build order roughly bottom-up):
   per-session firm assignment is not implemented.
 - **Schemas are vendored.** Do not hand-edit files under `schemas/`; regenerate
   the SBE bindings in `B3.*.Sbe` when upgrading and mirror the change in
-  `B3MarketDataPlatform` (UMDF) / `B3EntryPointClient` (EntryPoint).
+  `B3MarketDataPlatform` (UMDF) or `B3EntryPointClient` (EntryPoint). This is
+  enforced by the "Vendored schema guard" CI job, which requires the
+  `schema-upgrade` label on any PR touching `schemas/`.
+- **Protocol claims require schema evidence.** Before implementing an
+  EntryPoint/UMDF field, enum, or template, cite its vendored schema version,
+  template ID, and exact members. Cross-repo dependencies must cite the merged
+  implementation, not only an issue proposal. If the contract is absent,
+  stop at research/blocker status; do not invent proprietary SBE messages or
+  raw enum values.
 
 ## Configuration
 

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What changed and why? -->
+
+## Validation
+
+<!-- Commands or checks run. -->
+
+## Protocol contract
+
+<!-- Delete this section when the PR does not touch EntryPoint/UMDF. -->
+
+- [ ] Cites the vendored schema version and exact template ID.
+- [ ] Cites every field and enum value written or consumed.
+- [ ] Uses generated schema members/constants instead of invented raw values.
+- [ ] Cross-repo dependencies point to a merged implementation, not only an issue proposal.
+- [ ] Does not hand-edit a vendored schema except for a verified published B3 upgrade.
+- [ ] Updates the issue/closing note if implementation differs from the original proposal.

AGENTS.md

@@ -174,6 +174,26 @@ Quick reminders (the full rule list is in `CONTRIBUTING.md`):
 - `TreatWarningsAsErrors=true` is global — a new warning is a build
   break.
 
+### 9. Prove protocol contracts before implementing them
+
+For any EntryPoint/UMDF request, inspect the vendored XML before accepting
+the issue wording as fact. Record the schema version, template name/ID,
+fields, and enum values in the issue or PR.
+
+- Cross-repo dependencies must cite the merged PR/commit that implements
+  the wire shape, not only the upstream issue that proposed it.
+- If the template or field is absent, report the work as blocked/research.
+  Never invent a proprietary SBE message or hand-edit the vendored schema.
+- Do not encode raw literals for schema enums merely because a consumer
+  needs distinct values. Use generated enum members/constants and pin them
+  in wire tests.
+- If implementation diverges from the issue proposal, correct the issue or
+  leave an explicit closing comment before downstream work is filed.
+
+PR #582 / issue #581 is the canonical failure mode: a proposed
+`InstrumentStatus_NN` was treated as an implemented contract even though
+the merged code emitted `SecurityStatus_3`.
+
 ## What belongs in prompts, not here
 
 This file holds conventions that apply to **every contributor and

CONTRIBUTING.md

@@ -110,3 +110,30 @@ or UMDF, regenerate the SBE bindings in `B3.*.Sbe` and mirror the
 change in the companion repo (`B3MarketDataPlatform` for UMDF,
 `B3EntryPointClient` for EntryPoint). The repos must agree on the
 schema version.
+
+This is enforced by the **Vendored schema guard** CI job
+(`.github/workflows/ci.yml`), which fails any PR touching `schemas/`
+unless it carries the `schema-upgrade` label. The rules below are
+review-time discipline for evidence and scope; the CI job is the
+deterministic backstop against unreviewed hand-edits.
+
+### Protocol contract evidence gate
+
+Any issue or PR that changes, adds, or consumes an EntryPoint/UMDF field,
+enum value, or template must cite:
+
+- the vendored schema file and version;
+- the exact template name and ID;
+- the field names and enum values used;
+- the implemented upstream PR or commit when the dependency is cross-repo.
+
+An upstream issue proposal is not evidence that a wire contract exists.
+If the requested template or field is absent, stop at a research/blocker
+issue until B3 publishes it. Do not create a proprietary SBE template or
+write an out-of-domain raw enum value to approximate the missing contract.
+
+When implementation differs from an issue proposal, the PR and closing
+comment must state what was actually delivered so downstream work does not
+inherit the abandoned design. Wire tests should use generated schema types
+or constants and assert the emitted template ID, block length, and enum
+values.