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).
This commit is contained in:
Travis Herbranson 2026-05-23 06:49:50 -04:00
parent 236616514f
commit 31c67b9573
6 changed files with 31 additions and 9 deletions

View File

@ -6,7 +6,7 @@ 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
homelab / pbs / docker project domains. Phase 7 of the
repo-hygiene-remediation project: the durable version of the one-time audit.
## Architecture
@ -26,9 +26,13 @@ repo-hygiene-remediation project: the durable version of the one-time audit.
- **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.
- **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.

View File

@ -1,7 +1,7 @@
# 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
across the `homelab`, `pbs`, and `docker` project domains and reports
the findings, grouped by remediation phase.
It is the durable, repeatable version of the one-time 2026-05-19/20

Binary file not shown.

View File

@ -1,7 +1,7 @@
---
name: repo-hygiene-audit
description: >
Repeatable hygiene audit across the homelab / pbs / docker / root project
Repeatable hygiene audit across the homelab / pbs / docker project
domains. Runs scripted, read-only checks for git auditability and .git
ownership drift, .env file permissions, inline secrets in compose files,
non-git directories, uv-init leftover stubs, docker-compose.yml -> compose.yml
@ -39,18 +39,24 @@ wrong doc is worse than a missing one). That semantic scoring is the human part.
This skill automates the **mechanical enumeration** underneath it: sweep every
repo in every domain and flag the objective signals that drift produces.
Domains (the four the audit covered):
Default domains scanned:
| Domain | Roots scanned |
|--------|---------------|
| `homelab` | `/opt/projects/homelab/*` |
| `pbs` | `/opt/projects/pbs/*` |
| `docker` | `/opt/projects/docker/*`, `~/projects/docker/*` (compose stacks) |
| `root` | `/opt/projects/wiki-vault`, `/opt/projects/wiki-context` |
`docker` repos are treated as compose stacks: README expected, **no per-stack
CLAUDE.md** (per the locked doc-role convention).
**The Obsidian vault (`wiki-vault`, `wiki-context`) is intentionally out of
scope.** It's an MCP-owned, managed surface — the vault MCP maintains its own
context — so a second scanner poking at it risks interference. The original
audit covered it as a "root" domain; this recurring skill deliberately does
not. The `--scan` / `--repo` escape hatch can still point at it manually if
ever truly needed; don't re-add it to the defaults.
## Workflow
### Step 1 — Run the scripted sweep

View File

@ -12,6 +12,14 @@ CLAUDE.md = concise agent guide (not a README clone); docker compose stacks get
README only; prefer `main` over `master`; GitHub-destined repos are pushed
manually.
## Scope
Default domains: `homelab`, `pbs`, `docker`. The Obsidian vault (`wiki-vault`,
`wiki-context`) is **intentionally excluded** — it's an MCP-owned, managed
surface, so a second scanner risks interfering with how the vault MCP maintains
its context. Use `--scan` / `--repo` to point at it manually if ever needed;
don't re-add it to the defaults.
## AUDITABILITY (maps to Phase 3 — unblock un-auditable repos)
| check id | Looks for | Severity | Why |

View File

@ -43,11 +43,15 @@ from pathlib import Path
# A domain either scans the immediate children of one or more roots ("scan"),
# or names explicit repo paths ("repos"), or both. Override with --config.
#
# The Obsidian vault (wiki-vault, wiki-context) is deliberately NOT a default
# domain: it's an MCP-owned, managed surface (the vault MCP maintains its
# context), so a second scanner poking at it risks interference. Point --scan
# or --repo at it manually if you ever truly need to.
DEFAULT_DOMAINS: dict[str, dict[str, list[str]]] = {
"homelab": {"scan": ["/opt/projects/homelab"]},
"pbs": {"scan": ["/opt/projects/pbs"]},
"docker": {"scan": ["/opt/projects/docker", "/home/herbyadmin/projects/docker"]},
"root": {"repos": ["/opt/projects/wiki-vault", "/opt/projects/wiki-context"]},
}
# Conventions from the repo-hygiene-remediation plan (Locked Decisions).