rootnode-repo-hygiene

A two-phase Skill for auditing and cleaning up Claude Code repositories. Phase 1 sweeps the repo across 14 categories of hygiene concern plus a cross-category 7-layer placement leak check, producing a HYGIENE_REPORT.md. Phase 2 reads [APPROVED] markers placed in that file and executes the marked findings under critic-gate composition with halt-on-failure discipline.

The Skill is the operational counterpart to rootnode-cc-design: design produces the environment, hygiene maintains it. Structural findings that warrant fix-recipe derivation route to rootnode-cc-design REMEDIATE rather than executing here. Process-abstraction candidates that recur across CC environments route as warrant evidence for rootnode-skill-builder v2.

Important — five principles that govern Phase 2 behavior

These five principles override looser interpretations elsewhere in this Skill. They are enforcement-grade.

1. Authorization is file-state-grounded. Phase 2 reads [APPROVED] markers from the report file. Verbal authorization in chat is never a substitute. The Skill MAY act as a text editor on the user's behalf using the three approval forms (blanket, fragmented, conditional — see "Authorization discipline" below). When acting as editor, the Skill produces the marked file for the user to save; Phase 2 then reads the saved file. There is no verbal-authorization fallback. The discipline guards against the silent execution problem: chat-side intent is high-context but ephemeral; the marked file is the durable contract.

2. Recommendation-only categories never execute directly. Categories 11-14 and 7-layer leak findings are recommendation-only. [APPROVED] markers on these findings are noted in Phase 2 but produce a "skipped — REMEDIATE recommended" notice rather than an execution batch. The marker is preserved in the report file (it documents user intent) but does not become a file edit. Reason: structural change requires fix-recipe derivation and 7-layer placement validation that single-edit Phase 2 execution cannot perform safely.

3. Defer-to-downstream is a first-class commit-plan option. When Phase 1 detects distribution intent + working-tree state + downstream-resolvable findings, it recommends defer-to-downstream over Options A/B/C. Phase 2 accepts deferral and executes file edits without git operations; the cleanup_execution_log substitutes for commit messages as the audit trail. This is the production-validated pattern from a CC deployment where engine-baseline commit hit a permission denial on 207 MB / 883-file scope and Path 3 deferral was the right answer rather than retrying a failed commit.

4. Bootstrap heritage carve-out calibrates Cat 1. When the active profile contains a bootstrap_heritage block, Cat 1 produces a "Bootstrap heritage inventory" subsection at the top of its findings and applies sharpened detection conditions: findings only surface for inherited content modified after the threshold date, referenced by in-engine code, treated as authoritative in current docs, or otherwise active in the current project. This eliminates false positives on legitimate inherited content while preserving the ability to catch problematic inheritance.

5. Structural findings route to REMEDIATE. Cat 11-14 and 7-layer leaks always route to rootnode-cc-design REMEDIATE mode. The handoff is named explicitly in the report's "Routing recommendations" section when remediate_routing: true (default). REMEDIATE handles fix-recipe derivation and 7-layer placement validation that single-edit Phase 2 execution cannot.

When to use

Trigger this Skill on:

• "Audit my CC repo" / "sweep my repository for hygiene" / "check this CC environment"
• "Find process-abstraction candidates" / "what work patterns should be lifted to scripts/Skills/hooks"
• "Review my CLAUDE.md" / "clean up my .claude directory"
• "Pre-distribution hygiene check" / "before-shipping cleanup pass"
• "Find layer leaks in my CC setup" / "what's in the wrong layer"
• "Parent-project vestiges" (when the repo was bootstrapped from another project)

Symptom-phrased triggers also apply: "my CLAUDE.md feels bloated," "I have permissions I don't think I use anymore," "my CC environment has accumulated drift," "I want to know what to clean up before I share this repo."

The Skill operates CC-side only. It scans Claude Code repositories — .claude/ directory, CLAUDE.md, hooks, subagents, MCP configurations. It does not audit Claude Projects (CP-side). For Project audits, use rootnode-project-audit.

Two-phase workflow

Phase 1 — Sweep

Phase 1 walks four steps:

1. Pre-flight inventory. Read CLAUDE.md, settings files (.claude/settings.json, .claude/settings.local.json), Skills (.claude/skills/), agents (.claude/agents/), hooks, MCP declarations. Detect bootstrap_heritage block in active profile and capture its inventory. Capture working-tree state (informational; never halt). Output: pre-flight summary at the top of the report file.

2. Category sweep. Walk categories 1-14 per active profile in numerical order. Each category produces findings in its standard format (F-{cat}.{n} ID, risk tag, confidence tag, evidence quote, recommended action). Cat 1 applies bootstrap heritage calibration when active. Cat 2 runs both stale-removal and missing-entry directions (D9). Cat 14 produces 8-field candidate blocks rather than standard findings. See references/sweep-categories.md for detection rules per category.

3. 7-layer leak check (when profile enables it). Cross-category analytical pass after the sweep. Walks the full standing-context inventory and applies six layer-pair tests. Surfaces L-{n} findings for content placed in the wrong layer for its concern. Findings appear in their own "7-Layer Leak Findings" section near the end of the report. See references/seven-layer-framework.md.

4. Report assembly. Produce output/hygiene_reports/HYGIENE_REPORT_{ISO8601}.md with: pre-flight summary, per-category findings sections, 7-layer leak findings section (if enabled), "Routing recommendations" section (if remediate_routing: true), "Recommended commit plan" section (if include_commit_plan: true), and a marking ledger area at the bottom. The marking ledger is empty at Phase 1 end; the user (or the Skill acting as editor) populates it as authorization decisions are made.

Phase 2 — Execute

Phase 2 walks five steps:

1. Entry conditions. Five gate checks: file-state authorization (≥1 [APPROVED] marker in report), profile validation (JSON validates against schema), engine baseline coherence (state hasn't drifted since Phase 0), critic-gate availability (when threshold is required), marker placement validation (no [APPROVED] markers on Cat 11-14 / leak findings — those skip with notice). Failing any condition halts Phase 2 entry with the specific failure surfaced.

2. Batch construction. Group [APPROVED] Cat 1-10 findings into batches: one category per batch, subdivided by confidence tier and risk tier. Higher-confidence and lower-risk batches execute first. Each batch carries metadata for the verification step: file changes expected, category-specific verification command, finding IDs included.

3. Per-batch execution. Plan submission → critic-gate review (when applicable) → execute → post-batch verification → log to cleanup_execution_log.md. See references/execution-discipline.md for the per-category verification table and full critic-gate composition rules including the 3-cycle REQUEST_CHANGES cap.

4. Commit plan execution. Apply the chosen plan (Option A/B/C or defer-to-downstream). The Skill never auto-runs the engine-baseline commit (Step 1 of Options B/C); the user runs it manually pre-Phase-2 because the scope is too large to commit without explicit user review. The Skill runs the cleanup commit (Step 2) using a message built from the cleanup log.

5. Final verification sweep. En