refactor: rename autobuild package and CLI to autohands

[Jammy2211]

Overview

The Hands repo was renamed PyAutoBuild → PyAutoHands, but its payload package and CLI kept the old autobuild name. This task closes that seam: autobuild/ → autohands/ and bin/autobuild → bin/autohands, plus every live reference across the organism (~283 lines / ~110 files in 17 repos).

Landing is atomic, no back-compat shim (human decision): the directory move breaks PyAutoHeart's workspace-validation.yml and every workspace's run_smoke.py the moment it merges, so all PRs must merge in one pass — Hands → Heart → Brain → workspaces — while CI is quiet.

Plan

• Move the package and CLI in PyAutoHands via git mv so history follows the files.
• Update PyAutoHands' own consumers: dotted test imports, pre_build.sh, docs, workflows.
• Update PyAutoHeart's workspace-validation.yml (five hard-coded PyAutoHands/autobuild/*.py invocations) and its check comments.
• Update PyAutoBrain's binary resolver, policy config, repo maps and organ docs.
• Update the 13 workspace / HowTo / assistant repos — AGENTS.md generate commands, run_smoke.py sys.path.insert, config and workflow comments.
• Update the two live PyAutoMind files (scripts/repos_sync.py, ROUTING.md) while leaving ~150 historical records alone.
• Verify by grep: zero lowercase autobuild outside the explicit preserve-list.

Detailed implementation plan

Affected Repositories

• PyAutoHands (primary) — 173 lines / 35 files
• PyAutoHeart — 27 / 14
• PyAutoBrain — 37 / 21
• autolens_workspace (5/5), autogalaxy_workspace (6/6), autofit_workspace (5/5)
• autolens_workspace_test (5/3), autogalaxy_workspace_test (5/3), autofit_workspace_test (4/2), autocti_workspace_test (3/1)
• HowToLens (3/3), HowToGalaxy (3/3), HowToFit (3/3)
• autolens_assistant (3/2), autofit_assistant (3/2), autocti_assistant (2/1)
• PyAutoMind — 2 live files only
• admin_jammy — 1 line (drive-by)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoHands	main	clean
./PyAutoHeart	main	clean
./PyAutoBrain	main	clean
./autolens_workspace	main	clean
./autogalaxy_workspace	main	clean
./autofit_workspace	main	clean
./autolens_workspace_test	main	clean
./autogalaxy_workspace_test	main	clean
./autofit_workspace_test	main	clean
./autocti_workspace_test	main	clean
./HowToLens	main	clean
./HowToGalaxy	main	clean
./HowToFit	main	clean
./autolens_assistant	main	clean
./autofit_assistant	main	clean
./autocti_assistant	main	clean
./admin_jammy	main	3 modified (unrelated)

No worktree conflicts: the four active tasks claim PyAutoCTI, PyAutoFit, autolens_profiling, autolens_jax_joss and autolens_workspace_developer — none of them targets here.

Suggested branch: feature/rename-autobuild-to-autohands
Worktree root: ~/Code/PyAutoLabs-wt/rename-autobuild-to-autohands/
Work Classification: Library (Hands is the primary), with a broad workspace follow-on in the same branch.

Implementation Steps

