Docs/community cleanup 1.2.x

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,80 @@
+name: Bug report
+description: Something in bdsim doesn't behave as documented.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please fill in what you observed vs. what
+        you expected. Include enough detail (config snippet + sim settings) to
+        reproduce.
+
+        For **security** issues, see [SECURITY.md](../SECURITY.md) instead —
+        do not file them publicly.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      placeholder: |
+        Describe the bug. Include a minimal `run_with(...)` or
+        `LiveSimulator(...)` snippet that reproduces the issue.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      placeholder: |
+        Describe the expected behaviour (cite docs / equations / paper).
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: bdsim version
+      placeholder: "1.2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.10.x"
+    validations:
+      required: true
+
+  - type: input
+    id: stack
+    attributes:
+      label: numpy / scipy / numba versions
+      placeholder: "2.2.6 / 1.15.3 / 0.66.0"
+    validations:
+      required: true
+
+  - type: input
+    id: seed
+    attributes:
+      label: Random seed used (if any)
+      placeholder: "42"
+
+  - type: textarea
+    id: fingerprint
+    attributes:
+      label: Trajectory fingerprint (if applicable)
+      placeholder: |
+        Paste the truncated SHA-256 of the affected trajectory array
+        (`sv`, `pv`, `uv`). Compare to the pinned value in `tests/` and
+        `docs/00-orientation/Byte-identical-contract.md`.
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / stack trace
+      placeholder: |
+        Paste the full error output, including the Numba JIT traceback if
+        one is present.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,56 @@
+name: Feature request
+description: Propose a new ProcessFaults knob, a doc change, or a new feature.
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing a feature. Please describe the problem you're
+        trying to solve and your proposed API. Maintainers will review.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      placeholder: |
+        What is the workflow or research question you can't address with
+        the current API? Cite the docs page if relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed API
+      placeholder: |
+        Sketch the proposed field names, defaults, and where they'd live
+        in `ProcessFaults` / `Settings` / `SensorFaults` / `LiveSimulator`.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      placeholder: |
+        Did you consider a workaround with the current knobs? Why doesn't
+        it suffice?
+
+  - type: textarea
+    id: fingerprint-impact
+    attributes:
+      label: Trajectory impact
+      placeholder: |
+        Does the feature change the ODE state vector (`sv`) width, the
+        input vector (`uv`), or the published measurement vector (`pv`)?
+        Will it affect any pinned fingerprint profile?
+
+  - type: textarea
+    id: docs
+    attributes:
+      label: Docs updates needed
+      placeholder: |
+        Which docs files would need updates?
+        `docs/30-engine/Config-surface.md`,
+        `docs/40-helpers/Channel-indices.md`, etc.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Pull Request
+
+Thanks for contributing! Please fill in the sections that apply.
+
+## What
+
+<!-- One-sentence summary of the change. -->
+
+## Why
+
+<!-- The motivation. What bug does it fix or feature does it add? -->
+
+## Fingerprint impact
+
+- [ ] No fingerprint change (default-off / no ODE change)
+- [ ] Fingerprint bump — old pin ↔ new pin:
+
+| profile  | old               | new               |
+|----------|-------------------|-------------------|
+| legacy   | `<hash>…`         | `<hash>…`         |
+| dynamic  | `<hash>…`         | `<hash>…`         |
+| runtime  | `<hash>…`         | `<hash>…`         |
+
+## Tests
+
+- [ ] `uv run python -m pytest tests/ -q` passes locally
+- [ ] New test added (if behaviour changed)
+- [ ] `uv run ruff check bdsim/ tests/` clean
+
+## Docs
+
+- [ ] Updated [`Config-surface.md`](docs/30-engine/Config-surface.md) (if a
+      `ProcessFaults` field was added / renamed)
+- [ ] Updated [`Channel-indices.md`](docs/40-helpers/Channel-indices.md) (if
+      `sv` / `pv` / `uv` widths changed)
+- [ ] Updated [`Byte-identical-contract.md`](docs/00-orientation/Byte-identical-contract.md)
+      (if a new pinned profile was added)
+- [ ] Updated [`CHANGELOG.md`](CHANGELOG.md) under `[Unreleased]`
+
+## Notes for reviewers
+
+<!-- Anything else reviewers should know: tradeoffs, follow-ups, etc. -->
+
+---
+
+By submitting this PR you agree your contributions are licensed under GPLv3+
+(the same license as the project; see [`LICENSE`](LICENSE)).

ADMIN.md

