docs: api stability + contributing sections; issue/PR templates

Author: Lallapallooza

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Crash, hang, wrong result, or behaviour that diverges from the README
+title: ""
+labels: bug
+---
+
+## What happened
+
+A short description of the observed behaviour.
+
+## What you expected
+
+What the docs / type signature / contract led you to expect.
+
+## Reproduction
+
+A minimal source snippet, or a link to a fork with a failing test. The smaller the repro, the faster the fix.
+
+```cpp
+// minimal reproduction
+```
+
+## Environment
+
+- citor version (`git rev-parse HEAD` or `v` tag):
+- Compiler + version (`g++ --version`, `clang++ --version`, `cl`):
+- OS + kernel (`uname -a` on Linux, `winver` on Windows):
+- CPU model (`lscpu | grep "Model name"` on Linux):
+- CMake configure line you used:
+
+## Notes
+
+Anything else worth flagging: TSan output, ASan stack, sysfs oddity, NUMA layout, etc.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: A new primitive, hint field, platform, or contract surface
+title: ""
+labels: enhancement
+---
+
+## What you want
+
+The shape of the missing capability. If it's a primitive, sketch the signature.
+
+## Why
+
+A concrete workload that benefits. "Generally useful" by itself is not enough.
+
+## Alternatives considered
+
+Existing primitives or combinations you tried; why they fall short.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!-- A short PR description goes here. What and why. -->
+
+## Summary
+
+<!-- One or two sentences. What changes, what gets unblocked, what gets faster. -->
+
+## Type of change
+
+<!-- Tick whichever applies. -->
+
+- [ ] `fix`: bug fix
+- [ ] `feat`: new primitive, hint, or public surface
+- [ ] `perf`: measured performance change
+- [ ] `refactor`: internal restructure, no behaviour change
+- [ ] `docs`: README, CITATION, or in-tree comments
+- [ ] `test`: new test, no production code touched
+- [ ] `build` / `ci`: build system, packaging, workflows
+- [ ] `chore`: tooling, deps, releases
+
+## Test plan
+
+<!-- How you verified this. For perf: cell name + before/after JSON snippet. -->
+
+- [ ] `ctest --test-dir build --output-on-failure` (or the relevant subset)
+- [ ] `pre-commit run --all-files`
+- [ ] Bench evidence attached (for `perf` PRs)
+- [ ] Tested on Windows (for Windows-port PRs)
+
+## Notes for reviewers
+
+<!-- Anything reviewers should know: known limitations, follow-up work, alternative approaches considered. -->

README.md

@@ -1195,6 +1195,14 @@ scripts/                       pre-commit helpers (ctest, clang-tidy, doc-string
 
 Anything under `include/citor/{cpos,detail}/` is reachable but not part of the public API surface. Top-level headers in `include/citor/` (`thread_pool.h`, `hints.h`, `cancellation.h`, `chain.h`, `pool_group.h`, `function_ref.h`, `version.h`) are the user-facing entry points.
 
+## API stability
+
+citor is pre-1.0. The version scheme is semver, so `0.x` minor bumps may break source compatibility in principle. In practice the public surface (`include/citor/*.h` minus the `detail/` and `cpos/` subdirectories) has been stable across the last several releases and a breaking change is unlikely without a clear reason. Anything under `include/citor/detail/` is internal and changes freely.
+
+## Contributing
+
+Contributions, bug reports, and benchmark fairness fixes are welcome. Open an issue or a PR. For perf claims, include the host details and the `parallel_bench --export` JSON so the numbers reproduce. For bench-shape complaints (a peer pool wired in a way that disadvantages it, a missing competitor, an unfair workload), open an issue with the cell name and a proposed fix.
+
 ## License
 
 MIT. See [`LICENSE`](LICENSE).