Rewrite core library, add outlier rejection, characterization harness, and full tooling

.cursor/rules/bug_report.mdc

@@ -0,0 +1,79 @@
+---
+description: Standards for writing clear, reproducible bug reports with severity, evidence, and environment details.
+alwaysApply: false
+---
+
+# Bug Report Standards
+
+## 1. Core Components
+
+Every bug report MUST include:
+
+- **Clear title** — Describes the symptom and its location (e.g., "`Profile.from_file` raises KeyError on valid FITS header").
+- **Reproduction steps** — Numbered, minimal steps (ideally a short script) anyone can follow.
+- **Expected vs. actual behavior** — Side-by-side comparison.
+- **Environment** — Python version, OS, package version, relevant dependency versions.
+- **Severity** — Assessed per the scale below.
+- **Evidence** — Tracebacks, log output, or screenshots of incorrect results.
+
+## 2. Severity Scale
+
+| Level | Criteria |
+|-------|----------|
+| **Critical** | Crash, data corruption, silent wrong results, or security vulnerability. |
+| **High** | Major feature broken or blocking for many users. |
+| **Medium** | Non-critical feature broken or produces degraded results. |
+| **Low** | Minor issue, documentation error, or cosmetic problem. |
+| **Trivial** | Very minor issue with negligible user impact. |
+
+## 3. Report Template
+
+```markdown
+# Bug Report: [Concise title]
+
+## Description
+[1-2 sentences: what is broken and its impact.]
+
+## Environment
+- **Python version**: [e.g., 3.12.4]
+- **OS**: [e.g., Ubuntu 24.04, macOS 14.5, Windows 11]
+- **Package version**: [e.g., rms-psfmodel 0.3.1]
+- **Key dependency versions**: [e.g., numpy 2.2.1, scipy 1.14.0]
+- **Installation method**: [e.g., pip install rms-psfmodel, editable install]
+
+## Severity
+[Level] — [Brief justification]
+
+## Steps to Reproduce
+1. Install: `pip install rms-psfmodel==0.3.1`
+2. Run:
+   (Example)
+3. Observe the error.
+
+## Expected Behavior
+[What should happen.]
+
+## Actual Behavior
+[What actually happens, including the full traceback.]
+
+## Traceback / Logs
+[Paste full traceback or relevant log output here]
+
+## Additional Notes
+[Workarounds, frequency, related issues.]
+
+## Possible Fix
+[Optional: suspected root cause or fix direction.]
+```
+
+## 4. Writing Guidelines
+
+1. Be objective and factual — no blame or subjective language.
+2. One issue per report.
+3. Include exact version numbers and full tracebacks.
+4. Keep reproduction steps as short as possible while remaining unambiguous.
+5. Verify the bug is reproducible before submitting.
+
+## 5. Adaptation
+
+Adjust the template for the project's GitHub Issues and add project-specific fields (e.g., affected data set, mission, instrument).

.cursor/rules/dependency_management.mdc

@@ -0,0 +1,53 @@
+---
+alwaysApply: true
+description: Standards for declaring, installing, and maintaining Python project dependencies.
+---
+
+# Dependency Management
+
+## 1. Single Source of Truth
+
+- Declare ALL dependencies in **`pyproject.toml`** under `[project]` (PEP 621).
+- Do NOT maintain a separate hand-written `requirements.txt` for runtime dependencies. If a `requirements.txt` is kept, it should contain only `-e .` for backward compatibility.
+
+## 2. Dependency Groups
+
+| Group | Section | Install command | Purpose |
+|-------|---------|-----------------|---------|
+| **Runtime** | `[project].dependencies` | `pip install .` | Required for the package to function. |
+| **Dev** | `[project.optional-dependencies].dev` | `pip install -e ".[dev]"` | Testing, linting, type-checking, coverage. |
+| **Docs** | `[project.optional-dependencies].docs` | `pip install -e ".[docs]"` | Sphinx and documentation extensions. |
+
+## 3. Version Constraints
+
+- Specify **minimum** compatible versions for direct dependencies (e.g., `numpy>=2.2.0`).
+- Do NOT pin exact versions (`==`) in library projects; exact pinning belongs in lock files or application deployments.
+- For dev/docs dependencies, specify minimum versions to ensure consistent tool behavior across contributors.
+
+## 4. Adding or Updating Dependencies
+
+1. Add the dependency to the correct section in `pyproject.toml`.
+2. Run `pip install -e ".[dev]"` (or the relevant group) to verify installation.
+3. Run the full test suite and type-check to confirm compatibility.
+4. Commit the `pyproject.toml` change with a `build:` commit type.
+
+## 5. Security and Maintenance
+
+- Run `pip audit` in CI to catch known vulnerabilities.
+- Enable automated dependency update tooling (Dependabot, Renovate).
+- Review update PRs for breaking changes before merging.
+- Periodically remove unused dependencies to reduce attack surface.
+
+## 6. Tooling Configuration
+
+Consolidate all tool configuration into `pyproject.toml` where supported:
+
+| Tool | Section |
+|------|---------|
+| pytest | `[tool.pytest.ini_options]` |
+| coverage | `[tool.coverage.run]`, `[tool.coverage.report]` |
+| mypy | `[tool.mypy]`, `[[tool.mypy.overrides]]` |
+| ruff | `[tool.ruff]`, `[tool.ruff.lint]` — use explicit `select = [...]` for E, F, W, I, UP, B, SIM, C4, A, N, PT, RUF (see python_best_practices) |
+| setuptools_scm | `[tool.setuptools_scm]` |
+
+Do NOT create separate config files (`.coveragerc`, `.mypy.ini`, `.flake8`, `setup.cfg`) when the tool supports `pyproject.toml`.