1. PyAutoHands — git mv autobuild autohands; git mv bin/autobuild bin/autohands. In the CLI: AUTOBUILD_DIR→AUTOHANDS_DIR, header comment, autobuild help usage strings, the ~/.bashrc alias suggestion. Then tests/ dotted imports (from autobuild.build_util import … → autohands.build_util), pre_build.sh, docs/{internals,nightly_release_design,env_profile_redesign,pre_build_failure_audit}.md, README.md, AGENTS.md, CONTRIBUTING.md, MIGRATION.md, .github/workflows/{release,navigator_check}.yml, autohands/config/workspaces.yaml.
2. PyAutoHeart — .github/workflows/workspace-validation.yml lines ~135/179/295/322/411/445 (script_matrix.py, generate.py, run_python.py ×2, run.py, aggregate_results.py); scripts/health_release.sh:42; comments in heart/checks/{script_timing,test_run,url_check_live}.py.
3. PyAutoBrain — agents/_common.sh (resolve_autobuild→resolve_autohands, both the function and the _resolve_bin fallback path); config/policy.yaml extra_organism_targets + the intake keyword list; agents/conductors/build/{build.sh,BUILD_CAPABILITIES.md,AGENTS.md}; agents/conductors/{release,intake,bug,clone}; agents/faculties/vitals/HEART_CAPABILITIES.md; docs/organs/build.md; docs/adoption/config_surfaces.md; ORGANISM.md; skills/ship_library/reference.md; tests/test_policy_seams.py.
4. Workspaces / HowTos / assistants — AGENTS.md PYTHONPATH=../PyAutoHands/autobuild python3 ../PyAutoHands/autobuild/generate.py <project>; .github/scripts/run_smoke.py (sys.path.insert(… "PyAutoHands" / "autobuild") and the docstring); .claude/skills/{generate_and_merge,run_all_script_fix_failures}/SKILL.md; config/build/visualise_notebooks.yaml header comment; .github/workflows/navigator_check.yml comment; .navigator_check_ignore comment; autoassistant/to_notebook.py docstrings.
5. PyAutoMind (live only) — scripts/repos_sync.py:558-570 dict keys; ROUTING.md:38.
6. admin_jammy — README.md:25 PyAutoBuild/skills/ → PyAutoHands/skills/.
7. Verify — pytest in PyAutoHands, PyAutoBrain/tests/test_policy_seams.py, bash -n bin/autohands + autohands help, python3 PyAutoMind/scripts/repos_sync.py --check, and a final grep asserting zero lowercase autobuild outside the preserve-list.

Explicitly preserved (do not rewrite)

48 historical references: PyAutoBuild#118/#120/#121/#126/#127/#155/#156 issue citations; rhayes777/PyAutoBuild patterns in PyAutoHeart/config/url_fixups.yaml and heart/checks/url_check.sh; the pyautobuild: pyautohands back-compat alias in PyAutoBrain/config/policy.yaml; ~150 PyAutoMind historical records; PyAutoMind/planned.md:121 and dashboard.md:92 (registry pointers to real prompt-file paths); and the two gitignored .claude/settings.local.json allowlists.

Key Files

