feat(PyAutoBrain): hygiene conductor — phase 1 scaffold + boundaries

[Jammy2211]

Overview

Phase 1 of growing a PyAutoBrain hygiene conductor — the code-quality upkeep function (developer-loop cost + repo tidiness), distinct from Heart (proof-of-works) and profiling (modeling-compute speed). This phase makes the conductor real, routable, and correctly bounded with its five modes stubbed — no behaviour yet. It also corrects the profiling↔hygiene boundary now that hygiene is a real conductor. Design of record: PyAutoMind/feature/pyautobrain/hygiene_agent.md; decision: PyAutoMind/research/pyautobrain/hygiene_agent_decision.md (conductor, no new paired repo — reuse Heart for tracking, absorb repo_cleanup + cli_noise_clean, consult dep_audit + audit_docs).

Plan

• Stand up a new conductor at agents/conductors/hygiene/ (AGENTS.md + hygiene.sh skeleton), mirroring the profiling conductor.
• Charter: code-quality upkeep; emit a HygieneDecision; consult the vitals faculty; never issue health verdicts or touch Build.
• Stub all five modes — perf / tidy / noise / deps / docs + a default prioritized worklist — implemented in later phases.
• Wire into dispatch (bin/pyauto-brain), the /hygiene veneer (skills/hygiene/), and skills/COMMANDS.md.
• Correct boundaries now (the reason this is phase 1): rewrite profiling's stale ## vs hygiene block and move its "hunting generally-slow functions flagged by integration tests" future mode into hygiene's perf (phase 3); repoint repo_cleanup's "Future Cleanup Agent" note.
• Ship the shell + corrected boundaries only.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary)

Work Classification

Library (Brain-source)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoBrain	main (behind origin 3 — ff-sync at worktree cut)	clean

Suggested branch: feature/hygiene-agent
Worktree root: ~/Code/PyAutoLabs-wt/hygiene-agent/ (created by /start_library)

Implementation Steps

1. agents/conductors/hygiene/AGENTS.md — tier: conductor; charter; modes table (5 modes described, staged); boundaries vs profiling/health/bug-refactor/build; emits HygieneDecision.
2. agents/conductors/hygiene/hygiene.sh — bash skeleton mirroring profiling.sh: mode + --json arg-parse, "staged — phase N" notices, shared exit-code convention, stdlib/bash only.
3. bin/pyauto-brain — add [hygiene] to the dispatch map, the one-line description, the usage-comment block, and CONDUCTOR_ORDER.
4. skills/hygiene/hygiene.md + ~/.claude/commands/hygiene.md — /hygiene veneer + symlink via bin/install.sh.
5. skills/COMMANDS.md — add the /hygiene row and veneer-list entry.
6. agents/conductors/profiling/AGENTS.md — rewrite ## vs hygiene to the measured-thing split (profiling = modeling/compute speed; hygiene = dev-loop cost); remove "slow integration-function hunting" from its Future modes.
7. skills/repo_cleanup/SKILL.md — repoint the "Future Cleanup Agent" note at the built conductor.

Key Files

• agents/conductors/profiling/ — the conductor pattern to mirror (AGENTS.md + .sh + optional stdlib helper).
• bin/pyauto-brain — dispatch map, descriptions, CONDUCTOR_ORDER.
• skills/COMMANDS.md — the human-veneer registry.

Testing

bin/pyauto-brain hygiene and /hygiene resolve and print the staged mode menu; bin/pyauto-brain help lists hygiene in CONDUCTOR_ORDER; boundary edits read correctly. No behavioural tests (modes are stubs).

Out of scope (later phases)

Phase 2 — absorb repo_cleanup (→ tidy) + cli_noise_clean (→ noise), consult dep_audit (→ deps) + audit_docs (→ docs), default prioritized worklist. Phase 3 — perf mode (test/script/import timing, delegate to refactor/bug, JAX-adapt judgement) + optional PyAutoHeart legs (import_time / cli_noise).

Autonomy

--auto, effective level supervised (header supervised ∧ feature-medium cap safe). Plan written here; mechanical implementation proceeds; parks at ship sign-off (checkpoint-and-continue). No Heart YELLOW reason set acknowledged at launch. Merge/close human.

Original Prompt

Click to expand starting prompt

Phase 1 of the hygiene conductor (umbrella + settled design: feature/pyautobrain/hygiene_agent.md; decision: research/pyautobrain/hygiene_agent_decision.md). Make the conductor real, routable, and correctly bounded with its modes stubbed — no behaviour yet. Mirror the profiling conductor's wiring exactly.

Build: the conductor dir (AGENTS.md + hygiene.sh skeleton), wire into bin/pyauto-brain / /hygiene veneer / COMMANDS.md. Correct boundaries: profiling's ## vs hygiene block + move its "slow integration-function" future mode into hygiene's perf; repoint repo_cleanup's "Future Cleanup Agent" note. Out of scope: any real mode behaviour (phases 2–3).

Done when: bin/pyauto-brain hygiene and /hygiene resolve and print the staged mode menu; boundaries stated; profiling + repo_cleanup pointers updated; nothing else changed.