config-audit

What this skill does

# config-audit

> Audits the repo's Claude configuration against `docs/config-guidelines.md`. Read-only.
> Produces `audit-report.md` consumed by `config-refactor`.

**Triggers**: /config-audit, audit config, audit claude config, review configuration, configuration health check

---

## Process

### Step 0 — Detect execution context

Determine which mode to run in (per Principle 13):

- **Global mode** — CWD is the `claude-config` repo. Detected when ALL of:
  - `install.sh` exists at CWD root.
  - `skills/_shared/` exists at CWD root.
  - OR basename of CWD matches `claude-config` or `agent-config`.
- **Project mode** — CWD is any other directory containing a `CLAUDE.md` at root.
- **No-config mode** — CWD has no `CLAUDE.md`. Stop and print:
  `No CLAUDE.md found in this directory. Run project-claude-init (future) or create one manually before auditing.`

Record the detected mode and proceed. The mode controls Step 1 (guidelines source)
and Step 2 (target file enumeration).

### Step 1 — Locate guidelines

**Global mode** — read `docs/config-guidelines.md` from CWD. This file is the spec.

**Project mode** — read `~/.claude/docs/config-guidelines.md` (the deployed global
spec) as the read-only baseline. The project's own `CLAUDE.md` is the audit
target, not a spec source.

If the guidelines file does not exist in either mode:

- Emit CRITICAL "Guidelines file missing — cannot audit. In global mode, create
  `docs/config-guidelines.md`. In project mode, run `install.sh` from the
  `claude-config` repo on this machine."
- Stop. Do not produce a partial report.

### Step 2 — Enumerate target files

**Global mode** — audit only these targets, in this order:

1. `CLAUDE.md` (root)
2. `output-styles/*.md`
3. `skills/*/SKILL.md`
4. `hooks/*` (read for cross-checks against `CLAUDE.md`, do NOT audit hook internals)
5. `settings.json` and `settings.local.json` (cross-checks only — duplicated rules, hook
   declarations matching files in `hooks/`)
6. `mcp/*.json` (existence only)
7. `keybindings.json` (existence only)
8. `~/.claude/` orphan scan (Principle 12 whitelists).

Do not audit anything else. Out of scope: `docs/` (except guidelines), `memory/`, `agents/`,
test fixtures, README.

**Project mode** — audit only these targets:

