epic: birth autogalaxy_assistant (hand-built mirror of autolens_assistant)

[Jammy2211]

Birth autogalaxy_assistant — the galaxy structure modeling assistant cell for PyAutoGalaxy — hand-built by direct comparison against the mature reference autolens_assistant (autofit_assistant precedent: clone partition used as a checklist only, clone tool not run).

Mind prompt: PyAutoMind/draft/feature/autogalaxy_assistant/autogalaxy_assistant_birth.md
Reference partition (live-verified @ b9c10a9): 56 generic / 89 mixed / 301 domain / 0 unclassified — no reference-side unblock needed.

Locked decisions (human, 2026-08-01)

• PyAutoLabs/autogalaxy_assistant, PUBLIC at birth → every merged PR leaves the tree honest, zero lensing residue, green CI.
• Real galaxy cutouts sourced now (see data-sourcing checkpoint below); second HST/PyAutoReduce dataset deferred.
• Phased PRs under this epic; execution delegated to Opus subagents.

Phase checklist

• Phase 0 — this issue; Mind prompt filed; repo created public+empty; local checkout; PyAutoMind/repos.yaml entry + category-label fix + repos_sync.py --write; data-sourcing checkpoint opened.
• Phase 1 (PR Rename PyAutoAgent to PyAutoBrain #1) — frame + tooling + stack reference: 56-file generic tier with word-anchored substitutions; skills/_style.md re-authored FIRST (galaxy worked example); prose tier de-lensed (AGENTS.md 20 hits, skills/README 26, start-new-project 24, modes 13, wiki/README 4, llms.txt 11, _bootstrap_skill.md, scripts/AGENTS.md SLaM table rewritten — autocti went public carrying it, don't repeat); modes/maintainer.md template section re-partitioned for AG; sources.yaml (drop PyAutoLens/HowToLens/autolens_workspace; add autogalaxy_workspace + HowToGalaxy); config/ derived from autogalaxy_workspace/config (96 files — priors/ellipse/, different shapelets path), not the reference tree; autoassistant/ adapted — silent killers: BASELINE_MODULES/VERSIONED_MODULES tuple dupes ((autonerves,autoarray,autofit,autogalaxy,autogalaxy.plot)) and the leftover "al" alias key (drop; it would validate stale al.* prose); benchmark.py STACK_PACKAGES=(autogalaxy,autofit,autoarray,autonerves); literature.py → autogalaxy_literature.bib; mcp/lens_tools.py → galaxy_tools.py on ag.agg; workflows adapted (wiki-currency.yml pip install autogalaxy, clone list drops PyAutoLens, sparse-clone autogalaxy_workspace, rename drift artifact; clone-boundary.yml substitute BOTH checkout path: and checker arg → verified no-op); omit draft-pdf.yml + paper/; wiki/core/stack/ 5 pages + api_audit_baseline.json (wiki-currency runs --check-version per PR and exits 1 without it); ship LICENSE deliberately; honest PENDING.md.
• Phase 2 (PR Relocate the Health Agent into PyAutoBrain (canonical home) #2 + 4 external PRs) — real dataset + front door: dataset/imaging/<galaxy>/wavebands/ in cosmos_web_ring layout; galaxy info.json schema (single redshift, r_eff/sersic/PA hints; NO lens fields, NO positions.json); per-dataset provenance README; docs/make_readme_figures.py + hero PNG; README v2 with three anchored prompts; benchmarks/prompts/easy_*. External signposts merged AFTER: autogalaxy_workspace (llms.txt INTERIM science block + capability-boundary link + README "does not exist yet"), PyAutoGalaxy/llms.txt assistant bullet, HowToGalaxy/llms.txt capability boundary, org .github/profile/README.md.
• Phase 3 (PR Implement initial PyAutoBrain Build Agent #3) — wiki/core (~38 pages: api/ ~8 incl. new ellipse.md, keep mass_profile_catalog.md reframed for dynamical/stellar-mass work; concepts/ ~12-15; operations/ 5; external/ 5) + ag_audit_skill_apis / ag_update_wiki / ag_refresh_api_docs; baseline re-pin. Every snippet grounded on a named workspace script at pinned SHAs — never memory.
• Phase 4a (PR Implement initial PyAutoBrain Feature Agent #4) — 9 core-loop skills: ag_setup_environment, ag_prepare_imaging_data, ag_simulate_dataset, ag_build_imaging_model, ag_configure_search, ag_run_search, ag_plot_fit, ag_load_results, ag_debug_fit_failure.
• Phase 4b (PR Modernise and re-home PyAuto workflow skills for PyAutoBrain #5) — 8 feature skills: ag_basis_profiles (linear+MGE+shapelets), ag_pixelization, ag_light_model_extras, ag_ellipse_fitting (routes to ellipse/modeling.py — no start_here.py exists), ag_multi_dataset, ag_build_interferometer_model, ag_multi_galaxy_and_cluster (BCG + member light — watch lensing creep), ag_chain_searches. Trim → PENDING if long: ag_custom_profile, ag_custom_analysis (no AG grounding script — never author from the AL skill). Execute ≥1 script per skill's primary path.
• Phase 5 (PR Release Agent: release-validation rehearsal driver (M2 companion) #6) — wiki/literature (~40-50 files): Sersic/bulge-disk, isophotes/multipoles, MGE, ETG structure, scaling relations, high-z morphology; entities = surveys (COSMOS-Web, CANDELS, MaNGA/SAMI, Euclid). autogalaxy_literature.bib; every citation WebSearch-verified; make validate-literature-citations clean + ~20% ADS spot-check. + ag_ingest_paper. Privacy seam: PyAutoMemory structure/pointers only.
• Phase 6 (PR address Copilot review from #6 #7) — benchmarks (prompts easy/medium/hard/teacher; RESULTS.md only from actually-run cards), hpc/ galaxy-tuned + hand-executed (CI-ungated), ag_to_notebook + ag_inspect_results_mcp, retire PENDING.md → ROADMAP.md, full newborn gate (PyAutoHeart/docs/newborn_validation.md legs 1-4, leg 4 chat-surface smoke against the live URL).

Skill grounding tables (Phase 4)

Core loop: ag_setup_environment ← root start_here.py/welcome.py/config; ag_prepare_imaging_data ← imaging/data_preparation/*; ag_simulate_dataset ← imaging/simulator*.py, interferometer/simulator.py; ag_build_imaging_model ← imaging/{start_here,modeling}.py, guides/modeling/{cookbook,customize}.py; ag_configure_search ← guides/modeling/searches.py, config/non_linear/*; ag_run_search ← imaging/start_here.py, guides/using_jax.py, guides/hpc/*; ag_plot_fit ← imaging/plot.py, guides/plot/*; ag_load_results ← guides/results/* (aggregator, database, workflow); ag_debug_fit_failure ← guides/modeling/bug_fix.py, imaging/likelihood_function.py.

Features: ag_basis_profiles ← imaging/features/{linear_light_profiles,multi_gaussian_expansion,shapelets}/*; ag_pixelization ← imaging/features/pixelization/*; ag_light_model_extras ← imaging/features/{extra_galaxies,sky_background,operated_light_profile}/*; ag_ellipse_fitting ← ellipse/{modeling,fit,multipoles,plot,simulator,database}.py; ag_multi_dataset ← multi_dataset/start_here.py + features/*; ag_build_interferometer_model ← interferometer/*; ag_multi_galaxy_and_cluster ← multi_galaxy/* + cluster/*; ag_chain_searches ← guides/modeling/chaining.py.

Explicit deferrals

• paper/ + .github/workflows/draft-pdf.yml (JOSS paper post-completion; workflow is permanently red without paper.md).
• PyAutoBrain REFERENCE_PROFILES["autogalaxy_assistant"] — owner: whoever first clones FROM autogalaxy_assistant, paired via Brain-ref: (PyAutoBrain#186). Until then the inherited clone-boundary job is a verified no-op.
• Second (HST / PyAutoReduce) real dataset.
• Trimmed skills per Phase 4b.

Data-sourcing checkpoint (gates Phase 2 — HUMAN INPUT NEEDED)

No galaxy imaging FITS exists anywhere in the workspace (autogalaxy_workspace commits only sma.fits; all imaging is auto-simulated). Recommended: one multi-band JWST COSMOS-Web NIRCam cutout of a non-lens galaxy (same reduction chain as the reference's cosmos_web_ring — bright resolved early-type or clean bulge+disk, so it also serves ag_ellipse_fitting). Please name/approve the target galaxy + archive identifiers + reduction, or supply the cutout. Every info.json number will be measured by a committed script or cited — no invented provenance. Budget ≈ 13 MB (the reference's whole dataset/ footprint).

Version pin

PyAutoGalaxy latest release 2026.7.29.2 (wheel install in a clean venv for the baseline — --write-baseline refuses a dev-source stack without --allow-dev-stack).

[Jammy2211]

Phase 0 COMPLETE / Phase 1 PR OPEN (2026-08-01)

• Phase 0: repo born public+empty at PyAutoLabs/autogalaxy_assistant (bootstrap commit: LICENSE + honest interim README); Mind prompt issued (active/autogalaxy_assistant_birth.md); repos.yaml registered + label refreshed + repos_sync.py --write all-green.
• Phase 1: autogalaxy_assistant#1 OPEN — 157 files. Validation: pytest 66 passed / 2 skipped; full audit suite clean against a clean-venv wheel install of autogalaxy==2026.7.29.2; baseline pinned; residue grep clean.

Findings logged from the build (details on the PR):

1. autogalaxy_workspace/config lacks priors/mass/dark/gnfw_virial_mass_conc.yaml while ag.mp.gNFWVirialMassConcSph exists — upstream config gap, deserves its own issue.
2. autogalaxy/__init__.py module-level __getattr__ RecursionError on getattr(autogalaxy, "plot") pre-import — makes the bare autogalaxy.plot token audit-false-STALE; will bite Phase 3's wiki/core/api/plotting.md (avoid the bare token or fix upstream).
3. The audit cannot see unregistered aliases: with "al" removed from ALIAS_TO_MODULE, stale al.* prose is invisible to --scope all — residue detection is grep-only. Recorded in the tool's comments.
4. start-new-project.md shipped a real $AUTOLENS_ASSISTANT env-var leak in the reference — fixed here; reference-side fix belongs to the standing "systemic de-lensing of the generic tier" follow-up (autocti finding (a)).

⏳ Data-sourcing checkpoint remains OPEN (gates Phase 2) — need the target galaxy + archive identifiers/reduction for the real JWST/HST cutout (recommended: one multi-band COSMOS-Web NIRCam non-lens galaxy, bright resolved early-type or clean bulge+disk, ~13 MB budget).

[Jammy2211]

Data-sourcing checkpoint ANSWERED (2026-08-01): human approved the recommendation — one multi-band JWST COSMOS-Web NIRCam cutout of a non-lens galaxy. Production in flight through the sanctioned PyAutoReduce chain, reusing the 17.8 GB cached program-1727 level-2 exposures around the COSMOS-Web Ring (target will be selected inside that footprint; provenance measured, never invented). Phase 1 PR merged (ed72fab); Phase 3 wiki/core authoring is running in parallel.

[Jammy2211]

Phase 3 CI GREEN — autogalaxy_assistant#2 ready to merge (2026-08-01). 31 wiki/core pages (9 api / 15 concepts / 2 operations / 5 external) + 3 maintenance skills; wheel-venv validation clean; one CI-only failure found and fixed (a citation outside the sparse-clone cone — autogalaxy_workspace:dataset/ doesn't exist in CI's scripts-only clone, nor meaningfully upstream). In flight: Phase 4a (9 core-loop ag_* skills, stacked on #2) and the Phase 2 COSMOS-Web reduction.

[Jammy2211]

Phase 2 dataset PRODUCED (staged, pending repo integration): COSJ100020+015344 — COSMOS2020 499609, zCOSMOS 812167, z = 0.3422 spectroscopic (zCOSMOS-Bright DR3 conf 4.5, cited not measured), log M* = 10.54 early-type (smoke fit n ≈ 4.7). 4-band NIRCam cutouts (F115W/F150W @0.03", F277W/F444W @0.06") reduced from the cached program-1727 exposures, zero MAST traffic. Not a lens: COWLS cross-match null at 55.5" (recovers the ring at 0.1" as control). Smoke Sersic fit: reduced χ² 0.797, free sky recovers the measured pedestal to 1.4%. ~3.5 MB shipping products, provenance README with every number's origin.

Two upstream bugs found (deserve their own issues):

1. PyAutoReduce tier-1 ePSF is broken on crowded COSMOS fields: stars.find_stars selects ~76% compact galaxies as "stars" → kernel with 0.6% central-pixel flux (vs COWLS reference 14%), r½ 1.47" vs 0.085"; starred backend fails identically (defect is the star finder, not the builders). Also silently affects reduce_cosmos_web_ring.py's acceptance check (takes no PSF argument). Shipped dataset uses a tier-2b STPSF-composed kernel (autoreduce's own pieces), flagged as consistently sharper than the COWLS reference — the dominant known systematic.
2. JAX-enabled L-BFGS terminates at iteration zero returning its start point while logging "Search complete" (smoke fit needed PYAUTO_DISABLE_JAX=1). Reproduction material saved with the staging scripts.

[Jammy2211]

Phases 2, 3 and 4a ALL CI-GREEN (2026-08-01) — the stacked chain is ready for sequential merge:

1. autogalaxy_assistant#2 (Phase 3 — 31 wiki/core pages + 3 maintenance skills)
2. autogalaxy_assistant#3 (Phase 4a — the 9 core-loop ag_* skills, each validated by executing its generated script)
3. autogalaxy_assistant#4 (Phase 2 — the bundled COSJ100020+015344 4-band JWST dataset, README v2 front door, easy benchmark card, operations/dataset.md; pytest now 68/68)

GitHub retargets each PR as its base merges. Then the four external signposts: autogalaxy_workspace#200, PyAutoGalaxy#545, HowToGalaxy#54, PyAutoLabs/.github#7.

Process lessons now baked into the remaining phases' agent contracts: (a) symbol claims verified against the released wheel, never the ahead-of-release local stack (two main-only APIs were caught leaking); (b) workspace citations — inline AND frontmatter sources — confined to CI's scripts/-only sparse cone (three CI failures, one root cause).

In flight: Phase 4b (8 feature skills, authoring). Remaining after that: Phase 5 (literature wiki) and Phase 6 (benchmarks + hpc + full newborn gate).

[Jammy2211]

Phases 1, 2, 3 and 4a ALL MERGED (2026-08-01): assistant PRs #1/#2/#5 (reopen of #3)/#4 + the four external signposts (autogalaxy_workspace#200, PyAutoGalaxy#545, HowToGalaxy#54, .github#7). The public repo now ships: the frame + tooling, 36 wiki/core pages, 12 ag_* skills (9 core-loop + 3 maintenance), the bundled COSJ100020+015344 4-band JWST dataset with full provenance, the README front door with dataset-grounded starter prompts, and one benchmark card. All previously-404 public links now resolve to a working assistant. Stacked-PR lesson recorded: retarget a dependent PR to main before deleting its merged base branch — deleting first closes the PR unrecoverably (hence #5 as the reopen of #3). In flight: Phase 4b (8 feature skills). Remaining: Phase 5 literature wiki (+ the workspace llms.txt INTERIM science-block repoint), Phase 6 benchmarks/hpc/full newborn gate.