chore: OSS hardening — community files, gitignore, scratch cleanup

[TexasCoding]

Summary

Companion PR to the GitHub repo-settings hardening already applied via the gh CLI. Adds the on-repo side and clears scratch.

What changed at the repo-settings level (already applied)

• Branch protection on main — required status checks (test (3.12), test (3.13), drift-check), linear history (enforces squash-merge), no force-push, no branch deletions, conversation-resolution required. claude-review deliberately not required since it fails by design on workflow-self-modifying PRs and Dependabot PRs.
• Dependabot security updates + vulnerability alerts enabled. Separate from the weekly version-bump Dependabot already configured.
• Private vulnerability reporting enabled.
• Wiki disabled (was unused; small attack surface).
• Discussions enabled for community Q&A.

What this PR adds

Community files (lifts GitHub community-profile score 42% → 100%)

• SECURITY.md — disclosure policy, supported versions table (2.x ✅ / 1.x ❌), scope, response timeline, in-tree security measures inventory.
• CODE_OF_CONDUCT.md — references Contributor Covenant v2.1 by canonical URL with project-specific reporting channel (private vuln reporting).
• CONTRIBUTING.md — dev setup, conventions (mirrors CLAUDE.md), PR checklist.
• .github/ISSUE_TEMPLATE/bug_report.yml — structured bug form with SDK/Python version, env (demo/prod), reproducer, traceback, pre-flight checks.
• .github/ISSUE_TEMPLATE/feature_request.yml — problem-first feature template.
• .github/ISSUE_TEMPLATE/config.yml — disables blank issues; redirects security to Private Vulnerability Reporting, questions to Discussions, Kalshi-API questions to Kalshi support.
• .github/PULL_REQUEST_TEMPLATE.md — standard scaffold matching the workflow used across the v2.0 PRs.

Cleanup

• Deleted .planning/ — 6 audit reports from the v2.0 hardening wave. Preserved in git history (commit 3ab4617); no longer needed on main.
• Deleted scripts/audit_demo_feasibility.py — one-off v0.10–v0.13 endpoint feasibility probe; not part of supported tooling. Other scripts/*.py (real release/spec-sync tooling + WS diagnostic helpers) retained.
• Purged 92 .DS_Store files from the working tree.

.gitignore additions

**/.DS_Store, .planning/, .claude/worktrees/, .venv.stale* — keeps the patterns above out of future commits.

Test plan

• No code touched in kalshi/; existing CI will be trivially green
• .github/ISSUE_TEMPLATE/*.yml validated by GitHub on parse
• Branch protection's required checks (test (3.12) / test (3.13) / drift-check) all pass on docs-only diffs

[claude]

Code Review — PR #151: OSS Hardening (Community Files + Cleanup)

Overview

This is a pure docs/infrastructure PR. No changes to kalshi/, no model or resource edits, no test mutations. CI will be trivially green. The scope is well-executed and the PR description is thorough.

---

What this PR adds

Community files — well-structured throughout:

• SECURITY.md — clear scope, realistic timelines, in-tree controls inventory
• CODE_OF_CONDUCT.md — delegates to Contributor Covenant v2.1 by URL (good: avoids duplication drift)
• CONTRIBUTING.md — mirrors CLAUDE.md conventions accurately; PR checklist is accurate and actionable
• Issue templates (bug/feature/config) — YAML forms with required fields, pre-flight checks, proper security redirect; these are solid
• PR template — matches the style used in v2.0-era PRs

Cleanup:

• .planning/ deletion is correct — audit findings are tracked in GitHub Issues (WS reconnect/resubscribe: 5 race-condition bugs in the recv loop #77–#106), the files are in history, no loss
• .gitignore additions are clean (**/.DS_Store global pattern, .claude/worktrees/, .venv.stale*, .planning/)
• Deleting scripts/audit_demo_feasibility.py is correct — it was a v0.10–v0.13 one-off probe, not part of supported tooling

---

Issues

Medium — SECURITY.md claims spec-sync has contents: read only; audit-O found it had contents: write

SECURITY.md (line 786 in diff):

Spec-sync workflow runs with contents: read only; it cannot push, open PRs, or execute upstream-derived Python.

The deleted audit-O-security.md (finding F-O-01, severity high) found the opposite:

The workflow runs on a weekly cron with contents: write and pull-requests: write, then opens a PR.

