repo files

Author: hunterhogan

.github/copilot-instructions.md

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

.serena/.gitignore

@@ -0,0 +1,39 @@
+- Naming/labels:
+  - use camelCase, full words, no abbreviations, no single-character identifiers, no bare `_`
+  - callables should read as explicit subject-verb-object where practical
+  - preserve domain casing/spelling for AST names, column names, exported symbols, mapping keys, filenames
+  - filesystem semiotics: `path` = directory, `filename` = name only, `pathFilename` = full path
+- Formatting:
+  - `.editorconfig` then `pyproject.toml`/`ruff.toml` are authoritative
+  - preserve existing formatting/alignment; do not rewrite unrelated style
+  - Python code uses tabs; multiline calls/ordered sequences prefer leading commas; order-agnostic collections use trailing commas
+  - semantic line breaks, operators at line starts on continuations, closing delimiters on their own lines when elements span lines
+- Syntactic clarity:
+  - optimize for left-to-right parsing; avoid deferred/hidden operators in complex expressions
+  - replace ambiguous numeric adjustments with semantic identifiers from shared SSOT modules when available
+  - normalize comparisons toward `<` / `<=`
+  - prefer absolute imports from public APIs; package root exports are the public surface
+- Types:
+  - keep annotations complete and precise; no `Any`, no bare `object`, no weak containers
+  - use PEP 585/604 syntax; prefer `Sequence`/`Mapping` for read-only params
+  - prefer `TypedDict`, `Protocol`, `TypeVar`, and `@overload` over weak typing patterns
+  - do not add annotation-only bindings or destroy tuple unpacking just to annotate
+- Post-defensive style:
+  - once inputs are validated, trust invariants internally
+  - do not add truthiness/emptiness/None guards or silent recovery for impossible states
+  - let no-op-capable operations no-op naturally
+  - single return point by default; avoid artificial loop limits
+  - do not introduce high-blast-radius destructive operations like new `shutil.rmtree` usage
+- Diagnostics:
+  - assign diagnostic text to `message: str` before `raise`/warn/log
+  - use first-person observed-state wording (`I received ...`, `I could not find ...`)
+  - include actual runtime values; use backticks around identifiers in prose
+- Docstrings/comments:
+  - do not add docstrings or comments unless requested/necessary
+  - when docstrings are requested, use modified NumPy style: triple double quotes, full-stop summary, no reST/LaTeX, no `Notes` section, real usage examples, references section; add `(AI generated docstring)` only for newly created docstrings
+- Tests:
+  - pytest style; one test function per function/class under test
+  - every test uses `@pytest.mark.parametrize`
+  - all fixtures belong in `tests/conftest.py`
+  - use deterministic, distinctive data; every assertion needs a descriptive message
+  - prefer MCP test runners for execution.