diff --git a/CLAUDE.md b/CLAUDE.md index 62ad6f1..8662ee7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/README.md b/README.md index ebd2938..63bcd89 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/repo-hygiene-audit.skill b/repo-hygiene-audit.skill index cbe2a1b..7b64c99 100644 Binary files a/repo-hygiene-audit.skill and b/repo-hygiene-audit.skill differ diff --git a/repo-hygiene-audit/SKILL.md b/repo-hygiene-audit/SKILL.md index 130cfb7..d422f73 100644 --- a/repo-hygiene-audit/SKILL.md +++ b/repo-hygiene-audit/SKILL.md @@ -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 diff --git a/repo-hygiene-audit/references/check-catalog.md b/repo-hygiene-audit/references/check-catalog.md index 668c1a3..dd00104 100644 --- a/repo-hygiene-audit/references/check-catalog.md +++ b/repo-hygiene-audit/references/check-catalog.md @@ -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 | diff --git a/repo-hygiene-audit/scripts/audit.py b/repo-hygiene-audit/scripts/audit.py index 6b91b16..777287f 100644 --- a/repo-hygiene-audit/scripts/audit.py +++ b/repo-hygiene-audit/scripts/audit.py @@ -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).