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