• PyAutoHands/bin/autobuild — the dispatcher; AUTOBUILD_DIR and all help text.
• PyAutoHands/autobuild/ — 27 modules + config/workspaces.yaml; has __init__.py, so it is a real package.
• PyAutoHeart/.github/workflows/workspace-validation.yml — five path-invocations; the highest-blast-radius file.
• PyAutoBrain/agents/_common.sh — resolve_autobuild, the PATH/sibling fallback.
• PyAutoMind/scripts/repos_sync.py — hard-coded PyAutoHands/autobuild/*.py dict keys; breaks silently if missed.

Notes on risk

• Two import styles must both keep working: dotted (from autobuild.build_util import …, Hands' own tests) and flat-on-PYTHONPATH (from build_util import …, workspaces — only the sys.path string changes).
• No setup.py/pyproject.toml, so no PyPI package name is at stake.
• autobuild is not on PATH and has no shell alias, so no user shell config is affected.
• Accepted risk: workspace CI is broken between the Hands merge and the last workspace merge. That window is the cost of no shim.

Run conditions

• Phasing override. The Brain Feature Agent scored this too-large (37) and recommended split-into-phases. Not taken, with human approval: the score is driven by repo count (16), not conceptual complexity; there is no design phase in a mechanical rename; and sequential phases would violate the atomic-landing guardrail. Still ~18 PRs sharing one branch.
• Heart was RED (score 0) at launch — 13 test failures, 33 stale parked scripts, release validation integrate:fail. None caused by this task, and the corrective-PR exception does not apply (this rename repairs no RED reason). Per AUTONOMY.md, RED forbids commit/push/PR-open at every autonomy level, so this run is expected to park at the ship gate. Effective autonomy = min(supervised header, safe refactor cap) = supervised.

Original Prompt

Click to expand starting prompt

# Rename `PyAutoHands/autobuild` to `PyAutoHands/autohands`

Type: refactor
Target: PyAutoHands
Repos:
- PyAutoHands
- PyAutoBrain
- PyAutoHeart
- autolens_workspace
- autogalaxy_workspace
- autofit_workspace
- autolens_workspace_test
- autogalaxy_workspace_test
- autofit_workspace_test
- autocti_workspace_test
- HowToLens
- HowToGalaxy
- HowToFit
- autolens_assistant
- autofit_assistant
- autocti_assistant
- admin_jammy
- PyAutoMind
Difficulty: medium
Autonomy: supervised
Priority: normal
Status: formalised

## Original request (verbatim)

> rename - PyAutoHands/autobuild to - PyAutoHands/autohands and make sure this
> new word is used throughout

## Why

The Hands repo was renamed `PyAutoBuild` → `PyAutoHands`, but its payload
package and CLI kept the old `autobuild` name. The organ and its package now
disagree, which is the one naming seam the rename left behind.

## Scope

Rename the package directory, the CLI, and every **live** reference to the new
word across the organism.

- **PyAutoHands** (primary): `autobuild/` → `autohands/` (27 modules +
  `config/workspaces.yaml`), `bin/autobuild` → `bin/autohands` (and its internal
  `AUTOBUILD_DIR` / help text / alias suggestion), `pre_build.sh`, `tests/`
  (including the dotted imports `from autobuild.build_util import …`), `docs/`,
  `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, `.github/workflows/`.
- **PyAutoHeart**: `.github/workflows/workspace-validation.yml` invokes
  `PyAutoHands/autobuild/*.py` by path in five places; also
  `heart/checks/*.py` comments and `scripts/health_release.sh`.
- **PyAutoBrain**: `config/policy.yaml` (`extra_organism_targets`, alias map),
  `agents/_common.sh` (`resolve_autobuild`), the intake/bug repo maps, the
  build-conductor docs and `build.sh` dispatch.
- **Workspaces / HowTos / assistants**: `AGENTS.md` generate commands
  (`PYTHONPATH=../PyAutoHands/autobuild …`), `.github/scripts/run_smoke.py`
  (`sys.path.insert(… "autobuild")`), `.github/workflows/navigator_check.yml`
  comments, `config/build/visualise_notebooks.yaml` header comments,
  `.claude/skills/*/SKILL.md`.

## Guardrails

- **No back-compat shim.** Land atomically, library-first: the directory move
  breaks PyAutoHeart's `workspace-validation.yml` and every workspace's
  `run_smoke.py` the moment it merges, so all PRs must be merged in one pass
  before the next nightly.
- **Preserve historical old-name references.** Do *not* rewrite `PyAutoBuild#NNN`
  issue citations, `rhayes777/PyAutoBuild` URL-fixup patterns in
  `PyAutoHeart/config/url_fixups.yaml` / `url_check.sh`, or the back-compat
  alias `pyautobuild: pyautohands` in `PyAutoBrain/config/policy.yaml`. These
  point at real historical artifacts; rewriting them makes them wrong.
- **Leave PyAutoMind historical records untouched** (~150 files under
  `complete/`, `active/`, `draft/`, `issued/`, records) — dated records of past
  work. Two further exclusions of the same kind: `planned.md:121` and
  `dashboard.md:92` reference Mind *prompt paths* (`feature/pyautobuild/…`,
  `research/autobuild/git_docs.md`); those are registry pointers to real files
  on disk, so rewriting the string without moving the files breaks the link.
- **But PyAutoMind has two LIVE exceptions that must change** (found on the
  deep sweep; they are code and routing, not records):
  - `scripts/repos_sync.py:558-570` — a hard-coded dict keyed by
    `PyAutoHands/autobuild/<module>.py` paths. `repos_sync.py --write`
    regenerates the AGENTS.md repo tables and breaks silently without this.
  - `ROUTING.md:38` — lists `autobuild` as a routing target.
- Confirmed absent, do not go hunting again: no root-level `PyAutoLabs/*.md`
  references, and no `auto_build` / `autoBuild` / `Autobuild` spelling variants
  anywhere in the workspace.
