From e190c8f7b88806cff429afc51dec7f4c146fc134 Mon Sep 17 00:00:00 2001 From: Pedro Sakuma Travi <39205549+pedrosakuma@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:56:54 +0000 Subject: [PATCH] docs: require protocol contract evidence Add separate implementation and research issue forms, disable blank issues, and require schema/template evidence in contributor and agent workflows. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/config.yml | 2 + .github/ISSUE_TEMPLATE/general.yml | 35 ++++++++++++ .github/ISSUE_TEMPLATE/protocol-change.yml | 59 ++++++++++++++++++++ .github/ISSUE_TEMPLATE/protocol-research.yml | 47 ++++++++++++++++ .github/copilot-instructions.md | 6 ++ .github/pull_request_template.md | 18 ++++++ AGENTS.md | 20 +++++++ CONTRIBUTING.md | 21 +++++++ 8 files changed, 208 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/general.yml create mode 100644 .github/ISSUE_TEMPLATE/protocol-change.yml create mode 100644 .github/ISSUE_TEMPLATE/protocol-research.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..8005e322 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,2 @@ +blank_issues_enabled: false +contact_links: [] diff --git a/.github/ISSUE_TEMPLATE/general.yml b/.github/ISSUE_TEMPLATE/general.yml new file mode 100644 index 00000000..1d3e2717 --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/protocol-change.yml b/.github/ISSUE_TEMPLATE/protocol-change.yml new file mode 100644 index 00000000..6f6cdb03 --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/protocol-research.yml b/.github/ISSUE_TEMPLATE/protocol-research.yml new file mode 100644 index 00000000..0421c35a --- /dev/null +++ b/.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 diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2091e40a..d23f18db 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -116,6 +116,12 @@ Layered projects under `src/` (build order roughly bottom-up): - **Schemas are vendored.** Do not hand-edit files under `schemas/`; regenerate the SBE bindings in `B3.*.Sbe` when upgrading and mirror the change in `SbeB3UmdfConsumer`. +- **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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..06cc58e8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,18 @@ +## Summary + + + +## Validation + + + +## Protocol contract + + + +- [ ] 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. diff --git a/AGENTS.md b/AGENTS.md index f9fc1bca..343b2be7 100644 --- a/AGENTS.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c20d4ce9..d5de95f3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -109,3 +109,24 @@ Do not hand-edit files under `schemas/`. When upgrading B3 EntryPoint or UMDF, regenerate the SBE bindings in `B3.*.Sbe` and mirror the change in the companion `SbeB3UmdfConsumer` repo. The two repos must agree on the schema version. + +### 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.