Travis Herbranson 236616514f Add repo-hygiene-audit skill (Phase 7: repeatable hygiene sweep)

Read-only scripted audit across homelab/pbs/docker/root domains:
git auditability + .git ownership/dubious, .env perms (0660/devprojects),
inline compose secrets, non-git dirs, uv-init stubs, compose naming,
master-vs-main default, dirty trees, worktrees, herbygitea residue, doc
presence. Emits text/json/md findings mapped to remediation-plan phases.

SKILL.md + scripts/audit.py (stdlib-only) + references + packed .skill.
First run: 39 repos, 62 findings, ruff-clean.

2026-05-22 23:11:48 -04:00

3.0 KiB

Raw Blame History

CLAUDE.md

Agent operating guide for the repo-hygiene-audit skill repo. Human onboarding lives in README.md — this file is the concise, gotcha-focused guide.

What this is

A Claude skill that runs a repeatable, read-only hygiene audit across the homelab / pbs / docker / root project domains. Phase 7 of the repo-hygiene-remediation project: the durable version of the one-time audit.

Architecture

repo-hygiene-audit/SKILL.md — the contract: trigger description + the five-step workflow. Source of truth for what the skill does.
repo-hygiene-audit/scripts/audit.py — the engine. Pure stdlib, single file. discover_repos() → per-repo CHECKS list → Finding records → renderers (text / md / json).
repo-hygiene-audit/references/ — check-catalog.md (every check + why), findings-format.md (output schema + category→phase map).
repo-hygiene-audit.skill — zip of SKILL.md scripts/ references/. Repack after any change under repo-hygiene-audit/.

Gotchas / non-obvious rules

Read-only is the contract. The script must never write to the trees it scans — only to --output. All git invocations use read subcommands. Don't add a check that mutates a repo.
Each repo = an immediate child of a domain root. The root domain is the exception: it names explicit repo paths (wiki-vault, wiki-context), not a scan root.
docker domain repos are compose stacks — README expected, CLAUDE.md intentionally NOT expected (COMPOSE_STACK_DOMAINS). Don't "fix" the missing CLAUDE.md flag suppression there.
safe.directory wildcard caveat is load-bearing in the hints: always steer toward a scoped safe.directory <path>, never *.
Self-reference trap: audit.py literally contains the string herbygitea as a detection pattern. check_herbygitea_residue excludes its own file by resolved path — keep that exclusion if you refactor.
Heuristic checks (inline-secret, uv-init-stub, claude-md-bloat) can false-positive. They flag candidates for human judgement, not certainties.
Findings keys are stable (domain/repo:check) on purpose — week-over-week JSON diffing depends on it. Don't churn check ids casually.

Commands

# Run the sweep (default domains)
python repo-hygiene-audit/scripts/audit.py

# Lint (matches Travis's scaffolding ruleset)
ruff check repo-hygiene-audit/scripts/audit.py --select E,F,B,I,UP,N,S,SIM,RET,PTH

# Repack the .skill after editing anything under repo-hygiene-audit/
cd repo-hygiene-audit && zip -r ../repo-hygiene-audit.skill SKILL.md scripts/ references/

Conventions enforced (from the remediation plan)

.env target 0660 + group devprojects; secrets in .env not inline compose; README = human onboarding, CLAUDE.md = concise agent guide; prefer main over master; GitHub-destined repos pushed manually.

Don't-touch

Don't add network calls or pip dependencies — stdlib-only is deliberate so it runs anywhere python3 exists.
Don't make the audit remediate. Reporting and fixing are separate steps.

3.0 KiB Raw Blame History