Record the pipeline's scientific decisions in astra.yaml, linked to the code by @sc tags

[cailmdaley]

astra.yaml at the repo root records ShapePipe's scientific decisions: the choices in the code and in the committed workflow/config/cfis/ configs that change which objects enter the shear catalogue, or the numbers attached to them. Each decision carries its rationale, the alternatives, and the option develop selects (pinned in universes/committed.yaml). CI checks that the record and the code agree, so a scientific change cannot land without its record change. Format: ASTRA (uvx astra-tools@0.2.17 guide).

How the record connects to the code

A decision is linked to the code and config that implement it by an @sc tag at the site, where an editor sees it:

# @sc [decision:detection.detection_threshold_policy]
DETECT_THRESH    1.0
ANALYSIS_THRESH  1.0

def position_seed(ra, dec, ccd):
    """...
    @sc [decision:shape_measurement.ngmix_seed_mode]
    """

A # tag governs the settings below it up to the next blank line, or the whole section when it sits directly above a [SECTION] header; a docstring tag governs its function or class. The record keeps the why, and pins committed values by key:

rationale: >-
  Tiles use the MegaPipe tile-catalogue threshold, minimum area and filter, ...
  Values:
  default_tile.sex#DETECT_THRESH = 1.0;
  default_exp.sex#DETECT_THRESH = 1.5; ...

tests/unit/test_decisions.py runs in CI inside the image and fails when:

• a tag cites a decision the record lacks, or a decision has no tagged site;
• a Values: entry does not resolve to exactly one of its decision's tagged sites, or the value there differs. A governed key set twice in its file, a tagged site deleted, or a gate key turned off (WEIGHT_IMAGE = False) all fail;
• a key the record asserts = absent (e.g. SATUR_LEVEL, MASK_EXT == 0 in star selection) appears.

tests/unit/test_committed_configs_run.py runs SExtractor and PSFEx with the committed configs on a small synthetic image, so a tag that breaks a reader (SExtractor wants CONV on the first line of a .conv file) fails CI.

python -m tests.helpers.decisions <path>[:<line>] lists the decisions and local contracts governing a line; --decision <id> lists a decision's sites.

The configs gain only comment and blank lines, and the code only docstring lines; no active key, value or statement changes.

What is in the record

• 46 decisions in six sub-analyses (masking, detection, preparation, star selection + PSF, shape measurement, catalogue assembly) plus three cross-cutting (stamp size, zero-point, per-unit completeness), with 163 tags at the sites and 151 pinned values. Workflow policy (manifests, chunking, allocation) is out; it lives in Snakemake orchestration for shapepipe #848.
• 19 local contracts (@sc with an id and prose): constraints at one site that no decision states, such as "the CCD candidate prefilter must be a superset of the strict bounds test". src/shapepipe/utilities/CONTRACTS holds the one import boundary (utilities never import modules).
• Markers: [HARDCODED] (15), a scientific value fixed in code with no config key; [LINT] (3), the code disagreeing with itself or its docs.
• The masked-pixel decisions (defect_fill, blend_handling, epoch_masked_fraction_cut, central_defect_veto) carry the DES/Rubin literature with verified quotes and the bias measurements from ngmix: noise-fill defects under both BLEND_HANDLING options, drop epochs with a defect near the object #915/ngmix: opt-in DEFECT_FILL = interpolate for narrow defects, with a 7 px veto #916; defaults are what develop does today.
• Science tests in tests/science/ carry @pytest.mark.decision(...) naming the decision they protect (all currently shape_measurement.metacal_scheme).

Writing the record surfaced defects that are now fixed (#907, #909, #918 merged; #911 open) or filed (#912, #913, #914, #919).

Changing a scientific choice

Change the code or config, then amend its decision in the same PR (rationale, Values:, and universes/committed.yaml if the option changes). CI names the decision, the key, and the expected and actual values. The rule is in CLAUDE.md.

Reviewing

Every default was checked against the code, the rationales had independent line-by-line reads, and the checker was mutation-tested on the real configs (each mutation above fails for the stated reason; reordering keys inside a paragraph passes). A downloaded tile and exposure settled the one question the repo could not: both carry a SATURATE card (tile 9558.7, exposure CCDs 65535).

Still open: fit_priors's [LINT]. The ngmix template pins PIXEL_SCALE = 0.186 while star selection uses 0.187, and the WCS fallback that would replace the key is broken: pixel_scale_from_wcs meets the merged-headers file's leading TILE_ID string and raises AttributeError. The override hides the crash; the value only sets the centroid-prior width.

🤖 Generated with Claude Code