Add ROADMAP, issue/PR templates, and discussion routing

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: An ordersim run produced behavior that contradicts the documented model.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time. This template is for cases where the
+        observed behavior diverges from what the docs or equivalence tests
+        claim. For open-ended questions, use
+        [Discussions](https://github.com/tradingexpert/ordersim/discussions)
+        instead.
+  - type: input
+    id: version
+    attributes:
+      label: ordersim version
+      description: Output of `pip show ordersim` or your editable install commit.
+      placeholder: "0.1.3"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11.7"
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      placeholder: "macOS 14.5 arm64 / Ubuntu 22.04 x86_64 / ..."
+    validations:
+      required: true
+  - type: dropdown
+    id: engine
+    attributes:
+      label: Engine
+      description: Which engine produced the observation?
+      options:
+        - Python reference engine
+        - Compiled C++ engine
+        - Both (divergence between them)
+        - Not sure
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What the documented model — or the other engine — would produce.
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Event-stream excerpt, traceback, or other concrete observation.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Smallest snippet or fixture that exhibits the divergence.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: Optional context, hypotheses, or links to related issues/discussions.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Open-ended question or discussion
+    url: https://github.com/tradingexpert/ordersim/discussions
+    about: Conceptual questions, microstructure modeling debates, or anything not yet a concrete bug or feature.
+  - name: Editorial context
+    url: https://marketsinproduction.com/ordersim/
+    about: The Markets in Production page for ordersim — positioning, scope, and the wider essay context.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,43 @@
+name: Feature request
+description: Propose a new capability, modeling primitive, or API addition.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ordersim aims for clarity per line of code over feature breadth.
+        Requests that fit the inspectable-execution-replay scope are
+        welcome; requests that turn this into a general backtester or a
+        live trading system are out of scope.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What execution question would this answer?
+      description: |
+        Frame the proposal as the research or simulation question that
+        cannot currently be answered. "I want X" is harder to evaluate
+        than "I cannot currently tell whether Y happens because Z is not
+        modeled."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: API surface, modeling primitive, or behavior you have in mind.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        Workarounds you tried, related libraries, or reasons existing
+        primitives are not enough.
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This is about inspectable execution replay (in scope).
+        - label: I have read the "What It Is Not" section of the README.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!-- Thanks for sending a PR. Keep this short — what changed, why, and how it was checked. -->
+
+## What changed
+
+<!-- One or two sentences. -->
+
+## Why
+
+<!-- The question this answers, or the bug it fixes. Link the issue/discussion if there is one. -->
+
+## How it was checked
+
+- [ ] `pytest` passes locally.
+- [ ] If this touches the matching engine: Python and C++ engines still produce identical event logs against the equivalence fixtures.
+- [ ] If this changes observable behavior: a test fixture captures the new behavior.
+- [ ] If this changes the public API: docstrings, examples, and `CHANGELOG.md` updated.
+
+## Notes for review
+
+<!-- Anything worth flagging: tradeoffs you considered, alternatives you rejected, follow-ups you're deliberately leaving. -->

ROADMAP.md

@@ -0,0 +1,77 @@
+# Roadmap
+
+This is a direction document, not a commitment. The dates are deliberately
+omitted — the order of priorities is the useful information. Open issues and
+discussions are the working surface; this file exists so a new reader can see
+where the project is going without reading the whole tracker.
+
+## Near term — what's actively being shaped
+
+These are the questions that are likely to land first, in roughly the order
+they will probably arrive.
+
+- **Maker–taker fee modeling.** See [#40](https://github.com/tradingexpert/ordersim/issues/40).
+  The fee model is currently a uniform schedule; venue-realistic maker/taker
+  separation is needed before fee-sensitive strategy comparisons become
+  honest.
+- **Limit-order fill-connected strategies.** See [#39](https://github.com/tradingexpert/ordersim/issues/39).
+  Strategies that route their next action off the result of a fill — partial,
+  passive, or cancelled — are first-class research subjects. The gateway API
+  should make this ergonomic without leaking event-loop concerns into the
+  strategy code.
+- **Engine equivalence depth.** The Python and C++ engines must produce
+  identical event logs against the equivalence fixtures. New fixtures are
+  added as new fill paths get exercised. Equivalence is a release gate, not
+  an aspiration.
+
+## Middle distance — directions, not commitments
+
+- **Venue-specific matching behavior.** See the open
+  [Discussion](https://github.com/tradingexpert/ordersim/discussions). The
+  honest version of this is not a "supports venue X" matrix but a small set
+  of named matching primitives (price–time, pro-rata, price improvement
+  variants) that can be composed to match real venues, with the residual
+  uncertainty stated.
+- **Hidden-liquidity modeling.** See the open
+  [Discussion](https://github.com/tradingexpert/ordersim/discussions). The
+  unhelpful version of this is a tunable knob. The useful version is an
+  explicit assumption surface that a study can declare and a reviewer can
+  audit.
+- **More batch-ingest paths through the C++ engine** for callers that own
+  the event loop, while keeping the audited per-event `Replay(...)` path as
+  the reference for valuation marks.
+- **Examples that mirror Trading Reality essays.** Each essay that turns on
+  an execution mechanism should have a runnable companion in
+  `examples/`. The
+  [latency demo](examples/latency_demo.py) is the template; adverse
+  selection and queue-position essays are the natural next companions.
+
+## Out of scope — deliberately, not yet
+
+`ordersim` is a simulator. It will not turn into:
+
+- A general-purpose backtesting framework. You own the strategy loop.
+- A live trading system or order-routing gateway. The Python-facing API is
+  shaped so a production gateway can mirror it; the bridging code is yours.
+- A signal library or alpha repository.
+- A speed-first HFT framework. Compiled speed is welcome only when it
+  preserves observable behavior.
+
+These exclusions are how the surface stays inspectable.
+
+## Editorial context
+
+The conceptual frame for why these choices were made — and why "what an
+order did, in order, against this replay" is the unit of research — lives at
+[Markets in Production](https://marketsinproduction.com/ordersim/) and the
+[Trading Reality](https://www.tradingreality.com) publication. The roadmap
+should be read alongside that context, not separately from it.
+
+## Contributing
+
+Open a [Discussion](https://github.com/tradingexpert/ordersim/discussions)
+for anything that does not yet look like a concrete bug or feature. Issues
+labeled
+[`good first issue`](https://github.com/tradingexpert/ordersim/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+are the lowest-friction entry points. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the working agreement.