If that hardening happened in a prior merged PR this is fine — SECURITY.md is correct. But if .github/workflows/spec-sync.yml still carries the elevated permissions, this claim is false and creates a false sense of security.

Action: Before merging, verify .github/workflows/spec-sync.yml's permissions: block. If it still has contents: write / pull-requests: write, either update SECURITY.md to accurately describe the current state, or raise a follow-up issue to tighten the permissions. A document that misstates a control is worse than no document.

---

Minor — CoC reporting channel is unconventional

CODE_OF_CONDUCT.md routes CoC complaints through GitHub's Private Vulnerability Reporting:

Use GitHub's Private Vulnerability Reporting, even for non-security issues — this gives a private channel direct to maintainers.

GitHub's security advisory flow triggers vulnerability-specific workflows (CVE triage, CVSS scoring UI, security alert emails). Using it for CoC incidents will confuse both reporters and GitHub's automated tooling. The standard approach is a dedicated email address or a direct DM channel on a relevant platform.

Suggestion: Add a maintainer contact email (even a throwaway forwarding alias) as the primary CoC reporting channel. Private Vulnerability Reporting can remain as a secondary fallback.

---

Nit — uv sync --dev vs uv sync in CONTRIBUTING.md

CONTRIBUTING.md dev setup uses:

uv sync --dev

CLAUDE.md documents:

uv sync

uv sync already installs dev dependencies from pyproject.toml's [tool.uv] / dev extras. The --dev flag may be a no-op or slightly different behavior depending on the uv version. Worth aligning with what CLAUDE.md documents to avoid confusion for first-time contributors following this file.

---

No concerns

• All .DS_Store removals are correct; .gitignore pattern will prevent recurrence
• Issue templates are well-scoped — the security redirect in bug_report.yml and config.yml is exactly right
• feature_request.yml leading with "What problem does this solve?" (not "What feature do you want?") is good practice
• CONTRIBUTING.md's contract-drift section and *Request model conventions are accurately documented
• PR template matches the v2.0 PR style (Summary / Changes / Test plan / Notes / Issue links)
• Deleting .planning/ is clean; the wave-tracking history in v1.1-waves.md is preserved in git if ever needed

---

Summary

Approve pending verification of the spec-sync.yml permissions claim in SECURITY.md. Everything else is solid. No changes needed to kalshi/; CI will pass as-is.

---

Reviewed by Claude Code

[TexasCoding]

Three items addressed:

• ✅ SECURITY.md spec-sync permissions claim — verified accurate. .github/workflows/spec-sync.yml permissions block is contents: read + issues: write, locked in by PR security(spec-sync): harden against upstream compromise #109 (Wave 1 security/spec-sync hardening). No change needed.
• 🟡 CoC channel routed through Private Vulnerability Reporting — fixed. You're right that PVR is wired into security-advisory tooling and conflating channels confuses reporters + maintainers. CODE_OF_CONDUCT.md now points at direct GitHub-profile contact; reserves PVR for actual vulnerabilities per SECURITY.md.
• 🟦 uv sync --dev → uv sync — aligned with CLAUDE.md.

[claude]

Code Review — PR #151: OSS Hardening (Community Files + Cleanup)

Overall: Solid housekeeping PR. No kalshi/ code is touched, so runtime behavior is unchanged. The community files are well-written and follow the project's established conventions. A few issues worth resolving before merge.

---

Overview

This PR adds GitHub community-profile files (SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, issue templates, PR template), cleans up .planning/ audit archives and a one-off script, purges .DS_Store files, and extends .gitignore. All changes are additive infrastructure/docs.

---

Issues

🔴 SECURITY.md makes claims that may not match the current repo state

SECURITY.md lists these security measures as active:

• Nightly pip-audit workflow against the resolved dev environment.
• Spec-sync workflow runs with contents: read only; it cannot push, open PRs, or execute upstream-derived Python.
• Third-party Actions SHA-pinned in workflows that hold elevated permissions (release, spec-sync, claude review).

The audit report being deleted (audit-O-security.md) found the opposite of two of these as active issues:

• F-O-01 (high): spec-sync.yml runs with contents: write, pull-requests: write, not contents: read. A compromise of docs.kalshi.com + auto-merge path could propagate to PyPI.
• F-O-02 (medium): claude.yml and claude-code-review.yml use mutable @v4/@v1 tags, not SHA pins.
• F-O-07 (medium): No pip-audit workflow existed at audit time.

