wenuray 1.0.0__tar.gz

wenuray-1.0.0/.aider.conf.yml

@@ -0,0 +1,4 @@
+# Aider reads the rules and the agent guide with every request
+read:
+- CONVENTIONS.md
+- AGENTS.md

wenuray-1.0.0/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/tools/hooks/block-protected-push.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

wenuray-1.0.0/.cursor/environment.json

@@ -0,0 +1,7 @@
+{
+  "build": {
+    "context": "..",
+    "dockerfile": "Dockerfile"
+  },
+  "install": "pip install -e '.[test]' -r docs/requirements.txt pre-commit"
+}

wenuray-1.0.0/.cursor/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "tools/hooks/block-protected-push.sh",
+        "matcher": "git push"
+      }
+    ]
+  }
+}

wenuray-1.0.0/.cursor/rules/README.md

@@ -0,0 +1,26 @@
+# Cursor project rules
+
+Conventions for Wenuray contributors and AI agents. Cursor loads every `.mdc` file in this directory according to its `description`, `globs` and `alwaysApply` frontmatter. `CONVENTIONS.md` at the repo root mirrors these files for other tools. Claude Code reads them through `CLAUDE.md`.
+
+| File | Topic |
+|------|-------|
+| [`general.mdc`](general.mdc) | Purpose of Wenuray and general principles — read first |
+| [`design.mdc`](design.mdc) | Parameter budget, config objects, rounds, policies, backends |
+| [`selfcal-domain.mdc`](selfcal-domain.mdc) | Self-calibration theory invariants |
+| [`casa-io.mdc`](casa-io.mdc) | CASA tools, Measurement Sets, files, subprocesses, FITS |
+| [`implementation.mdc`](implementation.mdc) | Clear purpose, explicit code, known types, reading data in samples |
+| [`naming.mdc`](naming.mdc) | Naming and method order |
+| [`documentation.mdc`](documentation.mdc) | Docstrings, comments, README/examples |
+| [`error-handling.mdc`](error-handling.mdc) | Validation, exceptions, logging |
+| [`testing.mdc`](testing.mdc) | pytest layout, CASA-free unit tests, simulated end-to-end tests |
+| [`cicd.mdc`](cicd.mdc) | GitHub Actions, packaging, containers, branches/commits |
+
+Naming, OOP and policy conventions follow [Pyralysis](https://gitlab.com/clirai/pyralysis) so the two projects read the same. Pyralysis's array-backend, precision and UML rules have no counterpart here. How agents use these rules, with skills and hooks, is in [`AGENTS.md`](../../AGENTS.md).
+
+## Keeping `CONVENTIONS.md` in sync
+
+The `.mdc` files are the source of truth. After editing them, regenerate the mirror:
+
+```bash
+python tools/sync_conventions.py
+```

wenuray-1.0.0/.cursor/rules/casa-io.mdc

@@ -0,0 +1,31 @@
+---
+description: Working with CASA tools/tasks, Measurement Sets, files and subprocesses safely
+globs:
+  - "src/**/*.py"
+alwaysApply: false
+---
+
+# CASA tools and tables
+
+- Don't create module-level tool singletons (`tb = table()`). Create the tool where it's needed and **always close it**, using `try/finally` or a small context manager (`with open_table(path) as tb:`). Close TaQL result tables too.
+- Call CASA tasks with keyword arguments only. Use the task's own parameter names.
+- Check that a column exists before reading it. Remember that virtual models carry no `MODEL_DATA` column.
+- CASA ≥ 6.6.4 needs measures data (`casaconfig`). Don't rely on a runtime download in tests or containers.
+
+# Files and directories
+
+- Never run shell commands to delete files (`os.system("rm -rf ...")`). Remove only paths Wenuray created itself, with `shutil.rmtree`/`Path.unlink`.
+- Put temporary products in a per-run directory (`tempfile.mkdtemp` under the output directory), never in the current working directory with fixed names.
+- Build paths with `pathlib.Path`. Don't concatenate strings or `partition(".ms")`.
+- A Measurement Set comes with a sibling `<ms>.flagversions` directory. Copying, moving or deleting the MS must handle both.
+
+# Subprocesses (external executables)
+
+- `subprocess.run([...], check=True)` with an argument **list**. No shell strings and no `shlex.split` of concatenated text.
+- Log the command, and surface the exit code and stderr in the raised exception.
+
+# FITS
+
+- Read data inside the `with fits.open(...)` block, or copy it. Don't return an HDU from a closed file.
+- NumPy image shapes are `(NAXIS2, NAXIS1)`.
+- Interpolate masks with nearest-neighbour (or threshold afterwards), never bilinear.

wenuray-1.0.0/.cursor/rules/cicd.mdc

@@ -0,0 +1,39 @@
+---
+description: GitHub Actions, containers, packaging and releases
+globs:
+  - ".github/**"
+  - "Dockerfile*"
+  - "pyproject.toml"
+  - ".pre-commit-config.yaml"
+alwaysApply: false
+---
+
+# GitHub Actions
+
+- Pin actions to a release tag (or SHA), never `@master`. Keep them current via `.github/dependabot.yml`.
+- Only push container images on pushes to default branches or tags, **never from `pull_request`**. PRs build with `push: false`.
+- Build images from the checked-out source (COPY the wheel or source), not `pip install git+...` of a branch.
+- Pure-Python jobs (lint, build, unit tests) run on `actions/setup-python` with pip caching, not in the CUDA image. Reserve the heavy image for GPU and integration jobs.
+- Use `GITHUB_TOKEN` with minimal `permissions:`. Publish to PyPI with trusted publishing (OIDC).
+- Add `concurrency:` groups so superseded runs are cancelled.
+- Lint in CI with `pre-commit run --all-files`, the same hooks as locally.
+
+# Packaging
+
+- `pyproject.toml` is the single source of metadata and dependencies. Use lower bounds in `dependencies`; put exact pins only in lock/constraint files for CI and Docker.
+- Declare only what is imported. Optional backends go in extras (e.g. `wenuray[pyralysis]`).
+- Version comes from setuptools-scm, read at run time with `importlib.metadata.version("wenuray")`; no version file is written.
+- `requirements.txt` is the pinned set for CI and Docker, generated with `uv pip compile pyproject.toml`.
+
+# Containers
+
+- Combine `apt-get update && apt-get install ... && rm -rf /var/lib/apt/lists/*` in one layer.
+- Pin external sources (tags or commit SHAs) cloned or downloaded during builds.
+- Use multi-stage builds: compile in a devel stage, run on a runtime base.
+
+# Branches, commits and releases
+
+- `development` is the integration branch and `master` the release branch. Work on `chg/<issue>-<slug>` or `fix/<issue>-<slug>` branches from `development` and open PRs into `development`. Never base a PR on another unmerged PR (squash merges strand it). Direct pushes to `development` and `master` are blocked by `tools/hooks/block-protected-push.sh` for agents.
+- Commit prefixes used in history: `CHG:` (change/feature) and `FIX:` (bug fix).
+- Reference the GitHub issue in commits and PRs (`Closes #25`).
+- Semantic versioning via git tags; releases publish to PyPI.

wenuray-1.0.0/.cursor/rules/design.mdc

@@ -0,0 +1,81 @@
+---
+description: Class design for Wenuray — one self-cal loop, CalibrationStep hierarchy, CalStack, schedule rules, imager contract, config objects, policies
+globs:
+  - "src/**/*.py"
+alwaysApply: true
+---
+
+# Architecture (see GitHub issues #22 and #23)
+
+```text
+Selfcal (the ONLY self-cal loop — template method)
+ ├── steps: CalibrationStep (ABC, frozen dataclass)
+ │     ├── Phasecal
+ │     └── _AmplitudeStep  (solnorm, amplitude prerequisites)
+ │           ├── Ampcal
+ │           └── AmpPhasecal
+ ├── imager: Imager (ABC; image() enforces the contract, subclasses implement _reconstruct)
+ ├── solver: GainSolver · acceptance: AcceptancePolicy · stack policy: StackPolicy
+ ├── workspace: MSWorkspace (snapshot / restore)
+ └── observers: SelfcalObserver (logging, plots, provenance)
+```
+
+# Inheritance: put it where behaviour varies
+
+- **The loop exists once**, in `Selfcal.run`. Never add a `run()` loop to a step or imager subclass.
+- Calibration types are **subclasses of `CalibrationStep`** because they differ in behaviour (prerequisites, normalisation, plotting, gaincal extras). Put what varies in `ClassVar`s and small hooks (`_extra_gaincal_kwargs`), and build everything shared once in the base class. Shared amplitude behaviour lives once in `_AmplitudeStep`.
+- A new calibration type = a new subclass plus its transition rules. The loop doesn't change.
+- Imagers subclass `Imager` and implement only `_reconstruct`. The public `image()` is final, so it can always enforce the contract.
+- Use a subclass when behaviour differs; use a field when only a value differs. Don't add `if calmode == ...` or `isinstance` branches in the loop.
+
+# Dataclasses
+
+- Steps, config objects (`Selection`, `SolveOptions`, `ApplyOptions`, `ImageGeometry`, `Weighting`), `CalTable`, `CalStack` and results are `@dataclass(frozen=True)`.
+- Use `KW_ONLY` so the primary value stays positional (`Phasecal("60s")`) and everything else is keyword-only. That keeps subclasses free to add defaulted fields.
+- Validate in `__post_init__`, once. Derive values with `dataclasses.replace(...)`, which rejects unknown names, never `setattr` by string.
+- No mutable defaults: use `field(default_factory=...)`, tuples or `MappingProxyType`.
+
+# multimethod: type dispatch at boundaries and for rules
+
+Use `multimethod` (as Pyralysis does) when behaviour depends on the **runtime types of the arguments**, instead of `isinstance` chains:
+
+- `check_transition(prev, step, stack)`: schedule rules dispatched on `(previous step type, next step type)`. Each theory rule is one overload with its own test.
+- Coercion at the API boundary: `solint_seconds(str | float)`, `to_casa_quantity(str | float | Quantity)`, `as_initial_stack(None | CalStack | SelfcalResult | str)`.
+
+Don't use it where ordinary polymorphism (a method on the class) is enough.
+
+# Calibration state and schedules
+
+- Calibration state is an immutable `CalStack` of `CalTable(path, step, spwmap, interp)`. Only `CalStack` builds `gaincal` pre-apply and `applycal` argument lists. `spwmap` is derived per table, never a user parameter.
+- Every solve pre-applies the accepted stack (the `StackPolicy` decides which tables are kept).
+- `Selfcal.__init__` validates the whole schedule by simulating the stack. A schedule that breaks calibration theory raises `ScheduleError` **before any I/O**. Continuing a run uses `Selfcal.resume(result, ...)`, never another object's internals.
+
+# Parameter budget
+
+- A public constructor takes **at most ~8 parameters**, all of them used. If you need more, group them into a config object or split the class.
+- Don't add a parameter that theory or the data can supply (spwmap, cell/imsize, noise-based thresholds).
+
+# Policies and strategies
+
+Follow the Pyralysis "Policies" convention ([`.cursor/rules/design.mdc` in Pyralysis](https://gitlab.com/clirai/pyralysis/-/blob/development/.cursor/rules/design.mdc)): one family per configurable decision, frozen dataclasses, the default is an instance, and policies decide but never act.
+
+- `AcceptancePolicy` (keep or roll back a round; `AllOf`/`AnyOf` combinators), `StackPolicy` (`Accumulate`, `ReplacePhase`), `GainSolver`.
+- Strings (`"tclean"`, `"ap"`, `"alma"`) only at the boundary (config files, CLI), turned into objects by one registry/factory per family. Third-party imagers register via the `wenuray.imagers` entry point.
+
+# Imagers (plug-ins)
+
+- The contract: image `CORRECTED_DATA` and write `MODEL_DATA` to the MS given in the request. `Imager.image()` invalidates the model first and verifies it afterwards, raising `ImagerContractError` if it wasn't written. It also refuses an imager whose `geometry.cell` is coarser than the Nyquist cell of the selected data (#60): visibilities beyond the grid can't be modelled. The opt-out is an explicit `Selection(uvrange=...)`, never a silent drop.
+- Imagers are stateless with respect to the MS (it arrives in every `ImagingRequest`).
+- Backend options pass through using the backend's own names (`tclean`'s `usemask`). Validate them against the backend's signature.
+- Every imager, including users' own, should pass `wenuray.testing.ImagerContractSuite`.
+- Image statistics are computed once, by `ImageStatistics`, for all imagers. Optional backends are extras with lazy imports.
+
+# Cross-cutting concerns and side effects
+
+- Logging, gain plots and provenance are `SelfcalObserver`s, not constructor flags.
+- No I/O in constructors. `MSWorkspace` owns snapshots, rollback and cleanup.
+- Keep argument building, rules and statistics pure, so they can be tested without CASA.
+
+# Backwards compatibility
+
+v1.0 replaces the legacy constructors. Legacy arguments (`visfile=`, `solint=[...]`, `previous_selfcal=`) raise a `TypeError` that shows the new call. Deprecated aliases emit `DeprecationWarning` and have a test showing they behave like the new form.

wenuray-1.0.0/.cursor/rules/documentation.mdc

@@ -0,0 +1,20 @@
+---
+description: Docstrings, comments, user docs and examples
+globs:
+  - "**/*.py"
+  - "**/*.md"
+alwaysApply: true
+---
+
+# Docstrings and comments
+
+- NumPy-style docstrings on every public class, method and function, with units and accepted values (e.g. `solint : str` — `"inf"`, `"60s"`, `"int"`).
+- For self-cal behaviour, state the **theory** assumption in the docstring (which column is solved and which tables are pre-applied).
+- Comments explain **why**, never what. Keep them sparse.
+
+# User documentation
+
+- The README and every example (`examples/<name>/recipe.toml` and `selfcal.py`) **must run against the current API**. When you change a public API, update them in the same PR. CI smoke-tests the examples.
+- Examples should be recipes a user can copy: a config file plus one command, not a script that parses `sys.argv` with `eval`.
+- Each example is a recipe a user can copy plus the Python script that builds the same run; a test keeps them equal.
+- Wenuray ships no instrument presets. Instrument-specific values in examples are marked as the example's, with links to CASA guides where relevant.

wenuray-1.0.0/.cursor/rules/error-handling.mdc

@@ -0,0 +1,13 @@
+---
+description: Exceptions, validation and logging
+globs:
+  - "**/*.py"
+alwaysApply: true
+---
+
+# Errors and logging
+
+- Validate configuration **early**, at construction or before the first round, with messages that say how to fix it (e.g. "spw selection starts at 1 but spwmap maps to 0").
+- Raise exceptions; never return sentinel values or swallow errors. Use `FileNotFoundError` for missing inputs, `ValueError` for bad values, and `TypeError` for wrong types.
+- Silent fallbacks that change the science (point-source model, wrong column, dropped table) must be **errors**, or at least explicit warnings.
+- Use `logging` (module logger `logging.getLogger(__name__)`), not `print`. Log each round's metrics at INFO.

wenuray-1.0.0/.cursor/rules/general.mdc

@@ -0,0 +1,32 @@
+---
+description: Wenuray purpose, scope, and general principles — read first
+globs:
+  - "**/*.py"
+alwaysApply: true
+---
+
+# What Wenuray is for
+
+Wenuray (ca**S**a pytho**N** self-calibrati**O**n frame**W**ork) exists so radio astronomers stop rewriting a one-off self-calibration script for every new dataset. A user should be able to describe a self-cal procedure **briefly, declaratively and reproducibly**, and rerun it on another dataset by changing only what really differs.
+
+Judge every change against that goal:
+
+- Does it make the user's procedure **shorter or clearer**? Prefer defaults derived from theory or the data over new user-facing parameters. Wenuray ships **no instrument presets**: users keep their own shared settings as TOML files (`preset = "group.toml"`), and limits that depend on an instrument or the science are opt-in, with no default value.
+- Does it keep runs **reproducible**? Same config + same input data + same versions must give the same result, and a run must record what it did.
+- Is it **correct by radio-interferometry theory**? See `selfcal-domain.mdc`. A convenient API that gives wrong calibration is worse than no API.
+
+Layers, from the user inward:
+
+1. **TOML recipe** (`wenuray run recipe.toml`) — what most users touch. A recipe is a serialisation of the Python objects, not a second API (`wenuray.recipe`).
+2. **Python API** (`Selfcal`, the `Phasecal`/`Ampcal`/`AmpPhasecal` steps, config objects) — for power users and scripting.
+3. **Backends** — CASA tasks (`gaincal`, `applycal`, `tclean`) and imagers (`Tclean`, `Pyralysis`, or a user's own through the `wenuray.imagers` entry point).
+
+The design was set in GitHub issue #22 (milestone "v1.0 redesign"); self-cal with the Pyralysis imager is #24. How agents work on the repository is in `AGENTS.md`.
+
+# General principles
+
+- Python version follows `requires-python` in `pyproject.toml`. It is `>=3.12,<3.14`, the overlap of the CASA wheels and Pyralysis (#30).
+- Keep code simple, readable and maintainable; avoid duplication (the three copied self-cal loops are the cautionary example).
+- PEP 8, formatted with `yapf` + `isort` (config in `setup.cfg`, column limit 100), enforced via `pre-commit`.
+- `pytest` for tests. New behaviour needs tests (see `testing.mdc`).
+- **Legacy code predates these rules.** New and changed code must follow them. Don't mass-refactor untouched code outside the scope of the issue you are working on; open or extend an issue instead.

wenuray-1.0.0/.cursor/rules/implementation.mdc

@@ -0,0 +1,28 @@
+---
+description: Implementation principles — clear purpose, explicit code, known types, data read in samples
+globs:
+  - "**/*.py"
+alwaysApply: true
+---
+
+# Implementation
+
+- Every class, function and module has one clear purpose. If its docstring needs "and", split it.
+- No global or module-level mutable state, and no module-level CASA tool instances (`casa-io.mdc`).
+  Code is as stateless as possible: config objects are frozen, and a run's state lives in the
+  loop and its result.
+- Prefer explicit code over implicit behaviour. No magic methods without a clear reason, no hidden
+  defaults that change the science.
+- **Dispatch on known types with `isinstance` or `multimethod`, never by probing attributes**
+  (`getattr(obj, "geometry", None)`). An optional capability is a base-class attribute or hook with
+  a documented default (e.g. `Imager.geometry = None`, `Imager.provenance()`).
+- **Read measurement sets in samples, never whole columns, when a statistic is enough.** Large
+  datasets have billions of visibilities: sample rows evenly (`selected_rows`), read blocks
+  spread through the selection (`preflight.read_sample`), and keep the cost independent of the
+  dataset's size. Read whole columns only when the operation needs every row (e.g. `uv_extent`
+  for the Nyquist check reads `u`, `v` and `FLAG_ROW`, never the visibilities).
+- Use NumPy vectorisation and broadcasting over Python loops on rows; loop over baselines,
+  spectral windows or tables, not over visibilities.
+- Profile before optimising (`cProfile`, `line_profiler`). Most of a run's time is in CASA tasks
+  and the imager; optimise Wenuray's own code only where a profile shows it matters.
+- Use the dtype's limits (`np.finfo(dtype).eps`) instead of hard-coded small constants.

wenuray-1.0.0/.cursor/rules/naming.mdc

@@ -0,0 +1,16 @@
+---
+description: Naming conventions and method order (aligned with Pyralysis)
+globs:
+  - "**/*.py"
+alwaysApply: true
+---
+
+# Naming
+
+- Classes `CamelCase` (`SelfcalPipeline`, `CalTable`); functions, methods and modules `snake_case`.
+- Functions start with a verb (`derive_spwmap()`, `build_applycal_args()`).
+- Plural names for collections (`steps`, `caltables`).
+- Use radio-astronomy / CASA terminology consistently: `solint`, `calmode`, `refant`, `spwmap`, `combine`, `MODEL_DATA`. Don't invent synonyms.
+- User-facing parameters that map onto a CASA parameter keep the **CASA name** (`usemask`, `minblperant`).
+- Private `__name`, protected `_name`. Inside a class, order methods private → protected → public.
+- Booleans read as predicates (`is_model_written`, `has_corrected_column`).

wenuray-1.0.0/.cursor/rules/selfcal-domain.mdc

@@ -0,0 +1,41 @@
+---
+description: Radio-interferometric self-calibration invariants every change must respect (gaincal/applycal/model/spwmap/acceptance)
+globs:
+  - "src/**/*.py"
+alwaysApply: true
+---
+
+# Self-calibration invariants
+
+These are domain rules, not style preferences. Code that breaks them produces wrong science silently. When unsure, cite the CASA documentation for the task in the PR.
+
+## Data and model
+
+- `gaincal` **solves against `DATA`**, with any `gaintable`s applied on the fly. It never reads `CORRECTED_DATA`. The input MS must therefore have calibrated data in `DATA` (`split` first), or every prior table must be pre-applied explicitly. Detect and warn when this doesn't hold.
+- The solve needs a model in `MODEL_DATA` (or a virtual model). Without one, `gaincal` silently uses a **1 Jy point source at the phase centre**. Every imager used for self-cal **must** write the model of the accepted image to the MS that the next `gaincal` reads, and the pipeline must check that it did.
+- The imager must image the **calibrated** visibilities (`CORRECTED_DATA` after `applycal`). This applies to Pyralysis too: request and fit `CORRECTED_DATA`, not `DATA`.
+
+## Calibration tables
+
+- Keep an **ordered stack** of accepted tables. Each new solve **pre-applies** the stack (`gaincal(gaintable=stack)`), and `applycal` applies the stack plus the new table. Don't replace the stack with the latest table.
+  - Exception: a fresh phase-only solve may deliberately solve from scratch and replace the previous phase table. Make that explicit in the code.
+- `spwmap` and `interp` belong to **each table**. When `combine` includes `'spw'`, map every selected spw to the **lowest selected spw id**; otherwise use `[]`. Never share one `spwmap` across tables.
+- Amplitude (`a`/`ap`) solves pre-apply the best phase solutions, normally at a shorter solint. Otherwise phase decorrelation within the solint biases the amplitudes low.
+- `solnorm=True` for amplitude solutions preserves the flux scale. Document any change to that.
+- `calwt=False` is the default for self-cal.
+
+## Selection
+
+- Solve, apply and image use the **same** field/spw/uvrange selection (one `Selection` object). A `uvrange` restriction for the solve must be explicit and recorded.
+
+## Acceptance and stopping
+
+- PSNR alone is not sufficient. Amplitude self-cal can raise PSNR by absorbing noise or unmodelled flux.
+- Compare rounds with the **same** noise estimator and region, with the source masked, for every imager.
+- Also track the fraction of flagged solutions (`calflag` flags data where a solution fails), the restoring beam, and the integrated flux.
+- Rollback restores the previous round's data, flags, model and table stack together.
+
+## Reproducibility
+
+- Each run records: the fully resolved config (presets and defaults expanded), Wenuray/CASA/backend versions, an input MS fingerprint, the accepted table stack, and per-round metrics.
+- No hidden randomness. If a backend is stochastic, a seed is part of the config.

wenuray-1.0.0/.cursor/rules/testing.mdc

@@ -0,0 +1,20 @@
+---
+description: pytest layout, CASA-free unit tests, simulated end-to-end self-cal tests
+globs:
+  - "tests/**"
+  - "src/**/*.py"
+alwaysApply: true
+---
+
+# Tests
+
+- Layout: `tests/unit/` mirrors `src/wenuray/`; `tests/integration/` holds tests that need CASA; `tests/examples/` runs the README and `examples/`.
+- **Unit tests must not need CASA.** Keep argument building, spwmap derivation, config validation and statistics pure, so they can be tested with synthetic inputs (FITS arrays, dataclasses).
+- Mark CASA-dependent tests `@pytest.mark.casa`, GPU tests `@pytest.mark.gpu`, and long tests `@pytest.mark.slow`.
+- **Scientific regression test:** `wenuray.testing.simulate_point_source_ms` simulates a small MS with seeded antenna phase errors, and `injected_phases` returns them. `tests/integration/test_selfcal_recovers_gains_casa.py` self-calibrates it with each imager and asserts that the recovered phases match the injected ones, up to the reference antenna's phase and a source shift (self-cal can't fix the absolute position), and that the PSNR improves. Any change to the self-cal loop must keep it passing (#32).
+- **Import Wenuray as users get it:** `from wenuray.x import Y`, never `src.wenuray.x`, also in `mock.patch` and `monkeypatch` targets. Two import paths give two copies of every class, and `isinstance` fails between them.
+- **Assert values, not just form.** A test of a written, recorded or converted value compares what reads back with the value computed the plain way; asserting only a type, a shape or that a call ran passes broken code. A fixture makes the tested quantity non-trivial: e.g. an imaging test whose cell is coarser than the Nyquist cell runs on data the grid can't hold, so it tests nothing (#60). Simulated data must be physically valid for the check.
+- **Compare with physics in mind:** gains up to the degeneracies self-calibration has (reference phase, position), noise-limited tolerances derived from the simulation (e.g. one solution's phase noise σ / (S √((N−1) n_pol))), not tolerances tuned until the test passes.
+- Mocks declare absent data explicitly. A bare `Mock` attribute pretends a column or a capability exists.
+- Every bug fix comes with a test that fails before the fix.
+- Test the README/example recipes at least by import or a dry run.

wenuray-1.0.0/.cursor/skills/bug-fix/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: bug-fix
+description: >-
+  Fix a Wenuray bug: reproduce it with a failing test, fix the root cause, keep the regression test,
+  run pre-commit and pytest, push and open a PR. Use for issues labelled bug or when asked to fix a
+  defect.
+---
+
+# Bug fix
+
+## Before coding
+
+1. Read the issue: steps to reproduce, expected vs actual behaviour, environment, logs.
+2. Read `AGENTS.md` and `.cursor/rules/`. Search for duplicates and for the tests that cover the
+   area.
+3. Decide whether the bug is Wenuray's or upstream's (CASA, Pyralysis). An upstream bug gets an
+   upstream issue with a minimal reproduction and, if needed, a workaround in Wenuray that names the
+   upstream issue.
+
+## Reproduce first
+
+1. Write the smallest test that fails because of the bug: a unit test with mocks if the logic is
+   pure, an integration test on simulated data if it needs CASA.
+2. Run it and see it fail for the reason in the issue, not another one.
+3. Check the test's data can show the bug: e.g. a cell must be Nyquist-sampled for an imaging
+   check to mean anything (`testing.mdc`, "Assert values, not just form").
+
+## Fix
+
+- Branch `fix/<issue>-<slug>` from `origin/development`; commits `FIX: <what> (#<issue>)`.
+- Fix the root cause, not the symptom. A silent fallback that changes the science becomes an
+  error or an explicit warning (`error-handling.mdc`).
+- Keep the regression test. Confirm it fails with only the fix reverted (`git checkout
+  origin/development -- <file>`, run, restore), not by stashing unrelated work.
+
+## Quality gates
+
+```bash
+pre-commit run --files <changed files>
+pytest <targeted tests>            # CASA tests in Docker if needed, see AGENTS.md
+```
+
+Run `convention-review` on the diff; run `verify-ab` if the fix changes results of an existing
+path.
+
+## Pull request
+
+Open a PR into `development` with `Closes #<issue>`, the reproduction, the root cause, the
+regression test and the commands run. If the issue has no `effort:N` label, suggest one.

wenuray-1.0.0/.cursor/skills/convention-review/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: convention-review
+description: >-
+  Deep review of a Wenuray diff (branch or PR) against the repository's rules: self-calibration
+  invariants, genericity across arrays, CASA I/O, design budget, tests and docs. Reports findings
+  ranked by severity, each with a concrete failure scenario. Use before opening or merging a PR, or
+  when asked to review code. For CI failures and review threads use pr-review.
+---
+
+# Convention review
+
+Review with fresh eyes: read the diff (`git diff origin/development...HEAD`) and the rules it
+touches, not the author's explanation. Every finding needs a concrete scenario (data, selection,
+configuration) that produces wrong calibration, a crash, a regression or a broken rule. No
+scenario, no finding. Cite the rule file.
+
+## Checklist
+
+**Self-calibration theory** (`selfcal-domain.mdc`)
+
+- gaincal solves against `DATA` with the accepted stack pre-applied; the imager images
+  `CORRECTED_DATA` and writes `MODEL_DATA` for the selected data.
+- One `Selection` for solve, apply and imaging; every table's `spwmap` and `interp` travel with it
+  through `CalStack`.
+- A rejected round restores data, flags, model and stack; acceptance is never PSNR alone.
+- Amplitude steps come after a phase solution; schedules are validated before any I/O.
+
+**Generic across arrays** (`general.mdc`, `design.mdc`)
+
+- No instrument names, instrument-tuned numbers or `if instrument == ...`. Defaults come from
+  theory (closure needs 3 or 4 antennas, Nyquist sampling) or from the data; instrument- or
+  science-dependent limits are opt-in with no default.
+- Variation goes through hooks, ClassVars, registries and `multimethod`, not `if` chains.
+
+**Design** (`design.mdc`, `implementation.mdc`)
+
+- At most about eight constructor parameters, all used; options grouped in frozen config objects.
+- Known types dispatched with `isinstance`/`multimethod`, not attribute probing.
+- Recipes: a new public class serialises (fields, or `to_recipe`/`from_recipe`) and round-trips.
+
+**CASA and data** (`casa-io.mdc`, `implementation.mdc`)
+
+- No I/O in constructors; no module-level CASA tools; tables closed on every path.
+- No fixed file names in the working directory; outputs under the run's directory.
+- Reads of a measurement set in samples when a statistic suffices: what happens on 10⁹ rows?
+
+**Errors** (`error-handling.mdc`)
+
+- Silent fallbacks that change the science are errors or explicit warnings; messages say how to
+  fix the problem.
+
+**Tests** (`testing.mdc`)
+
+- Behaviour changes have tests; regression tests fail on the old code.
+- Assertions about values, fixtures where the tested quantity is non-trivial and the simulated
+  data are physically valid (Nyquist-sampled cells, enough S/N).
+- Tolerances derived from the simulation's noise, and the degeneracies of self-cal respected.
+- Unit tests stay CASA-free; patch targets are `wenuray.…`, never `src.wenuray.…`.
+
+**Docs** (`documentation.mdc`)
+
+- Docstrings, README, `docs/`, examples and recipes match the new behaviour; examples still build
+  equal runs; comments say why.
+
+## Output
+
+Findings ranked most severe first: `file:line`, the defect in one sentence, the failure scenario,
+the suggested fix. Then a short list of what was checked and found fine. A finding that needs a
+run (results, speed) goes to `verify-ab` instead of a guess.

wenuray-1.0.0/.cursor/skills/docs-maintainer/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: docs-maintainer
+description: >-
+  Improve Wenuray's documentation: README, Sphinx pages (MyST Markdown, Read the Docs), examples and
+  docstrings, keeping docs and code in step. Docs-only PRs. Use for documentation issues or when
+  asked to audit or improve the docs.
+---
+
+# Docs maintainer
+
+## Scope
+
+| In | Paths |
+| --- | --- |
+| Front page and guides | `README.md` (it is the docs' front page), `docs/*.md`, `docs/migration.md` |
+| Examples | `examples/<name>/recipe.toml` and `selfcal.py`, `examples/README.md` |
+| API reference | Public docstrings (numpy style), rendered by sphinx-autoapi |
+| Agent and contributor docs | `AGENTS.md`, `CONTRIBUTING.md` (only when that is the task) |
+
+Out of scope: behaviour changes. If the docs can only be right after a code change, open an issue
+or use `feature-dev`.
+
+## Goals, in order
+
+1. **Correctness:** every snippet runs against the current API; names, defaults and file paths
+   match the code; instrument values in examples are marked as the example's, not Wenuray's.
+2. **Parity:** every public class and option is documented; recipes and scripts in `examples/`
+   build equal runs (a test checks it).
+3. **Structure:** pages in the right toctree, no duplication (the README is included, not copied).
+4. **Clarity:** short sentences, the theory where a choice depends on it (e.g. why a cell must be
+   Nyquist-sampled), links to CASA guides for CASA parameters.
+
+## Checks
+
+```bash
+pre-commit run --files <changed files>            # markdownlint, TOML formatting
+pip install -r docs/requirements.txt
+sphinx-build -W --keep-going -b html docs docs/_build/html   # no warnings allowed
+pytest tests/examples                              # README and examples run against the API
+```
+
+Docstrings render as reStructuredText: quote `|u|` and `**kwargs` as literals (` ``|u|`` `), and
+end a sentence with `::` before an indented code block.
+
+## Pull request
+
+Branch `chg/docs-<slug>` (or `chg/<issue>-<slug>`), PR into `development`: what was wrong, what
+changed, how to verify (the Sphinx build, the example tests). Escalate when a fix needs an API
+change, a structural decision, or domain review (self-calibration theory, CASA behaviour).

wenuray-1.0.0/.cursor/skills/estimate-effort/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: estimate-effort
+description: >-
+  Estimate the effort of a Wenuray GitHub issue and set its effort:N label (Fibonacci). Use when an
+  issue has no effort label, or when asked to size or prioritise issues.
+---
+
+# Effort estimation
+
+## Input
+
+The whole issue: description, acceptance criteria, open questions, labels, milestone, linked
+issues and PRs. Check the code it touches.
+
+## Output
+
+1. One `effort:N` label, N in 1, 2, 3, 5, 8, 13 (`gh issue edit N --add-label effort:3`; remove an
+   old one).
+2. One comment: the effort, 2–4 sentences of rationale (modules touched, test surface, CASA or
+   Pyralysis involvement, risk), and the tests it needs.
+
+## Rubric
+
+| Effort | Typical scope |
+| --- | --- |
+| 1 | Docs, a one-line fix, a trivial test |
+| 2 | A small change in one or two files, unit tests |
+| 3 | A feature across a few modules, unit tests, maybe one integration test |
+| 5 | Cross-module change, integration tests on simulated data, docs and recipes |
+| 8 | A new backend or calibration type, the loop, or upstream coordination (CASA, Pyralysis) |
+| 13 | Architecture: split it into issues of 8 or less instead |
+
+Raise the estimate when the change needs a design decision (`design` label), touches the
+self-calibration invariants, or depends on an unreleased upstream fix.