.cursor/rules/documentation.mdc

@@ -0,0 +1,38 @@
+---
+alwaysApply: true
+description: Standards for Python library documentation using Sphinx, ReadTheDocs, and docstrings.
+---
+
+# Documentation Standards
+
+## 1. Documentation System
+
+- Use **Sphinx** for all project documentation, hosted on **ReadTheDocs**.
+- After any code or doc change, run `sphinx-build` on the full documentation tree and fix all warnings and errors before delivering.
+
+## 2. Documentation Standard
+
+- NEVER use unicode characters such as smart quotes, em-dashes, or arrows in source code files (such as .py) in docstrings or comments. They are acceptable in .rst and .md files. They are also acceptable in source code strings when needed to present special characters to the user such as degree signs or arrows at runtime.
+
+## 3. Required Documentation
+
+| Document | Contents | Keep up-to-date? |
+|----------|----------|-------------------|
+| **Module index** | Every module that exists or is planned (placeholders for future modules). | Yes |
+| **Architecture overview** | Class hierarchy, public API surface, and interface contracts. | Yes |
+| **Install guide** | `pip install` instructions, supported Python versions, optional dependencies. | Yes |
+| **Usage examples** | Common workflows with code snippets and expected output. | Yes |
+| **README** | Project summary, PyPI/ReadTheDocs badges, quickstart, and links to full docs. | Yes |
+
+## 4. Docstrings
+
+- EVERY class, method, function, and module MUST have a descriptive docstring.
+- Follow **PEP 257** using **Google style** with `Parameters:` (not `Args:`).
+- Include `Returns:` and `Raises:` only if there are return values or exceptions raised.
+- Include behavioral notes sufficient to write a black-box test but do not reference the internal details of the code.
+- Wrap docstring text to **90** characters.
+
+## 5. Change Discipline
+
+- Any code change MUST update the relevant docstrings and the README if affected.
+- NEVER leave stale or contradictory documentation. If a feature is removed, remove its docs.

.cursor/rules/environment_best_practices.mdc