- Two import styles must both keep working: dotted (`from autobuild.build_util
  import …`, PyAutoHands' own tests) and flat-on-`PYTHONPATH`
  (`from build_util import …`, workspaces — only the `sys.path` string changes).
- Use `git mv` so history follows the files.
- No `setup.py`/`pyproject.toml` exists, so no PyPI package name is at stake.

## Run conditions (recorded at launch, 2026-07-23)

- **Phasing override.** The Brain Feature Agent scored this `too-large (37)` and
  recommended `split-into-phases` (design / core-api / workspace-examples /
  docs). Not taken, with the human's approval: the score is driven by repo count
  (16), not conceptual complexity; there is no design phase in a mechanical
  rename; and sequential phases would violate the atomic-landing guardrail above
  by leaving a window where Hands has moved and Heart's CI still points at the
  old path. The work is still ~18 PRs (one per repo) sharing one branch name.
- **Heart was RED (score 0) at launch** — 13 test failures, 33 stale parked
  scripts, release validation `integrate:fail`. None caused by this task, and
  the corrective-PR exception does not apply (this rename repairs no RED
  reason). Per `AUTONOMY.md`, RED forbids commit/push/PR-open at every autonomy
  level, so this run is expected to park at the ship gate. Effective autonomy
  = min(`supervised` header, `safe` refactor cap) = **supervised**.

<!-- authored by start_dev from a direct user request on 2026-07-23; scope
     decisions (all live code + docs / preserve historical refs / no shim)
     confirmed with the user before planning -->

[Jammy2211]

Parked at the ship gate — Heart RED (autonomous run, --auto, effective autonomy supervised)

The rename is complete and verified in the worktree, but nothing has been committed, pushed, or opened as a PR. Per AUTONOMY.md, Heart RED forbids commit/push/PR-open at every autonomy level, and the corrective-PR exception explicitly never fires under --auto. This rename repairs none of the RED reasons, so the exception would not apply even if a human invoked it.

Heart verdict re-read at ship time (not the launch reading) — RELEASE READINESS ✗ RED score 0:

✗ PyAutoFit: 1 commit(s) behind origin
✗ PyAutoGalaxy: 1 commit(s) behind origin
✗ PyAutoLens: 1 commit(s) behind origin
✗ release validation FAILED (stage integrate)
! workspace validation not passing (13 failed, 2026-07-21T19-05-22Z)
! 33 stale parked script(s)

What is done (in ~/Code/PyAutoLabs-wt/rename-autobuild-to-autohands/, uncommitted)

Repo	Files changed
PyAutoHands	53 (incl. git mv autobuild autohands, git mv bin/autobuild bin/autohands)
PyAutoBrain	19
PyAutoHeart	12
autolens/autogalaxy/autofit workspaces	5 / 6 / 5
the four *_workspace_test repos	3 / 3 / 2 / 1
HowToLens / HowToGalaxy / HowToFit	3 / 3 / 3
autolens/autofit/autocti assistants	2 / 2 / 1
PyAutoMind (live files only)	2
admin_jammy	1

Verification performed

• PyAutoHands: 132 passed — this is the real regression surface, since its tests use dotted from autohands.build_util import … imports.
• PyAutoBrain: 152 passed, 1 failed — test_skill_install.py::test_every_public_agent_has_a_skill_wrapper (missing sizing wrapper). Confirmed pre-existing on main, not caused by this change.
• repos_sync.py --check — output identical to main (same 2 pre-existing tenant-firewall mismatches, no new ones). This is a meaningful check, not a vacuous pass: FIREWALL_ALLOWLIST is keyed by real file path, so had the PyAutoHands/autobuild/*.py keys been missed, all 13 moved modules would have surfaced as "unlisted file" violations.
• bash -n clean on bin/autohands, pre_build.sh, _common.sh, build.sh, health_release.sh; autohands help renders correctly.
• Every PyAutoHands/autohands/<module> path referenced anywhere in the workspace resolves to a file that exists.

Two findings worth recording

1. PyAutoMind/scripts/repos_sync.py:558-570 held a hard-coded dict keyed by PyAutoHands/autobuild/<module>.py. It was missed by the first repo-level pass (PyAutoMind had been excluded wholesale as "historical") and caught on the deep sweep. Missing it would have broken repos_sync.py --write silently. ROUTING.md:38 was the only other live Mind file.
2. PyAutoHeart/heart/checks/url_check_live.sh:16 carried a usage comment pointing at a Hands path that did not exist on main either — the script had been migrated into PyAutoHeart. Since the rename touched that line, it was corrected to the file's real home (heart/checks/url_check_live.sh) rather than left knowingly wrong.

Deliberately preserved

PyAutoBuild#NNN issue citations; rhayes777/PyAutoBuild patterns in url_fixups.yaml / url_check.sh; the pyautobuild: pyautohands policy alias; pyautobuild_boundary_audit.md (a real filename); ~150 Mind historical records; planned.md:121 + dashboard.md:92 prompt-path pointers; the two gitignored settings.local.json allowlists; and the PYAUTOBUILD_DIR docstring in regenerate_navigator.py, which describes a shim that no longer exists.

autobuild was additionally kept as a back-compat router keyword in policy.yaml, _intake.py and _bug.py — those are typed keywords, not paths, so retaining the old word keeps existing prompts routing to Hands at no cost.

To resume

Heart must clear RED first. Then /ship_library, merging in one pass while CI is quiet: PyAutoHands → PyAutoHeart → PyAutoBrain → workspaces. The directory move breaks workspace-validation.yml and every workspace run_smoke.py the moment Hands merges — that window is the accepted cost of landing without a shim.

[Jammy2211]

RED investigation (human-authorized) — the blocker is largely stale evidence

Heart moved score 0 → 40 after refreshing stale local checkouts. Findings on what remains:

1. release validation FAILED (stage integrate) — STALE, already fixed on main

The only hard ✗ reason. Traced to run 29912642195, which had exactly 3 script failures:

Script	Failure
scripts/cluster/start_here.py	TIMEOUT at the 1800s cap
interferometer/features/potential_correction/start_here.py	ValueError: The dpsi grid is too sparse
interferometer/features/potential_correction/likelihood_function.py	same ValueError

Both potential_correction failures share one root cause: PYAUTO_SMALL_DATASETS=1 caps masks to 15×15, starving the dpsi mesh in mesh.py:132 get_itp_box_ctr. The profile's existing interferometer/start_here override does not reach them, because that pattern is a substring match and their paths are interferometer/features/potential_correction/....

That fix is already merged. autolens_workspace commit f582fb7f5 — "fix: unblock release validation — potential_correction env override + 2 SLOW-skips" — adds precisely that override (and SLOW-skips covering the cluster timeout). Timeline:

• failing run started 2026-07-22 10:40
• fix landed 2026-07-22 19:26 — about 9 hours later

The workspace validation not passing (13 failed) reason is dated 2026-07-21T19-05-22Z, also before the fix. So both reasons judge evidence generated before their own repair. No source fix is needed for either — they need fresh evidence.

2. manifest drift: tenant firewall — 4 mismatch(es) — LIVE, and it grew 2→4 today

Two are long-standing (test_mind_commit_guard.py, test_workspace_config_precedence.py). Two are new, introduced by PR #178 (clone-skill-prefix-corruption), merged after this task's worktree was created:

• PyAutoHands/tests/test_clone_seed_substitute.py — new file, not in FIREWALL_ALLOWLIST
• PyAutoBrain/agents/conductors/clone/_clone.py:417 — new autocti_assistant fact

Correct fix is allowlisting in PyAutoMind/scripts/repos_sync.py: the test must name instances because it tests clone-name substitution, exactly like its already-allowlisted sibling test_clone_conductor.py. This is a one-file change, but landing it needs the corrective-PR exception (human, quoting the reason string — the quote is above).

3. Consequence for this task

PR #178 also touched clone_seed.py, which this branch renamed to autohands/clone_seed.py. 11 of the 18 branches are now behind origin/main (PyAutoMind by 8). They need main merged in before shipping, which cannot happen while the work stays uncommitted under RED.