feat: give /hygiene sight of orphan config files (reachability-based)

[Jammy2211]

Overview

/hygiene config has a structural blind spot recorded during the grids.yaml removal (autolens_workspace#317). _hygiene_config.py iterates over library yamls and, at line 67, skips any without a workspace counterpart — and the loop only ever iterates library yamls. So a workspace config file with no library counterpart is structurally invisible to it. That is how a dead config/grids.yaml survived in 10 repos for ~1 year.

A previous prototype flagged orphans by filename (100+ hits, nearly all legitimate) and was correctly not shipped — it needed a suppression design. This task supplies it, and ships the dead config the new signal finds.

Plan

• Replace the wrong signal. Filename-orphanhood asks "does a library ship a file with this name?" The right question is reachability: does anything read the file?

• Under reachability the noise separates by owner, not by guesswork (measured 2026-07-23, 120 orphan instances / 30 distinct):

  Family	Instances	Read by	Verdict
  build/*	~39	PyAutoHands	legitimate
  priors/*	~40	JSONPriorConfig, by class path	legitimate
  non_linear/{nest,mle,mcmc}.yaml	~26	nothing	dead

• Suppression lives in an explicit owner map in the checker itself — small, reviewable in one file. Deliberately not a per-repo .hygieneignore (20 new files + a config surface that can itself go stale = the exact failure mode being fixed).

• Ship the cleanup the signal finds: delete the ~26 dead non_linear/{nest,mle,mcmc}.yaml across 9 repos.

Detailed implementation plan

Affected repositories

• PyAutoBrain (primary — the detector)
• autocti_assistant, autocti_workspace, autocti_workspace_test, autofit_workspace_developer, autofit_workspace_test, autogalaxy_workspace_test, autolens_assistant, autolens_workspace_test, euclid_strong_lens_modeling_pipeline (the non_linear cleanup)

The non_linear finding

config/non_linear/{nest,mle,mcmc}.yaml is dead config — the same class as grids.yaml, found by the very signal this builds. Verified 2026-07-23: no library reads conf.instance["non_linear"] for them (all six of autofit/autogalaxy/autolens/autoarray/autocti/autonerves checked). Search defaults come from the Python signature — PyAutoFit/autofit/non_linear/search/nest/nautilus/search.py:41 declares n_live: int = 3000 while the workspace nest.yaml says n_live: 200, and the file has no effect. The three user-facing workspaces already dropped them; the stragglers are the test/assistant/developer/euclid repos.

config/non_linear/GridSearch.yaml is live (conf.instance["non_linear"] resolves to {'gridsearch': ...}) — do not remove it.

Steps

1. _hygiene_config.py: add an orphan-file pass beside the existing key-mirror diff. Walk every config/**/*.yaml in each workspace-ish repo; a file is an orphan if no library ships a same-relative-path yaml; suppress orphans matching the owner map (build/* → PyAutoHands, priors/* → path-resolved prior config). Preserve the count|summary single-line prescan contract and the sys.exit(1) PyYAML-absent fallback.
2. tests/test_hygiene_conductor.py: cover a suppressed and an unsuppressed orphan — the owner map is the part most likely to rot.
3. Delete the ~26 dead non_linear/{nest,mle,mcmc}.yaml across the 9 repos.

Key files

• PyAutoBrain/agents/conductors/hygiene/_hygiene_config.py — the detector + owner map
• PyAutoBrain/tests/test_hygiene_conductor.py — suppression coverage
• <9 repos>/config/non_linear/{nest,mle,mcmc}.yaml — deleted

Acceptance test (non-negotiable)

The check must flag grids.yaml when run against the pre-deletion tree (a commit before autolens_workspace#317), flag non_linear/{nest,mle,mcmc}.yaml today, and stay silent on build/* and priors/*. A check that cannot re-find the bug that motivated it is not validated.

Guardrails

• _hygiene_config.py is stdlib + PyYAML only — never import the science stack.
• The orphan count is a surface signal ("files to review"), not a bug count.
• PyAutoCTI/test_autocti/config/ is what the CTI test conftest points conf.instance at — run the autocti suites after deleting, as the grids.yaml sweep did.
• gh pr create fails on this workspace's SSH remotes → gh api repos/O/R/pulls -X POST.

Related

• Follows the grids.yaml removal (autolens_workspace#317, 12 PRs), which recorded this gap as its open follow-up.
• Sibling PyAutoMind/draft/maintenance/workspaces/config_key_mirror_drift.md covers the opposite direction (keys missing FROM workspaces); neither catches an orphan FILE.
• Discovered again while purging the autoconf-era legacy surface (PyAutoNerves#137) — priors/subconfig.json and eden.yaml were orphan config files that survived for exactly this reason.

[Jammy2211]

Shipped — 2026-07-23

All 10 PRs merged.

Part 1 — detector: PyAutoBrain#156 (closes this issue).
Part 2 — cleanup (9): autocti_assistant#11, autocti_workspace#6, autocti_workspace_test#9, autofit_workspace_developer#24, autofit_workspace_test#71, autogalaxy_workspace_test#88, autolens_assistant#89, autolens_workspace_test#206, euclid_strong_lens_modeling_pipeline#35.

Verified on synced main

Running the merged detector against the workspace now reports 0 orphan config files — the non_linear/{nest,mle,mcmc}.yaml (26) and visualize/include.yaml (2) clusters are gone; only the 19 pre-existing key-mirror-drift items remain. The check that found the dead config confirms its removal.

Notes

• Two assistant PRs (autocti#11, autolens#89) merged with pre-existing red — wiki-currency (wiki drift) and boundary (4 unclassified docs/images/* files). Both fail on every recent PR to those repos, are unrelated to deleting config/non_linear/*.yaml, and did not block the earlier grids.yaml merge. Neither is a required check.
• Detector edge case recorded: autofit_workspace_developer's config/ shares no live file with the library set, so the mirror-heuristic does not scan it; its 2 dead files were swept manually. A config tree that is entirely dead orphans is invisible to a mirror-based check — noted as a known limitation, not worth complicating the detector for.