236616514f
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.
69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.
|