31c67b9573
wiki-vault/wiki-context are an MCP-owned, managed surface — a second scanner risks interfering with how the vault MCP maintains its context. Remove the 'root' domain from DEFAULT_DOMAINS so a plain run no longer touches the vault; the --scan/--repo escape hatch still allows manual one-offs. Updated SKILL.md, check-catalog, findings-format, README, CLAUDE.md with the rationale. Default run: 3 domains, 37 repos, 54 findings (was 61); clears the vault-only false positives (herbygitea doc-mention, wiki-context uv-init stub).
73 lines
3.3 KiB
Markdown
73 lines
3.3 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 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.** Domains can also name
|
|
explicit repo paths via `repos` (vs `scan`) if a one-off is ever needed.
|
|
- **The Obsidian vault is intentionally NOT a default domain.** wiki-vault /
|
|
wiki-context are MCP-owned, managed surfaces — a second scanner risks
|
|
interfering with the vault MCP's context. Don't "helpfully" re-add a `root`
|
|
domain to `DEFAULT_DOMAINS`; the `--scan`/`--repo` escape hatch covers manual
|
|
one-offs.
|
|
- **`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.
|