claude-health

Claude Health Check

Trigger

• Keywords: health check, .claude check, config audit, lint .claude, claude health, plugin sync, version drift, upgrade check, doctor

When NOT to Use

• Code review (use /codex-review-fast)
• Doc review (use /codex-review-doc)
• Security review (use /codex-security)

Scope

| Argument | Description | |----------|-------------| | --scope hygiene | Only run C1-C7 hygiene checks | | --scope sync | Only run S1-S3 sync checks | | --scope all | Run both modules (default) |

Workflow

[--scope] → Select modules → Scan → Classify → Report → Fix suggestions
               │                                  │
       ┌───────┴───────┐                     P0/P1/P2
       ▼               ▼                    + fix commands
  Hygiene (C1-C7)  Sync (S1-S3)

Hygiene Module — Checks (7 items)

| # | Check | Method | Criteria | |---|-------|--------|----------| | 1 | Junk files | find .claude/ -name ".DS_Store" -o -name ".zip" -o -name ".tmp" | Any exists → P1 | | 2 | .gitignore exists | ls .claude/.gitignore | Missing → P1 | | 3 | .gitignore completeness | Read .claude/.gitignore, compare required items | Missing required → P2 | | 4 | Naming consistency | Scan all skills/*/ for reference vs references | Inconsistent → P2 | | 5 | README count sync | Count actual vs README description | Mismatch → P2 | | 6 | Command-Skill pairing | Each core skill should have corresponding command | Missing → P1 | | 7 | Cache size | du -sh .claude/cache/ | > 50M → P2 |

Check 1: Junk Files

find .claude/ -name ".DS_Store" -o -name "*.zip" -o -name ".tmp*" 2>/dev/null

• Has results → P1: List files, suggest deletion
• No results → ✅

Check 2-3: .gitignore

ls .claude/.gitignore 2>/dev/null || echo "MISSING"

Missing → P1. If exists, read content and compare required items:

| Required Item | Reason | |---------------|--------| | .DS_Store | macOS generates continuously | | settings.local.json | Personal config | | cache/ | Runtime cache | | .tmp* | Temp files | | .tmp | Temp files (suffix variant) | | .zip | Backup archives | | .claude_review_state.json | Review state tracking |

Missing any → P2

Check 4: Naming Consistency

# Scan all skill subdirectories
for dir in .claude/skills/*/; do
  if [ -d "${dir}reference" ]; then echo "INCONSISTENT: ${dir}reference"; fi
done

Has reference/ (singular) → P2, suggest renaming to references/

Check 5: README Count Sync

# Count actual items
ls .claude/commands/ 2>/dev/null | wc -l
ls .claude/skills/ 2>/dev/null | wc -l
ls .claude/agents/ 2>/dev/null | wc -l
ls .claude/rules/ 2>/dev/null | wc -l
ls .claude/hooks/*.sh 2>/dev/null | wc -l

Extract counts from README.md, compare. Mismatch → P2

Check 6: Command-Skill Pairing

Scan all skills/*/SKILL.md, exclude these types, then check for corresponding command:

| Exclude Type | Examples | Reason | |--------------|----------|--------| | Domain KB | portfolio, aum | Referenced by other skills, no standalone entry | | External | agent-browser | Not maintained by this project |

Remaining skills without command → P1

Check 7: Cache Size

du -sh .claude/cache/ 2>/dev/null

• \> 50M → P2, suggest cleanup
• ≤ 50M → ✅

Sync Module — Checks (S1-S3)

Only runs when --scope sync or --scope all (default).

S1: Version Check

| # | Check | Method | Criteria | |---|-------|--------|----------| | S1.1 | Manifest exists | Read .sd0x/install-state.json | Missing → P1 | | S1.2 | Manifest parseable | JSON.parse | Parse error → P1 | | S1.3 | schema_version current | == 1 | Mismatch → P2 | | S1.4 | plugin_version matches | manifest vs .claude-plugin/plugin.json or package.json | Mismatch → P1 | | S1.5 | Manifest completeness | Has rules + hook_scripts + scripts keys | Missing key → P2 (MANIFEST_GAP) |

