feat: switch workspace default branches from release to main with version-paired tags

[Jammy2211]

Overview

The three workspace repos (autofit_workspace, autogalaxy_workspace, autolens_workspace) currently have release set as their GitHub default branch. release is a downstream branch updated only by PyAutoBuild during a release cut, so PRs opened via gh pr create (without --base main) or the GitHub UI silently land on release and get overwritten by the next main → release sync. This already silently lost autolens_workspace PRs #54, #55, #58, #59, #61 and autogalaxy_workspace PR #28 between 2026-04-13 and 2026-04-14 (since recovered via cherry-pick PRs #62, #63, #29). This task fixes the root cause by flipping the defaults back to main and replacing the release-branch model with version-tagged workspace releases that pair to library versions.

Plan

• Flip GitHub default branch on the three workspace repos from release → main.
• Rip the release branch out of PyAutoBuild's release pipeline; tag workspaces with vYYYY.M.D.N matching the library version instead of merging main → release.
• Add a version.txt to each workspace, written by the release pipeline; add an autoconf helper that raises a clear error (with env-var override) when workspace and library versions disagree.
• Update PyAutoFit / PyAutoGalaxy / PyAutoLens installation docs so users clone the workspace at the tag matching their installed library version.
• Sweep admin_jammy/skills/ and PyAutoBuild/CLAUDE.md to remove now-stale release-branch references, including the --base main defence-in-depth in ship_workspace.md.
• Verify with gh repo view --json defaultBranchRef and a final grep -rn '\brelease\b' audit of PyAutoBuild and admin_jammy.

Detailed implementation plan

Affected Repositories

• autolens_workspace (primary — most affected by the bug)
• autogalaxy_workspace
• autofit_workspace
• PyAutoFit (docs)
• PyAutoGalaxy (docs)
• PyAutoLens (docs)
• PyAutoConf (new workspace.check_version helper)
• PyAutoBuild (release.yml, tag_and_merge.py, CLAUDE.md)
• admin_jammy (skills + claude.md sweep)

Work Classification

Both — library-side changes (PyAutoBuild, PyAutoConf, library docs) come first via /start_library; workspace version.txt commits and welcome.py wiring follow.

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoFit	main	clean
./PyAutoGalaxy	main	clean
./PyAutoLens	main	clean
./PyAutoConf	main	clean
./PyAutoBuild	main	clean
./autofit_workspace	main	clean
./autogalaxy_workspace	main	clean
./autolens_workspace	main	clean

Suggested branch: feature/default-branch-release-to-main
Worktree root: ~/Code/PyAutoLabs-wt/default-branch-release-to-main/ (created later by /start_library)

Implementation Steps

Phase 1 — GitHub admin (no code)

1. gh repo edit PyAutoLabs/{autofit,autogalaxy,autolens}_workspace --default-branch main — flip defaults.
2. Verify each with gh repo view PyAutoLabs/<repo> --json defaultBranchRef --jq '.defaultBranchRef.name'. Expect main.

Phase 2 — PyAutoBuild release-branch removal
3. PyAutoBuild/.github/workflows/release.yml — rewrite the release_workspaces job (lines 683-692) to skip the release checkout. Commit notebooks to main, write version.txt, tag the workspace at vYYYY.M.D.N matching the library tag, push tags. Same fix for run_notebooks_and_release_workspaces (lines 797-817).
4. PyAutoBuild/autobuild/tag_and_merge.py — delete the dead release checkout block (line 38); activate the workspace-tagging path so workspaces get a tag matching the library version.
5. PyAutoBuild/CLAUDE.md — drop the "Updating workspace release branches" bullet (line 11) and the update_notebook_visualisations description (line 124).

Phase 3 — Workspace versioning bootstrap
6. Add version.txt (placeholder = current latest tag 2026.4.13.6) to each workspace; release pipeline overwrites on every release.
7. PyAutoConf — add autoconf.workspace.check_version(library_version) that reads <cwd>/version.txt, raises WorkspaceVersionMismatchError. Env override: PYAUTO_SKIP_WORKSPACE_VERSION_CHECK=1.
8. Wire the check into each workspace's welcome.py (single bootstrap location, runs once when user first verifies install).