@@ -10,7 +10,7 @@ The person who keeps bdsim installable, runnable, and reproducible on this box (
 
 Use this path whenever you run the fingerprint suite or need trajectories that match the pinned hashes in `tests/`.
 
-**Reference stack for bdsim 1.1.1 pins:** Python **3.10** + committed [`uv.lock`](uv.lock) → `numpy==2.2.6`, `scipy==1.15.3`, `numba==0.66.0` (macOS arm64 reference host). Source of truth is the lockfile, not loose `pyproject.toml` ranges.
+**Reference stack for bdsim 1.2.0 pins:** Python **3.10** + committed [`uv.lock`](uv.lock) → `numpy==2.2.6`, `scipy==1.15.3`, `numba==0.66.0` (macOS arm64 reference host). Source of truth is the lockfile, not loose `pyproject.toml` ranges.
 
 From this repo's root:
 
@@ -89,23 +89,23 @@ uv run python -m pytest tests/test_smoke.py -q
 
 ## Fingerprint regression
 
-`tests/test_live_simulator.py` (and the per-Layer tests) pin SHA-256 fingerprints over the full trajectory. `tests/test_smoke.py` checks shapes, physical ranges, and determinism only — no SHA pins. A silent numerical drift in a kernel will fail loud.
+`tests/test_live_simulator.py` (and the per-feature tests) pin SHA-256 fingerprints over the full trajectory. `tests/test_smoke.py` checks shapes, physical ranges, and determinism only — no SHA pins. A silent numerical drift in a kernel will fail loud.
 
 Named profiles (see `docs/00-orientation/Byte-identical-contract.md` and `AGENTS.md`):
 
 | Path | Profile | Meaning | Hash |
 |---|---|---|---|
-| batch | runtime default (1.2.0+) | Bare `ProcessFaults()` enables Layers 2.5 + 2.1 + 2.4 (both) + 2.8a | `sv=691cf51b4c1a0bc2` `pv=baedc29fcfa8f526` `uv=4e4134e40fa0c1ad` |
-| batch | legacy fingerprint | Tests pass all Layer masters `False` (21-wide state) | `sv=c8807b23b14a9ad1` `pv=77def506dbfe25c9` `uv=17e620519474074a` |
-| batch | Layer 2.5 fingerprint | Dynamic HEX fouling, all other masters off (22-wide state) | `sv=696531c4990c5b1e` |
-| batch | Layer 2.5 + Layer 2.1 | `fouling_dynamic=True quality_state=True` (27-wide state) | `sv=d663e17d687b1133` |
-| batch | Layer 2.4 pump-only | `pump_wear=True`, no valve_wear / quality_state (23-wide state) | `sv=7ddd7aaa7da4b679` |
-| batch | Layer 2.4 valve-only | `valve_wear=True`, no pump_wear / quality_state (23-wide state) | `sv=9425d007ae968ee7` |
-| batch | Layer 2.4 both | `pump_wear=True valve_wear=True`, no quality_state (24-wide state) | `sv=c092fe082f4ba6f4` |
-| batch | Layer 2.6 (active disturbance) | Nonzero disturbance amplitudes, all other masters off | `sv=8865a8c352cb6b55` |
+| batch | runtime default (1.2.0+) | Bare `ProcessFaults()` enables dynamic fouling, quality latching, pump + valve wear, and the NIR/IR spectrum sensor | `sv=691cf51b4c1a0bc2` `pv=baedc29fcfa8f526` `uv=4e4134e40fa0c1ad` |
+| batch | legacy fingerprint | Tests pass all feature flags `False` (21-wide state) | `sv=c8807b23b14a9ad1` `pv=77def506dbfe25c9` `uv=17e620519474074a` |
+| batch | dynamic-fouling fingerprint | Dynamic HEX fouling, all other masters off (22-wide state) | `sv=696531c4990c5b1e` |
+| batch | dynamic-fouling + quality-latching | `fouling_dynamic=True quality_state=True` (27-wide state) | `sv=d663e17d687b1133` |
+| batch | pump-only actuator wear | `pump_wear=True`, no valve_wear / quality_state (23-wide state) | `sv=7ddd7aaa7da4b679` |
+| batch | valve-only actuator wear | `valve_wear=True`, no pump_wear / quality_state (23-wide state) | `sv=9425d007ae968ee7` |
+| batch | pump + valve wear | `pump_wear=True valve_wear=True`, no quality_state (24-wide state) | `sv=c092fe082f4ba6f4` |
+| batch | external disturbances (active) | Nonzero disturbance amplitudes, all other masters off | `sv=8865a8c352cb6b55` |
 | live | runtime default (1.2.0+) | Bare `ProcessFaults()` (`tf=14400 dt=10`) | `sv=80f6f04683703382` `pv=9e2b2081f469e473` `uv=c3a05be9a234fe2a` |
 | live | legacy fingerprint | Matching legacy knobs | `sv=23c3c885694c3d24` |
-| live | Layer 2.6 (active disturbance) | | `sv=bb763a9bde1d3fc9` |
+| live | external disturbances (active) | | `sv=bb763a9bde1d3fc9` |
 
 Runtime default (`ProcessFaults()`) is now the broad-defaults profile — `fouling_dynamic=True`, `quality_state=True`, `pump_wear=True`, `valve_wear=True`, `spectrum_enabled=True` (sv width 30). Tests and demos needing a narrower state must opt out explicitly via the relevant `*_state=False` / `*_wear=False` / `spectrum_enabled=False` overrides. When a fingerprint updates, that's a "we changed the math **or the numerical stack**" signal. Pins as of **1.2.0** match `uv.lock` (`numpy==2.2.6`, `scipy==1.15.3`, `numba==0.66.0`). Document the why in the commit body and update the pin in the test file. Don't suppress the test.