Plugin version resolution (priority order):

.claude-plugin/plugin.json → package.json → "unknown"

Plugin source location (same as /install-rules Phase 1):

Glob: ~/.claude/plugins/**/sd0x-dev-flow/rules/auto-loop.md
Glob: ${REPO_ROOT}/node_modules/sd0x-dev-flow/rules/auto-loop.md
Fallback: @rules/auto-loop.md (plugin-relative)

S2: Component Classification

For each managed component (rules, hooks, scripts), compute 3 hashes and classify:

manifest_hash  = manifest[category][filename].hash    # null if missing
local_hash     = git hash-object --no-filters <local-path>  # null if file missing
plugin_hash    = git hash-object --no-filters <plugin-path>  # source of truth

Classification table (read-only diagnostic; maps to install-rules states for delegation):

| Doctor State | Condition | Severity | install-rules Equivalent | |-------|-----------|----------|--------------------------| | OK | local == manifest == plugin | ✅ | SKIP | | MISSING | local_hash is null, plugin exists | P1 | FRESH_INSTALL | | OUTDATED | local == manifest, plugin != manifest | P1 | AUTO_UPDATE | | LOCAL_MODIFIED | local != manifest, plugin == manifest | ✅ | KEEP_LOCAL | | CONFLICT | local != manifest, plugin != manifest | P2 | CONFLICT | | LEGACY | manifest_hash is null, local exists | P2 | LEGACY | | MANIFEST_GAP | manifest category key missing | P2 | N/A | | TOMBSTONED | manifest deleted: true, local missing | ✅ | SKIP_DELETED |

Managed inventory (hardcoded):

| Category | Local Path | Plugin Source | Files | |----------|-----------|--------------|-------| | Rules | .claude/rules/.md | rules/.md | auto-loop.md, codex-invocation.md, fix-all-issues.md, framework.md, testing.md, security.md, git-workflow.md, logging.md, docs-writing.md, docs-numbering.md, self-improvement.md, context-management.md | | Hooks | .claude/hooks/.sh | hooks/.sh | pre-edit-guard.sh, post-edit-format.sh, post-tool-review-state.sh, stop-guard.sh, post-compact-auto-loop.sh | | Scripts | .claude/scripts/ | scripts/ | precommit-runner.js, verify-runner.js, dep-audit.sh, commit-msg-guard.sh, pre-push-gate.sh, lib/utils.js |

S2.5: Override Safeguard Checks

5 checks for project override files (e.g., auto-loop-project.md):

| # | Check | Severity | Detection | Recommendation | |---|-------|----------|-----------|----------------| | 1 | Override drift | P2 | based_on hash comment in project file vs current base file hash | "Base auto-loop updated since override authored; review your overrides" | | 2 | Policy contradiction | P1 | Override's Auto-Trigger table omits a command that stop-guard.sh requires | "Override conflicts with stop-guard enforcement" | | 3 | Missing reference | P1 | .claude/CLAUDE.md has @rules/auto-loop-project.md but file missing, OR file exists but not referenced | /install-rules to recreate or add reference | | 4 | Wrong-layer edit | P2 | Base auto-loop.md has LOCAL_MODIFIED, CONFLICT, or LEGACY state while project override exists | "Move customization to auto-loop-project.md" | | 5 | Duplicate heading | P2 | Override file has multiple active ## <heading> with same text | "Keep one, remove duplicates. Last occurrence takes effect." |

Policy contradiction detection: Parse the project override's Auto-Trigger table for required check commands. Cross-reference against hook-enforced sentinels: if override omits /codex-review-fast for code changes or /codex-review-doc for .md changes, flag as P1.

Override drift detection: Read the <!-- Based on: auto-loop.md @ <hash> --> comment from the project file. Compare against git hash-object --no-filters .claude/rules/auto-loop.md | cut -c1-7. If different, the base has been updated since the override was authored. Uses blob hash for content-level comparison; accepts legacy commit-style hashes (any 7+ hex chars) during backward-compat transition.

S3: Settings Comp