The PR description says these were "already applied via the gh CLI," but this diff doesn't show any changes to .github/workflows/. If those workflow files were already updated in a prior commit on this branch (or squashed into main), the claims are fine. If not, the document is actively inaccurate about the repo's security posture.

Request: Confirm (or show in this PR) that spec-sync.yml has been ratcheted down to contents: read, that the Claude workflows have been SHA-pinned, and that a pip-audit step exists somewhere. If those changes are on a separate branch, link to it. A security document that overstates controls is worse than no document.

---

🟡 CODE_OF_CONDUCT.md reporting contact is vague

contact a project maintainer directly via their GitHub profile (DM or the email listed there)

GitHub profile DMs require the reporter to identify the right maintainer and for that maintainer to have DMs open. Most CoC templates use a dedicated email address (e.g. conduct@…) so the reporter has a stable, role-based address that doesn't depend on any individual's GitHub settings.

This is low priority for a small repo but worth noting if you ever expect external contributors.

---

🟡 CONTRIBUTING.md references the claude-review check as addressing feedback

PRs receive automated code review from Claude (the `claude-review` check). 
Address the feedback or explicitly justify skipping it in a PR reply.

The PR description explicitly notes that claude-review is not a required status check (it "fails by design on workflow-self-modifying PRs and Dependabot PRs"). Telling contributors to address Claude's feedback when it's not required, and when it fails silently on some PR types, could be confusing. Consider softening to "may receive automated code review" or clarifying it's advisory.

---

🟡 PR template has a bare Closes # placeholder

Closes #

When submitted without filling this in, GitHub parses Closes # as invalid (no issue number) and ignores it — so it won't cause a problem. But it could confuse contributors into thinking they must reference an issue. Consider using:

<!-- Closes #N if this PR addresses a tracked issue -->

---

Looks Good