1. `CLAUDE.md` at CWD root (the project's own).
2. `.claude/skills/*/SKILL.md` if present (project-local skills).
3. `.claude/settings.json` and `.claude/settings.local.json` if present.

Out of scope in project mode: `~/.claude/` runtime directories, the global
`CLAUDE.md`, anything outside the project root. The global layer is read-only
reference for duplication checks (Principle 13 anti-duplication rule).

### Step 3 — Run check matrix

Apply every check below. For each finding, record:

- `severity`: CRITICAL | WARNING | SUGGESTION
- `file`: absolute path
- `line` (if applicable)
- `rule`: the principle name from guidelines (e.g. "Principle 4 — Token budget")
- `finding`: one-sentence description
- `fix_hint`: one-sentence suggested action

#### Token-budget checks (Principle 4)

For each target file:

- Count lines.
- Compare against the file's soft and hard limit from the guidelines table.
- Over hard limit → CRITICAL.
- Over soft limit → WARNING.

#### Separation-of-concerns checks (Principle 2)

Scan `CLAUDE.md` for:

- Sections that match orchestrator/agent-specific scope (e.g. "Bind this to … agent or
  rule only", explicit sub-agent contracts, SDD model assignments). If found and no
  `agents/<name>.md` exists, raise WARNING "Move scoped section to `agents/`".
- A manual skill catalog (table listing 5+ skills with descriptions). If found, raise
  WARNING "Remove manual skill catalog — harness auto-discovers skills (Principle 2)".

Scan each `output-styles/*.md` for:

- Bullets that begin with verbs like "Verify", "Never agree", "Propose alternatives",
  "Explain why with evidence". These restate `CLAUDE.md` behavior rules → WARNING.
- Prescriptive technical opinions ("X over Y", "always use X", "concepts > code"). Raise
  WARNING with rule "Principle 7 — Output styles are tone, not behavior".

#### Anti-duplication checks (Principle 3)

Build a normalized fingerprint of each rule line in `CLAUDE.md` and each rule line in
output styles and skills. A "rule line" is a top-level bullet inside a `## Rules`-like
section.

For each pair that exceeds 70% token overlap:

- If one of the two files is a hook and the other is `CLAUDE.md` → CRITICAL "Rule
  duplicated between hook and CLAUDE.md (Principle 3.1)".
- If `CLAUDE.md` and an output-style → WARNING "Rule duplicated (Principle 3.2)".
- If two skills → SUGGESTION "Extract shared rule into `skills/_shared/`".

#### OS-correctness checks (Principle 5)

Scan `CLAUDE.md` for these substrings (case-insensitive): `brew`, `apt-get`, `cat `,
`find `, `sed `, `grep ` (as Bash command, not the Grep tool), `ls `.

For each hit:

- If the line is not prefixed by an OS-specific marker ("On Linux/macOS only:", "WSL:", etc.)
  → WARNING "OS-specific tooling assumed without declaration (Principle 5)".

#### Engram-ownership checks (Principle 9)

Scan `CLAUDE.md` for headings or bullets that look like the engram protocol payload:

- "PROACTIVE SAVE TRIGGERS"
- "SESSION START PROTOCOL"
- "SESSION CLOSE PROTOCOL"
- "AFTER COMPACTION"
- `mem_save` format template (a multi-bullet block describing `title`, `type`, `content`)

If found AND the same content is also injected by a `SessionStart` hook → CRITICAL
"Engram protocol duplicated between hook and CLAUDE.md (Principle 9)".

If found AND no hook injects it → WARNING "Engram protocol in CLAUDE.md but no hook
injects it; verify ownership".

#### Force-read-inline table checks (Principle 10)

Find the "Skills — Force-read inline" table (or any table at root of `CLAUDE.md` listing
skills with paths). Check:

- More than 4 entries → WARNING "Force-read table exceeds 4 entries".
- Title is "Skills catalog", "Auto-load skills", or any wording that implies full catalog
  → WARNING "Rename to 'Skills — Force-read inline'".
- Any path that does not exist on disk → CRITICAL "Force-read entry points to missing
  file".

#### Skill format checks (Principle 8)

For each `skills/*/SKILL.md`:

- Missing YAML frontmatter → CRITICAL.
- Missing `name`, `description`, or `format` in frontmatter → CRITICAL.
- `format` value not in {procedural, reference, anti-pattern} → CRITICAL.
- Missing `**Triggers**:` line in body → WARNING.
- Section contract for declared format not met (see `docs/format-types.md`) → WARNING.

#### Two-layer duplication checks (Principle 13, project mode only)

For each rule line in the project `CLAUDE.md`:

- Normalize and fingerprint as in the anti-duplication check.
- Compare against rules in the global `~/.claude/CLAUDE.md`.
- Token overlap > 70% AND no `## Overrides global` block declares the rule →
  CRITICAL "Project CLAUDE.md restates global rule without override declaration
  (Principle 13)".
- If a project rule contradicts a global rule (semantic opposite) and no override
  block is declared → CRITICAL "Project CLAUDE.md contradicts global without
  override (Principle 13)".

In global mode this check is skipped (only one layer present).

#### Orphan checks in `~/.claude/` (Principle 12, global mode only)

List the entries directly under `~/.claude/`. For each entry:

- If the name is in the known-runtime whitelist (Principle 12) → ignore.
- If the name is in the known-deployed whitelist → ignore.
- Otherwise → WARNING "Orphan in ~/.claude/: <name>. Investigate origin or remove."

Do not recurse into runtime directories. The check is one level deep.

#### Cross-reference checks (general)

- For every absolute path mentioned in `CLAUDE.md` (e.g. `~/.claude/skills/foo/SKILL.md`),
  verify the corresponding repo path exists. If not → SUGGESTION "Dead reference".
- For every skill name referenced inside another `SKILL.md` body, verify it exists in
  `skills/`. If not → SUGGESTION "Reference to missing skill".

### Step 4 — Write the r