@@ -0,0 +1,40 @@
+---
+description: Git, CI/CD (GitHub Actions), virtual environments, and tooling for development and publishing.
+alwaysApply: true
+---
+
+# Environment Best Practices
+
+## 1. Source Control
+
+- ALWAYS use **git** for all source code.
+- Commit early and often with meaningful messages (see `git_workflow.mdc`).
+
+## 2. CI/CD
+
+- ALWAYS use **GitHub Actions** for continuous integration and publishing.
+- Every PR MUST pass lint (`ruff`), type-check (`mypy`), test (`pytest`), Markdown lint (`PyMarkdown`), and documentation build (`sphinx-build`) jobs before merge.
+- Pin action versions to a major tag (e.g., `actions/checkout@v6`) to balance stability and security updates.
+- Publishing to PyPI is triggered by creating a GitHub Release from a version tag on `main`.
+
+## 3. Environment Isolation
+
+- ALWAYS use `python -m venv` (or `virtualenv`) to create an isolated virtual environment. Activate it before any `pip install`.
+- NEVER install project dependencies into the system Python.
+- Record the supported Python version range in `pyproject.toml` via `requires-python` (e.g., `>=3.10`).
+- Test across all supported Python versions in CI using a matrix strategy.
+
+## 4. Editor Settings (VSCode / Cursor)
+
+The repository includes `.vscode/settings.json` so all contributors get consistent formatting:
+
+- **Indent**: 4 spaces (no tabs).
+- **Trailing whitespace**: Trimmed on save.
+- **Final newline**: Exactly one newline at end of file; excess trailing blank lines removed on save.
+- **Line length**: Rulers at 80, 90, and 100 characters (max 100 enforced by Ruff).
+
+## 5. Secrets and Configuration
+
+- NEVER commit secrets, tokens, or credentials. Use environment variables or GitHub Secrets.
+- Use `.env` files for local development only; ensure `.env` is in `.gitignore`.
+- Validate required environment variables at startup with clear error messages.

.cursor/rules/git_workflow.mdc

@@ -0,0 +1,66 @@
+---
+description: Conventional commits, branching, and PR workflow for source control and code review.
+alwaysApply: false
+---
+
+# Git Workflow
+
+## 1. Commit Messages
+
+Use the **Conventional Commits** format:
+
+```
+<type>[(<scope>)]: <imperative summary>   (50 chars max for subject)
+
+[Optional body — wrap at 72 chars. Explain *what* and *why*, not *how*.]
+
+[Optional footer — e.g., Closes #123, BREAKING CHANGE: description]
+```
+
+### Allowed types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New user-facing feature or public API addition. |
+| `fix` | Bug fix. |
+| `docs` | Documentation-only change. |
+| `style` | Formatting, whitespace — no logic change. |
+| `refactor` | Code restructure with no behavior change. |
+| `perf` | Performance improvement. |
+| `test` | Adding or updating tests only. |
+| `build` | Build system or dependency change. |
+| `ci` | CI/CD configuration change. |
+| `chore` | Maintenance tasks that don't fit above. |
+
+### Rules
+
+- Subject line MUST be imperative mood ("Add X", not "Added X" or "Adds X").
+- Subject line MUST NOT exceed 50 characters.
+- Do NOT end the subject line with a period.
+- Separate subject from body with a blank line.
+- Body lines MUST NOT exceed 72 characters.
+- Reference related issues in the footer.
+- Each commit MUST represent one logical change. Do NOT mix unrelated changes.
+
+## 2. Branching Strategy
+
+This project uses a simple two-tier branching model:
+
+- **`main`** — Always releasable. Protected; requires PR review and passing CI. Releases are created by tagging commits on `main`.
+- **`feature/<name>`** — New features or enhancements, branched from `main`.
+- **`bugfix/<name>`** — Bug fixes, branched from `main`.
+
+There are NO separate release, hotfix, or develop branches. All work merges back to `main` via pull request.
+
+## 3. Pull Requests and Merging
+
+- ALWAYS create a PR for merging into `main`; direct pushes are prohibited.
+- PRs MUST pass all CI checks (lint, type-check, tests) before merge.
+- Prefer **squash merge** to keep `main` history linear and readable.
+- Delete the source branch after merge.
+
+## 4. Tagging and Releases
+
+- Tag releases on `main` with semantic versioning: `v<MAJOR>.<MINOR>.<PATCH>`.
+- Let `setuptools_scm` derive the package version from tags automatically.
+- Creating a GitHub Release from the tag triggers the PyPI publish workflow.

.cursor/rules/how_to.mdc

