Repository navigation
docs: explain non-prior configuration leaf keys #1732
Description
Overview
explain non-prior configuration leaf keys. One of the five existing configuration tasks approved together in this session.
Plan
Add a small scripts/check_config_comments.py auditor in PyAutoFit using YAML nodes, quoted-comment handling, nonempty scan validation and priors exclusion. Add concise adjacent explanations to missing leaves under the four libraries' config directories; preserve loaded YAML exactly. Mirror comment-only changes for matching existing keys into autolens_workspace/config and autogalaxy_workspace/config without overwriting defaults. Validate baseline findings, zero final findings, parser regressions, parsed-value equality and library suites. Open library PRs first, then linked workspace PRs; retain human merge authority.
Tier: glance — merge mode: human review (/prm); no merge authorized.
Detailed implementation plan
Affected repositories: PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens, autolens_workspace, autogalaxy_workspace.
Branch: feature/config-leaf-comments; worktree root: /home/jammy/Code/PyAutoLabs/.worktrees/config-leaf-comments. For existing contributor PRs, retain their head branches instead.
All canonical checkouts are on main. Existing untracked dataset.fits in autolens_workspace and the schematic PNG in autolens_assistant are excluded. No other session holds registered repo claims; this session coordinates its own overlapping tasks sequentially on isolated branches. The unrelated PyAutoFit detached worktree is untouched.
Key files, changes and validation: Add a small scripts/check_config_comments.py auditor in PyAutoFit using YAML nodes, quoted-comment handling, nonempty scan validation and priors exclusion. Add concise adjacent explanations to missing leaves under the four libraries' config directories; preserve loaded YAML exactly. Mirror comment-only changes for matching existing keys into autolens_workspace/config and autogalaxy_workspace/config without overwriting defaults. Validate baseline findings, zero final findings, parser regressions, parsed-value equality and library suites. Open library PRs first, then linked workspace PRs; retain human merge authority.
Acceptance is the original prompt's witness, evaluated against current source; stale reported defects must be identified rather than recreated. Preserve original task scope and separate task/PR identity. No separate bundle backlog.
Original Prompt
Starting prompt
Config yaml keys missing their one-line explanatory comment
Type: maintenance
Target: autofit
Repos:
- PyAutoFit
- PyAutoArray
- PyAutoGalaxy
- PyAutoLens
- autolens_workspace
- autogalaxy_workspace
Difficulty: medium
Autonomy: safe
Priority: low
Status: formalised
Consequence: glance
Witness: the uncommented-leaf-key check reports 0 across every library config/ folder (excluding priors/) after the sweep, and reports a non-zero count when run against main before it.
Review-minutes: 3
Unattended: ready
User request (verbatim): "can you have an issue which checks if the docs have comments in them (lots do, but look for missing one line comments)" — clarified: "I mean the config yaml files themselves which often have comments next to thing".
The packaged config yaml (general.yaml, visualize/*.yaml, non_linear/**, output.yaml, ...) under each library's config/ folder, and the workspace config/ copies, document most keys with a one-line # comment on or above the key saying what it controls and what values it takes. Some keys have no comment. Walk every config yaml (excluding priors/, whose keys are class/param names), list every leaf key with no comment on its own line or the line above, and add the missing one-line comments (short, in the same register as the neighbours). Add a small check (a test in PyAutoFit, or a script the sweep re-runs) that reports uncommented leaf keys so the gap does not reopen. Workspaces follow the packaged files: propagate the comments to autolens_workspace and autogalaxy_workspace config/ copies in the same pass. Follow-on from the config-priors-drift sweep (PyAutoGalaxy#618).
Witness: the uncommented-leaf-key check reports 0 across every library config/ folder (excluding priors/) after the sweep, and reports a non-zero count when run against main before it.
Phasing if split at start_dev: (1) PyAutoFit + PyAutoArray packaged config + the check; (2) PyAutoGalaxy + PyAutoLens; (3) the two workspace copies.
Activity
Jammy2211 commentedon Oct 26, 2026
Library implementation: added 277 missing leaf comments across Fit/Array/Galaxy/Lens; all 125 parsed YAML values are unchanged. Added a standalone non-prior YAML comment checker and four focused tests (all pass). Parallel full Fit tests exposed shared-output/SQLite races, reproduced on pristine HEAD; serial rerun of failed nodes passed 27/28, with the Zeus logging assertion also reproduced on pristine HEAD. Full serial Fit and remaining library suites are in progress.
Human decision in this session: “Yes—open draft PRs with the baseline failure documented.” This authorizes draft PRs despite that reproduced baseline failure; merge stays blocked. It does not waive unrelated failures. Workspace comment mirrors follow the library PRs; task remains active.
Jammy2211 commentedon Oct 26, 2026
Library PR Created: #1733 (draft; pending-release label verified). Full serial Fit suite passes: 3,932 passed, 2 skipped, 1 xfailed. The isolated Zeus failure is order-sensitive and also occurs on pristine HEAD; it does not reproduce in the complete serial suite. API changes: none. Remaining Array/Galaxy/Lens PRs follow their ongoing unit checks. Next: /start_workspace to mirror comments into existing Galaxy/Lens workspace keys, preserving values.
Jammy2211 commentedon Oct 26, 2026
All four library drafts are open:
Final library suites: Fit 3932 passed (serial), Array 2191 passed, Galaxy 1373 passed, Lens 952 passed. All pending-release labels verified. No merge performed.
Workspace mirrors implemented: 323 explanatory comments across Galaxy/Lens workspace config copies. All 168 workspace YAML values unchanged; audit reports zero missing leaf comments. Heart smoke against the actual workspace branches is now running. Workspace PRs will retain library-first merge gates.
Jammy2211 commentedon Oct 26, 2026
Final library downstream smoke
Total: 172 passed, 0 failed. Initial infrastructure failures were resolved without source changes: Lens regressions needed a real isolated Git worktree; CTI needed locally extracted GSL headers/libraries using the documented installer setup. All corrected runs exited 0. Local structured evidence:
.worktrees/config-validation/logs/smoke-summary.json; raw initial and retry logs are retained.All four library unit suites also pass (8,448 tests total). Draft status and human merge gate remain. Workspace mirrors have their separate branch-specific smoke runs.
Jammy2211 commentedon Oct 26, 2026
Implementation ready for draft review
Both workspace drafts are now open:
Together with the four library drafts linked above, this completes the approved comment sweep: 600 comments (277 library + 323 workspace), zero missing leaf comments, and unchanged parsed values in 293 YAML files. Independent workspace review was CLEAN. The full library suites pass 8,448 tests; downstream library smoke passes 172 checks.
Review/merge order: library drafts first, then these workspace drafts. The Galaxy/Lens corner-plot contributor branches include the corresponding comment branches, with notation conflicts resolved and all corner values preserved; merge these comment PRs before those corner PRs. Draft status remains as explicitly requested. No merge or issue close performed.
Jammy2211 commentedon Oct 26, 2026
Shipped
Merged all six PRs in library-first order: PyAutoFit #1733, PyAutoArray #656, PyAutoGalaxy #667, PyAutoLens #802, autogalaxy_workspace #264 and autolens_workspace #602. Added 600 comments and the missing-comment checker while preserving all 293 YAML mappings. Library suites passed 8,448 tests; downstream smoke passed 172 checks; workspace branches passed 60 checks. Every workflow run and job was green at merge. Library releases remain pending and their obligations are retained in Mind. Human /prm confirmed merged unchanged and authorized completed-worktree cleanup.