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 ## What this is
A Claude skill that runs a repeatable, **read-only** hygiene audit across the 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. repo-hygiene-remediation project: the durable version of the one-time audit.
## Architecture ## 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 - **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 scans — only to `--output`. All git invocations use read subcommands. Don't
add a check that mutates a repo. add a check that mutates a repo.
- **Each repo = an immediate child of a domain root.** The `root` domain is the - **Each repo = an immediate child of a domain root.** Domains can also name
exception: it names explicit repo paths (wiki-vault, wiki-context), not a explicit repo paths via `repos` (vs `scan`) if a one-off is ever needed.
scan root. - **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 - **`docker` domain repos are compose stacks** — README expected, CLAUDE.md
intentionally NOT expected (`COMPOSE_STACK_DOMAINS`). Don't "fix" the missing intentionally NOT expected (`COMPOSE_STACK_DOMAINS`). Don't "fix" the missing
CLAUDE.md flag suppression there. CLAUDE.md flag suppression there.

View File

@ -1,7 +1,7 @@
# repo-hygiene-audit # repo-hygiene-audit
A Claude Code / Cowork skill that runs a **repeatable, read-only 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. the findings, grouped by remediation phase.
It is the durable, repeatable version of the one-time 2026-05-19/20 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 name: repo-hygiene-audit
description: > 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 domains. Runs scripted, read-only checks for git auditability and .git
ownership drift, .env file permissions, inline secrets in compose files, ownership drift, .env file permissions, inline secrets in compose files,
non-git directories, uv-init leftover stubs, docker-compose.yml -> compose.yml 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 This skill automates the **mechanical enumeration** underneath it: sweep every
repo in every domain and flag the objective signals that drift produces. repo in every domain and flag the objective signals that drift produces.
Domains (the four the audit covered): Default domains scanned:
| Domain | Roots scanned | | Domain | Roots scanned |
|--------|---------------| |--------|---------------|
| `homelab` | `/opt/projects/homelab/*` | | `homelab` | `/opt/projects/homelab/*` |
| `pbs` | `/opt/projects/pbs/*` | | `pbs` | `/opt/projects/pbs/*` |
| `docker` | `/opt/projects/docker/*`, `~/projects/docker/*` (compose stacks) | | `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 `docker` repos are treated as compose stacks: README expected, **no per-stack
CLAUDE.md** (per the locked doc-role convention). 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 ## Workflow
### Step 1 — Run the scripted sweep ### 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 README only; prefer `main` over `master`; GitHub-destined repos are pushed
manually. 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) ## AUDITABILITY (maps to Phase 3 — unblock un-auditable repos)
| check id | Looks for | Severity | Why | | 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"), # A domain either scans the immediate children of one or more roots ("scan"),
# or names explicit repo paths ("repos"), or both. Override with --config. # 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]]] = { DEFAULT_DOMAINS: dict[str, dict[str, list[str]]] = {
"homelab": {"scan": ["/opt/projects/homelab"]}, "homelab": {"scan": ["/opt/projects/homelab"]},
"pbs": {"scan": ["/opt/projects/pbs"]}, "pbs": {"scan": ["/opt/projects/pbs"]},
"docker": {"scan": ["/opt/projects/docker", "/home/herbyadmin/projects/docker"]}, "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). # Conventions from the repo-hygiene-remediation plan (Locked Decisions).