@@ -0,0 +1,74 @@
+---
+description: Guidelines for writing user-facing how-to documentation with steps, prerequisites, and troubleshooting.
+alwaysApply: false
+---
+
+# How-To Documentation
+
+## 1. Audience and Tone
+
+- Write for **Python users** who are familiar with `pip` and the command line but may not know the library's internals.
+- Use clear, direct language; define domain-specific terms on first use.
+- Focus on what the user needs to do and what they should observe.
+
+## 2. Best Practices
+
+1. **Action-oriented title** — e.g., "How To Process a Cassini Image", not "Image Processing Overview".
+2. **Brief introduction** — 1-3 sentences explaining purpose and value.
+3. **Prerequisites** — Python version, package installation, required data or environment variables.
+4. **Numbered steps** — One action per step in logical order. Include code snippets for API usage or CLI commands.
+5. **Expected results** — State what the user should see after each significant step AND in a summary section at the end. Keep both consistent.
+6. **Troubleshooting** — Common failures (import errors, missing data, version mismatches) and their fixes.
+7. **Related features** — Mention next steps or related guides.
+
+## 3. Document Structure
+
+```markdown
+# How To [Action]
+
+[1-3 sentence introduction explaining purpose and value.]
+
+## Prerequisites
+
+- Python >= 3.10
+- `pip install rms-<package>`
+- [Any required data, environment variables, or configuration]
+
+## Steps
+
+1. Import the module:
+   ```python
+   from package import SomeClass
+   ```
+2. [Action]. You should see [result].
+3. [Action].
+
+## Expected Results
+
+[Summary of the successful end state — expected output, files created, etc.]
+
+## Troubleshooting
+
+- **[Problem]**: [Solution].
+
+## Additional Information
+
+[Tips, performance notes, or links to related guides.]
+```
+
+## 4. Converting Technical Content
+
+When turning docstrings, test scripts, or internal notes into How-To guides:
+
+1. Identify the user-facing feature or workflow.
+2. Determine the target audience (library user, CLI user, contributor).
+3. Extract user actions from technical steps.
+4. Translate internal terminology to user-friendly language.
+5. Add code examples, expected output, and troubleshooting.
+
+## 5. Diagrams and Figures
+
+- **When to use**: Multi-step workflows, data pipelines, or architecture that is clearer as a visual.
+- **Placement**: Inline, immediately after the relevant step or section.
+- **Format**: Prefer Mermaid diagrams (e.g., rendered by Sphinx via `sphinxcontrib-mermaid`) for process flows. Use PNG/SVG for screenshots or data visualizations.
+- **Naming**: Descriptive filenames (e.g., `backplane-pipeline.svg`). Include alt text for accessibility.

.cursor/rules/pull_request.mdc

@@ -0,0 +1,37 @@
+---
+description: PR structure, purpose, implementation details, testing evidence, and review checklist.
+alwaysApply: false
+---
+
+# Pull Request Standards
+
+## Scope of review
+
+Treat the PR as a **single unit of change**. The diff to review is the set of all commits on the current branch back to its **immediate root** (the merge-base with the target branch). Consider the net result of those commits together; do **not** comment on differences that exist only between commits within the PR (e.g. "you fixed X in a later commit" or "commit 2 undid part of commit 1"). Review the final state of the branch against the base.
+
+## Principles
+
+1. **Descriptive title** — Summarize the change in an imperative sentence (e.g., "Add caching to profile lookup").
+2. **Purpose first** — Explain *why* the change is needed before *how* it was done.
+3. **Scope** — One logical change per PR. Split unrelated changes into separate PRs.
+4. **Testing evidence** — Document automated and manual testing performed.
+5. **Impact assessment** — Note potential effects on the public API, performance, or dependent packages (Potential Impacts section).
+6. **Linked issues** — Reference related GitHub issues using `Closes #NNN` syntax.
+
+## Template
+
+The PR template is in `.github/pull_request_template.md` and is applied automatically when a new PR is opened. Fill out every section:
+
+- **Purpose** — Why the change is needed; link issue with `Closes #NNN`.
+- **Changes / Implementation Details** — What changed and how it was implemented; technical approaches chosen and non-obvious design decisions.
+- **Type of Change** — Check all that apply (bug fix, feature, breaking, refactor, docs, tests, CI/build).
+- **Testing** — Check boxes for unit tests, integration tests, E2E tests run; describe new tests added and manual verification performed.
+- **Potential Impacts** — Public API, backward compatibility, performance, downstream; write "None" if straightforward.
+- **Checklist** — Style, mypy, docs, CHANGES.md, no debug code, no secrets/credentials, no warnings/errors, performance impact assessed, breaking changes flagged.
+- **Notes** — Optional; delete only if not needed (tricky areas, follow-up work).
+
+## Guidance
+
+- **Library-specific** — Call out public API changes, deprecations, and migration notes in Potential Impacts.
+- **Required reviewers** — Tag maintainers for changes to core modules.
+- **Brevity vs. completeness** — Short enough that authors fill everything out; detailed enough for a reviewer with no other context.