feat(PyAutoBrain): hygiene conductor — phase 2 modes (absorb + consult)

[Jammy2211]

Overview

Phase 2 of the PyAutoBrain hygiene conductor (phase 1 scaffold merged in #88). Give the four non-perf modes real behaviour by wiring them to the hygiene skills that already exist, and make the default no-arg run one prioritized worklist across them. perf stays staged for phase 3. Umbrella: PyAutoMind/issued/hygiene_agent.md; decision: PyAutoMind/research/pyautobrain/hygiene_agent_decision.md.

Plan

• tidy — drive repo_cleanup's audit → HygieneDecision rows (stale branches / stashes / [gone] refs / dirty checkouts).
• noise — drive cli_noise_clean's audit (warnings / stray prints / library chatter).
• deps — consult dep_audit (version-cap drift vs PyPI, risk-tiered).
• docs — consult audit_docs (stale docs/api/*.rst module paths).
• default (no-arg) — run the audits → ONE prioritized HygieneDecision worklist, each row tagged with mode + delegate.
• Extend --json so each mode emits real finding rows; flip staged notices in the conductor + veneer + repo_cleanup/SKILL.md.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary)

Work Classification

Library (Brain-source)

Design fork — settle first

The conductor's charter is reason and delegate; never edit source, never mutate other repos (stays stdlib/bash, no JAX). So "absorb" must NOT move destructive logic into the Brain. Recommended: each mode owns the AUDIT + prioritization and points at the existing skill for EXECUTION — the skills stay the executors (repo_cleanup keeps its interactive per-bucket git mechanics + safety gates; the others keep their fix/report steps). The conductor parses their audit output (or re-implements only the read-only audit where cleaner) and unifies + ranks. Confirm before coding. Under --auto supervised, an unsettled fork at implementation becomes a batched issue question (checkpoint-and-continue).

Implementation Steps

1. agents/conductors/hygiene/hygiene.sh (+ optional stdlib helper) — implement tidy/noise/deps/docs audits (drive/parse the four skills) and the default ranked worklist; extend the --json HygieneDecision with real rows.
2. agents/conductors/hygiene/AGENTS.md — flip the four modes from staged → implemented; document the delegate each routes to.
3. skills/hygiene/hygiene.md — update the staged note (only perf remains staged).
4. skills/repo_cleanup/SKILL.md — note the tidy mode now exists.

Key Files

• skills/repo_cleanup/, skills/cli_noise_clean/, skills/dep_audit/, skills/audit_docs/ — the four skills the modes drive/consult.
• agents/conductors/hygiene/ — the conductor to extend.

Testing

pyauto-brain hygiene {tidy,noise,deps,docs} each emit real audit findings (human + --json); no-arg run emits one prioritized worklist; PyAutoBrain tests/ green.

Out of scope

perf mode + PyAutoHeart legs (import_time/cli_noise) — phase 3.

Autonomy

--auto, effective supervised (header supervised ∧ feature-medium cap safe). Parks at ship sign-off; the design fork above parks as a batched issue question if unsettled at implementation. Merge/close human.

Original Prompt

Click to expand starting prompt

Phase 2 of the hygiene conductor: give the four non-perf modes real behaviour by wiring them to the existing hygiene skills, and make the default no-arg run a single prioritized worklist. tidy←repo_cleanup, noise←cli_noise_clean, deps←dep_audit, docs←audit_docs. Design fork: conductor reasons + delegates (never mutates) → modes own the audit + prioritization and point at the skill for execution; skills stay the executors. Extend --json with real rows. Out of scope: perf + Heart legs (phase 3). Done when the four modes emit real findings + the no-arg run ranks them + tests green.