• Issue templates are well-structured. The bug_report.yml requiring SDK version + Python version + minimal reproducer is exactly right for triage. The config.yml correctly routes security reports to Private Vulnerability Reporting and Kalshi API questions out of this repo entirely.
• .gitignore additions are all appropriate. **/.DS_Store with the glob is the right way to catch nested macOS noise.
• .planning/ deletion is the correct call — these are now tracked as GitHub Issues (WS reconnect/resubscribe: 5 race-condition bugs in the recv loop #77–#106), and the audit content is preserved in git history as noted.
• scripts/audit_demo_feasibility.py deletion is clearly right; the file's own docstring confirms it was a one-off v0.10–v0.13 probe.
• CONTRIBUTING.md mirrors CLAUDE.md closely without duplicating it, which is the right split. The pointer to METHOD_ENDPOINT_MAP for new endpoint registration is particularly useful for outside contributors.
• SECURITY.md scope section (in-scope / out-of-scope) is well-drawn and accurate for an SDK.

---

Summary

The blocking question is whether the security measures claimed in SECURITY.md are actually in place in .github/workflows/. If those workflow hardening changes exist and are confirmed, this is ready to merge after the minor copy edits above.

[TexasCoding]

Addressed all four items from this round:

• 🔴 SECURITY.md vs actual workflow state — verified all three claims; one was overstated:
  • ✅ spec-sync.yml: contents: read + issues: write (PR security(spec-sync): harden against upstream compromise #109, Wave 1) — already correct.
  • ✅ Nightly pip-audit: .github/workflows/pip-audit.yml exists.
  • ⚠️ SHA pinning: claude.yml, claude-code-review.yml, spec-sync.yml were pinned; release.yml was not. Bot was right to flag. Now SHA-pinned every third-party action in release.yml (checkout/setup-uv/upload-artifact/download-artifact/pypi-publish/action-gh-release) so the SECURITY.md claim matches reality.
• 🟡 CoC reporting via GitHub profile — acknowledged. Solo-maintainer repo at the moment; manufacturing a conduct@ alias for one person and a barely-used CoC reporting channel would be theater. Direct-DM contact is honest about the current scale. If contributor volume grows enough that a role address starts to matter, that's a good problem to have and a separate change.
• 🟡 CONTRIBUTING.md claude-review wording — fixed. Now says it's advisory, not required, and fails by design on Dependabot / workflow-self-modifying PRs.
• 🟡 PR template bare Closes # — wrapped in an HTML comment with a note that the section can be deleted if no issue is referenced.

[claude]

Code Review — PR #151: OSS Hardening (Community Files, Gitignore, Scratch Cleanup)

Overview

A clean, no-code-change PR. The additions are community/governance infrastructure; the deletions are internal planning artifacts and a one-off audit script. No kalshi/ Python was touched, so there are no runtime regressions to worry about. CI will be trivially green.

---

Release Workflow SHA-Pinning ✅

This is the best part of the PR. All six third-party actions in release.yml are now pinned to exact commit SHAs with inline version comments — exactly the pattern the audit report (F-O-02) recommended and that spec-sync.yml already demonstrated. Addresses the supply-chain risk on the highest-privilege workflow in the repo.

Also noticed attestations: true is now present on the pypa/gh-action-pypi-publish step — that's the F-O-12 fix shipped quietly here. Good.

---

Community Files

SECURITY.md — Content is solid. Scope table, reporting channel, response timeline, and in-scope/out-of-scope lists are all appropriate. Two items to double-check:

1. Nightly pip-audit workflow — the security measures inventory says "Nightly pip-audit workflow against the resolved dev environment" exists. F-O-07 from the audit recommended adding this but it wasn't present at the time. Is this workflow actually merged, or is this aspirational language that belongs in a future PR? If it doesn't exist yet, this line should be removed to avoid misleading reporters who check the inventory.

2. spec-sync permissions claim — "Spec-sync workflow runs with contents: read only; it cannot push, open PRs, or execute upstream-derived Python." The audit (F-O-01) found it ran with contents: write + pull-requests: write. If spec-sync was hardened in a prior PR as part of the v2.0 wave, this statement is accurate — but the spec-sync.yml diff is not included here to confirm. Worth a quick git grep to verify the claim before merge, since SECURITY.md is exactly the place reporters will look.

CODE_OF_CONDUCT.md — Correct and concise. The clarification that Private Vulnerability Reporting is not the CoC channel (and why) is a nice touch that prevents a real operational confusion.

CONTRIBUTING.md — Well-written. Mirrors CLAUDE.md cleanly. One small note: the checklist references uv run mypy kalshi/ but doesn't mention the --strict flag that CI enforces. A new contributor who runs bare mypy kalshi/ and sees no errors may still fail CI. Consider uv run mypy kalshi/ # strict mode; see CLAUDE.md or just uv run mypy kalshi/ with a note that CI runs strict.

---

Issue Templates

bug_report.yml — Required fields (SDK version, Python version, environment, reproducer) are the right ones. The render: python on the reproducer textarea is a nice touch. Pre-flight checklist forces duplicate-search and latest-version confirmation. No issues.

feature_request.yml — Problem-first structure is correct. render: python on the proposal textarea is appropriate. No issues.

config.yml — Blank issues disabled, three contact links correctly scoped (security, questions, Kalshi API). No issues.

---

PR Template

One rendering bug in .github/PULL_REQUEST_TEMPLATE.md:

Closes #<!-- N -->

The <!-- N --> is an HTML comment — it renders as invisible, leaving the line as Closes # with nothing after it. GitHub will not close any issue, and the author won't see the broken syntax in the preview (comments are stripped). The intent is clear but the execution doesn't work. Suggest either:

Closes #N

(plain text that authors replace), or:

<!--
Use `Closes #N` to auto-close on merge, or `Refs #N` for partial work.
Delete this section if the PR doesn't reference an issue.

Closes #N
-->

---

Deletions

• .planning/ removal — Appropriate. The six audit documents captured valuable technical debt (79 findings, converted to 30 issues). Removing them from the tree now that they've been converted to issues is the right call. The note that they're preserved in history is accurate.
• scripts/audit_demo_feasibility.py — Correct to remove a one-off probe script. The remaining scripts/ tooling (release, spec-sync, WS diagnostics) is still useful.
• .DS_Store purge — 92 files cleared. The .gitignore pattern **/.DS_Store prevents recurrence.

---

.gitignore

All four additions (**/.DS_Store, .planning/, .claude/worktrees/, .venv.stale*) are sensible. No concerns.

---

Summary

Approve with minor items:

1. SECURITY.md pip-audit claim — verify the nightly workflow exists before merge, or remove the claim.
2. SECURITY.md spec-sync permissions — verify spec-sync.yml actually has contents: read now.
3. PR template Closes #<!-- N --> — fix so the placeholder works as intended.

None of these block the CI-level changes or the community file additions; items 1–2 are factual accuracy concerns in the security policy, and item 3 is a minor usability fix for future contributors. Everything else is clean.