Travis Herbranson 31c67b9573 Drop Obsidian vault (root domain) from default audit scope

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

2026-05-23 06:49:50 -04:00

3.3 KiB

Raw Blame History

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

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

3.3 KiB Raw Blame History