# 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.