Phase 4 — Library docs
9. Update docs/installation/{pip,conda}.rst in PyAutoFit, PyAutoGalaxy, PyAutoLens — change bare workspace git clone … --depth 1 to a versioned git clone --branch v<library_version> … snippet.

Phase 5 — admin_jammy skills + CLAUDE.md sweep
10. Scan and update all 8 admin_jammy files with release references:
- admin_jammy/skills/ship_workspace/ship_workspace.md — remove --base main IMPORTANT block (lines ~68-71).
- admin_jammy/skills/ship_library/ship_library.md
- admin_jammy/skills/start_workspace/start_workspace.md
- admin_jammy/skills/review_release/review_release.md
- admin_jammy/skills/pre_build/pre_build.md
- admin_jammy/skills/dep_audit/SKILL.md
- admin_jammy/skills/verify_install/verify_install.md
- admin_jammy/claude.md, admin_jammy/software/build.md

Phase 6 — Verification
11. gh repo view PyAutoLabs/<repo> --json defaultBranchRef × 3 — confirm defaults stuck.
12. grep -rn '\brelease\b' PyAutoBuild/ admin_jammy/ — only legitimate hits should remain (release-notes, pypi release, GitHub Releases).
13. (Future, not in this PR) Decide whether to delete the release branches from origin entirely — destructive; keep as separate confirmation step.

Key Files

• PyAutoBuild/.github/workflows/release.yml — remove release checkout in workspace-release jobs
• PyAutoBuild/autobuild/tag_and_merge.py — activate workspace tagging
• PyAutoBuild/CLAUDE.md — drop release-branch documentation
• PyAutoConf/autoconf/workspace.py (new) — version-mismatch helper
• autofit_workspace/version.txt, autogalaxy_workspace/version.txt, autolens_workspace/version.txt — new
• autofit_workspace/welcome.py, autogalaxy_workspace/welcome.py, autolens_workspace/welcome.py — wire version check
• PyAutoFit/docs/installation/{pip,conda}.rst, PyAutoGalaxy/docs/installation/{pip,conda}.rst, PyAutoLens/docs/installation/{pip,conda}.rst
• admin_jammy/skills/**/*.md — sweep release refs

Original Prompt

Click to expand starting prompt

Three workspace repos currently have release set as their GitHub default branch. release is supposed to be a downstream branch updated only by PyAutoBuild when it merges main → release during a release cut. Having release as the default means gh pr create without --base main, and the GitHub UI "Compare & pull request" button, both silently target release. PRs that land on release are orphaned from main's history and get overwritten by the next main → release sync.

This already happened: autolens_workspace PRs #54, #55, #58, #59, #61 and autogalaxy_workspace PR #28 were merged to release over 2026-04-13 → 2026-04-14 without anyone noticing. All have since been replayed onto main via cherry-pick PRs (autolens_workspace #62, #63 and autogalaxy_workspace #29), but the underlying misconfiguration is still there and will keep causing drift until fixed.

Reason

Currnetly, release is what links to the pypi release, such that if a user runs pip install autolens, the
release branch should be in sync.

What we should do instead is have workspaces use main, but have it so the two following things happen:

1. Workspaces have tagged or version github branches, so that when a PyAuto version is released users can pair it to a specific workspace.
2. All PyAutoFit / PyAutoGalaxy / PyAutoLens docs tell the user (e.g. during installation) to use a version number for the workspace clone or download, paired to their version.
3. If a user has an out of sync workspace and source code, they get an error they have to manually disable.

This will mean a user can run the main branches of the source repos and workspace repos without issue.

Action

On each of the three repos, change the default branch from release back to main:

• https://github.com/PyAutoLabs/autolens_workspace/settings/branches — set default to main
• https://github.com/PyAutoLabs/autogalaxy_workspace/settings/branches — set default to main
• https://github.com/PyAutoLabs/autofit_workspace/settings/branches — set default to main

(autolens_workspace_test is already correct — default is main.)

Then add solution to points 1), 2) and 3) above.

Verification

After each change, confirm with:

gh repo view PyAutoLabs/<repo> --json defaultBranchRef --jq '.defaultBranchRef.name'

Expect main for all four workspace repos.

Why not purely rely on the /ship_workspace skill fix?

The skill has already been patched to pass --base main explicitly on every gh pr create call (admin_jammy commit 8152d05). That covers Claude-driven shipping. It does NOT cover:

• PRs opened manually in the GitHub UI (the "Compare & pull request" banner defaults to the repo's default branch).
• PRs from contributors who don't use the shipping skill.
• git push -u origin <branch>'s suggested PR URL (pre-fills the default base).

So changing the repo default is the root-cause fix; the skill patch is defence-in-depth.

So, also remove this fix once we are on main everywhere.

[Jammy2211]

Library PRs Created — 2026-04-18

PRs

• PyAutoConf: feat(workspace): add version-mismatch check helper PyAutoConf#94 — autoconf.workspace.check_version helper + tests
• PyAutoBuild: refactor(release): drop release branch, tag workspaces on main PyAutoBuild#48 — drop release-branch from release pipeline, tag workspaces on main
• PyAutoFit: docs(install): clone workspace at tag matching library version PyAutoFit#1225 — install docs use version-pinned workspace clone
• PyAutoGalaxy: docs(install): clone workspace at tag matching library version PyAutoGalaxy#354 — install docs use version-pinned workspace clone
• PyAutoLens: docs(install): clone workspace at tag matching library version PyAutoLens#440 — install docs use version-pinned workspace clone

Status

Library work shipped. GitHub default branch on the three workspace repos has already been flipped from release to main (verified). Workspace work pending: each of autofit_workspace, autogalaxy_workspace, autolens_workspace needs a version.txt file and a welcome.py call to autoconf.check_version(...). Routing to /start_workspace.

admin_jammy

Skill cleanup also pushed to Jammy2211/admin_jammy@main (commit 035fd48) — removed the --base main defence in ship_workspace.md, switched verify_install.md to clone the matching tag, dropped the obsolete "never push to release" warning in start_workspace.md.

[Jammy2211]

Shipped — 2026-04-18

PRs

• Add version.txt and check_version() in welcome.py autofit_workspace#33
• Add version.txt and check_version() in welcome.py autogalaxy_workspace#32
• Add version.txt and check_version() in welcome.py #72

Upstream PRs

• feat(workspace): add version-mismatch check helper PyAutoConf#94
• refactor(release): drop release branch, tag workspaces on main PyAutoBuild#48
• docs(install): clone workspace at tag matching library version PyAutoFit#1225
• docs(install): clone workspace at tag matching library version PyAutoGalaxy#354
• docs(install): clone workspace at tag matching library version PyAutoLens#440

Summary

Retired the release branch on the three workspace repos. The release pipeline now tags workspace releases on main and writes version.txt to pin each cloned workspace to the library version it was generated against. PyAutoConf gained a check_version helper and each workspace's welcome.py calls it at startup so library/workspace drift fails loudly. Installation docs were updated so git clone reads the installed library __version__ and pulls the matching workspace tag from main rather than tracking the (now-defunct) release branch.

Session Notes

• The release branches on autolens/autogalaxy/autofit_workspace were the GitHub default branches. Several workspace PRs (autolens_workspace docs: update add_a_profile guide for rotate_back #54–61, autogalaxy_workspace Update all scripts for new flat plot function API #28) were silently lost between 2026-04-13 and 2026-04-14 because gh pr create defaulted to release and the next main → release sync overwrote them. The default-branch flip to main (done as part of this task) prevents recurrence.
• All admin_jammy skills (/start_workspace, /ship_workspace, /verify_install) still carry --base main defence-in-depth so the explicit base flag survives even if a future repo gets a non-main default again.
• The release branches themselves are still present on origin (deferred — destructive). Safe to delete in a follow-up once we're confident nothing external depends on them.
• version.txt placeholder is 2026.4.13.6 for now; PyAutoBuild's release pipeline will overwrite it on the next release tag.
• pending-release label was missing on autofit_workspace and autogalaxy_workspace (only autolens had it). Created via gh api since the local gh CLI predates the gh label subcommand.