Writing TASK.md

The task you give @cosmotron (or pass as bootstrap_session's user_task argument) is free text, plus optional structured ## section: blocks that cosmotron_mcp/pipeline_resolve.py parses deterministically. TASK.md is a convention for writing that text down as a reusable file — the task-spec sibling of DATA_DESCRIPTION.md (which describes the data; TASK.md describes the request).

Sections are parsed independently and additively — order doesn't matter, but a header must match exactly (## correlations:, not ## correlation:). Free text above the first ## heading is read as plain prose; measurement params like nside=512 lmax=1535 can appear there directly. nside is never read from a section block — see Parameter resolution.

Template

Copy TASK.md.template as a starting point.

Section reference

Section	Controls	Extractor
## probes:	Per-probe overrides: probe_name: key=value, key=value (e.g. sigma_e=, lmax=, bias=)	extract_probes
## correlations:	Which pairs to compute: all (default) | auto | adjacent: N | pairs: [[0,1],[lens0,src1]] (index or tracer-name pairs). Applied early to spectra, covariance, and SACC — only selected pairs are ever built. A referenced bin's auto is always included.	extract_correlations
## plots:	Comma- or line-separated list of required plot types, persisted as session_context.json["required_plots"]	extract_required_plots
## calibration:	Shear multiplicative bias: m=, sigma_m= (also settable per-probe in ## probes:, or from a catalogue profile's calibration: block)	extract_calibration
ell_binning=log / ## ell binning:	"linear" | "log", global per session — see Parameter resolution	extract_ell_binning
ell edges: [...] / ## ell edges:	Explicit bandpower edges, overriding n_bandpowers	extract_ell_edges
## inference priors:	Omega_c: [min, default, max] (flat) or sigma8: gaussian(mean, sigma); or e.g. "use the same priors as DESI DR2" (routed through a literature, human-confirmed gate). A parameter is sampled iff it has a prior — everything else stays fixed. Nuisance parameters go here too, not just cosmology — see the spellings below.	run_inference's prior parsing / draft_inference_spec
## inference sampler:	A CosmoSIS family token + optional knobs, e.g. nautilus, n_live=400 or emcee with 32 walkers (families: nautilus/emcee/zeus/dynesty/multinest/polychord/metropolis/grid/maxlike/apriori/test). Default test (single evaluation). The tool owns the actual [sampler] INI syntax — see the cosmosis-sampler skill.	build_cosmosis_inference
## inference scale cuts:	lens0: [20, 150] per-tracer ℓ-ranges, or a cross pair lens0,src1: [20, 100] → firecrown data_source.filters. Inference-only — never the NaMaster measurement lmax.	run_inference's scale-cut parsing
## inference gate: skip	Turns OFF the human spec-approval gate for this run — @inference compiles and launches without pausing at SPEC_READY:. Default is ON (gate active). Only this explicit heading (or a gate: skip line, or the session-wide skip_gates) skips it; prose like "just run it" never does. Skipping the gate never skips validation or the dry-run.	resolve_gate_mode
## remote: / ## site:	Which heavy step classes run on an HPC cluster: site: <name> + an optional queue: <name> + a list of ingest / spectra / covariance / inference (or all). ## site: <name> alone = all classes on that site. See Running steps on a cluster below.	extract_remote

The model picks a choice (a sampler family, a prior shape, a probe name); the tool always owns the syntax (the actual INI/YAML text). Never author [sampler] blocks or Firecrown YAML by hand — that's exactly the "tool owns the syntax" pattern behind the tool-priority invariant.

Example — single-probe clustering

Compute the angular power spectrum for the galaxy catalogue in
/data/my_survey/ at nside=512.

## plots:
cls_comparison, catalogue_diagnostics

No ## probes: needed — a single, undeclared catalogue defaults to galaxy_density (spin-0). See quickstart/opencode.md for the equivalent one-line prompt form.

Example — tomographic shear

Cosmic shear analysis on /data/kids1000_gold/ at nside=1024, tomographic
(4 bins). Use log-spaced bandpowers.

## probes:
galaxy_shear: sigma_e=0.28, lmax=2000

## calibration:
m=0.012, sigma_m=0.02

## ell binning:
log

## plots:
cls_grid, covariance

sigma_e/lmax are per-probe overrides; nside stays global. m is divided out of the ellipticities at ingest time, and sigma_m feeds the covariance's calibration-uncertainty marginalisation term.

Example — full 3×2pt with inference

Run a 3×2pt analysis on /data/my_survey/ at nside=1024.

## probes:
galaxy_density: bias=1.8
galaxy_shear: sigma_e=0.28, lmax=2000

## correlations:
adjacent: 1

## inference priors:
Omega_c: [0.1, 0.26, 0.5]
sigma8: gaussian(0.81, 0.03)

## inference sampler:
nautilus, n_live=400

## inference scale cuts:
lens0: [20, 150]
lens0,src1: [20, 100]

## correlations: adjacent: 1 selects autos plus adjacent-bin crosses only — the compute-cost win for a large tomographic 3×2pt run. Omega_c and sigma8 get sampled (they have priors); every other cosmological parameter stays fixed at its default. These sections seed a typed InferenceSpec, which @inference fills in, and which — by default — it presents for your approval before compiling and launching the chain. Add ## inference gate: skip if you want an unattended run to proceed straight through (validation and the dry-run still run). See inference for the full loop.

Nuisance priors in ## inference priors:

The section is not cosmology-only — nuisance parameters are routed to their spec slot by name. Recognised spellings (case-insensitive):

Parameter	Write it as
Cosmology	Omega_c, Omega_b, sigma8, h, n_s (amplitude is sigma8, never A_s)
Intrinsic alignment	a_ia / ia_bias, eta_ia / alphaz, z_piv; TATT: a1, a2, bta (or the firecrown ia_a_1 … names)
Multiplicative shear bias	m_0, m_1, … (or src0_mult_bias, or bare src0)
Linear galaxy bias	b_0, b_1, … (or lens0_bias, or bare lens0)
Photo-z shift	src0_delta_z / lens0_delta_z (or dz_0, which resolves to shear when the session has shear)

Declaring an IA parameter also selects the IA model — eta_ia implies nla_z, a1/a2/bta imply tatt, otherwise nla. Per-bin parameters must cover every bin of that probe; declaring src0_delta_z but not src1_delta_z in a two-bin run is a validation error, not a half-configured run. A name that matches nothing above is reported back as unrouted_priors with a warning — it is never silently ignored.

Running steps on a cluster

Two task-level knobs push heavy steps to an HPC cluster (full setup in Remote execution). You never write a jobspec or name a tool — you say what runs where and the tools attach the rest.

## remote: — pick which step classes run remotely. Body is an optional site: <name> (a sites.yaml entry), an optional queue: <name> (a sites.yaml queue-map key, overriding the resource class's own default queue for every step in this block), plus a list drawn from ingest, spectra, covariance, inference, or all:

Tomographic 3×2pt on /data/des_y3/ at nside=1024.

## remote:
site: sunrise
queue: bigmem
covariance, inference

Here maps/spectra run locally (fast enough on the Spark) while the covariance and the CosmoSIS chain run as Slurm jobs on sunrise, submitted to the bigmem queue — the agents dispatch them and poll to completion automatically, and results land back in the session. ## site: sunrise on its own is shorthand for "all heavy classes on sunrise" (no queue: line possible in that shorthand form). An inline form works too: ## remote: all on sunrise. Drop queue: entirely to use each step's resource-class default queue, as before.

Data on the cluster — site:path. If the catalogue already lives on a cluster filesystem, point the run at it with a site: prefix instead of a bare path:

@cosmotron analyse sunrise:/cfs/nobackup/mygroup/des_y3/ at nside=1024

The session is pinned to that site and ingest is forced remote (a multi-GB FITS on the cluster can't be read locally) — no ## remote: block needed for that. Add one only to also push later steps (covariance/inference) remote. A session lives on exactly one site; naming a second is a hard error. See Data placement for where products end up.