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.
76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# repo-hygiene-audit
|
|
|
|
A Claude Code / Cowork skill that runs a **repeatable, read-only hygiene audit**
|
|
across the `homelab`, `pbs`, `docker`, and `root` project domains and reports
|
|
the findings, grouped by remediation phase.
|
|
|
|
It is the durable, repeatable version of the one-time 2026-05-19/20
|
|
documentation/repo audit — Phase 7 of the *repo-hygiene-remediation* project.
|
|
The original sweep proved that a one-time pass isn't enough; this skill makes
|
|
the mechanical part runnable on a cadence so the project folders don't drift
|
|
back into inconsistency.
|
|
|
|
## What it checks
|
|
|
|
- **Git auditability & ownership** — missing/empty `.git`, dubious ownership,
|
|
`.git`-vs-directory owner drift, group drift.
|
|
- **Secrets & permissions** — world-readable / wrong-mode `.env` files, secrets
|
|
inlined in compose files.
|
|
- **Cleanups** — `uv init` leftover stubs, `docker-compose.yml` → `compose.yml`
|
|
naming, stale review docs, `herbygitea` SSH-alias residue, stray backup dirs.
|
|
- **Git state** — `master`-vs-`main` default branch, leftover `docs-audit`
|
|
branches, dirty trees, stray worktrees, unpushed commits.
|
|
- **Docs** — missing README/CLAUDE.md, oversized CLAUDE.md (likely README clone).
|
|
|
|
Full catalogue: [`repo-hygiene-audit/references/check-catalog.md`](repo-hygiene-audit/references/check-catalog.md).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
cd repo-hygiene-audit
|
|
|
|
# Terminal triage across all default domains:
|
|
python scripts/audit.py
|
|
|
|
# Phase-mapped markdown (pastes into the remediation plan):
|
|
python scripts/audit.py --format md -o findings-$(date +%Y%m%d).md
|
|
|
|
# Machine-readable, for week-over-week diffing:
|
|
python scripts/audit.py --format json -o findings-$(date +%Y%m%d).json
|
|
```
|
|
|
|
No third-party dependencies — `python3` (or `uv run python`) is enough. The
|
|
script is **read-only**: it never edits, commits, or pushes the repos it scans.
|
|
|
|
### Useful flags
|
|
|
|
| Flag | Purpose |
|
|
|------|---------|
|
|
| `--format {text,json,md}` | Output format (default `text`) |
|
|
| `-o, --output PATH` | Write to a file instead of stdout |
|
|
| `--config FILE.json` | Override the domain map |
|
|
| `--scan NAME=PATH` | Ad-hoc scan of a directory's children |
|
|
| `--only CATEGORY` | Restrict to one or more categories |
|
|
| `--fail-on SEVERITY` | Non-zero exit at/above a severity (automation hook) |
|
|
|
|
## Layout
|
|
|
|
```
|
|
repo-hygiene-audit-skill/
|
|
├── README.md # this file (human onboarding)
|
|
├── CLAUDE.md # agent operating guide
|
|
├── repo-hygiene-audit/ # the skill itself
|
|
│ ├── SKILL.md # trigger + workflow
|
|
│ ├── scripts/audit.py # read-only check engine
|
|
│ └── references/
|
|
│ ├── check-catalog.md # every check + rationale
|
|
│ └── findings-format.md # output schema + phase mapping
|
|
├── repo-hygiene-audit.skill # packaged bundle (zip of the above)
|
|
└── sessions/ # session notes
|
|
```
|
|
|
|
## Cadence
|
|
|
|
Currently **weekly, triggered manually** by Travis (no automation yet). The
|
|
`--fail-on` flag is the hook if/when this becomes a scheduled task.
|