feat: add settings audit route to devkit-sync (#139)

Add route 12 (audit) that checks ~/.claude/settings.json for
redundant specific permissions subsumed by broad wildcards.
Reports findings and optionally cleans up the file with backup.

Closes #134

Co-authored-by: Claude <noreply@anthropic.com>

Author: HerbHall

README.md

@@ -95,6 +95,7 @@ This backs up any existing files in `~/.claude/`, creates symlinks for all share
 | `/devkit-sync update` | Check version and upgrade to latest release |
 | `/devkit-sync verify` | Check if DevKit updates reached all active projects |
 | `/devkit-sync new-project` | Scaffold a new project with templates and profile |
+| `/devkit-sync audit` | Check for redundant permissions in settings.json |
 
 ### Multi-machine workflow
 

claude/skills/devkit-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devkit-sync
-description: Manual sync operations for DevKit multi-machine synchronization. Status, push, pull, init, diff, unlink, promote, update, and new-project scaffolding.
+description: Manual sync operations for DevKit multi-machine synchronization. Status, push, pull, init, diff, unlink, promote, update, new-project scaffolding, and settings audit.
 user_invocable: true
 ---
 
@@ -32,6 +32,7 @@ What sync operation do you need?
 9. **Update** -- Check version and upgrade to a specific release or latest
 10. **Verify** -- Check if DevKit updates reached all active projects
 11. **New project** -- Scaffold a new project with DevKit templates and profile
+12. **Audit settings** -- Check for redundant permissions in settings.json
 
 Or just type your question about DevKit sync.
 </intake>
@@ -50,6 +51,7 @@ Or just type your question about DevKit sync.
 | 9, "update", "upgrade", "version", "release" | workflows/update.md |
 | 10, "verify", "propagation", "check projects", "reach" | workflows/verify.md |
 | 11, "new-project", "scaffold", "create project", "new" | workflows/new-project.md |
+| 12, "audit", "cleanup", "settings audit", "redundant", "permissions" | workflows/audit-settings.md |
 
 **After reading the workflow, follow it exactly.**
 </routing>

claude/skills/devkit-sync/workflows/audit-settings.md

@@ -0,0 +1,93 @@
+# Audit Settings
+
+Check `~/.claude/settings.json` for redundant permissions that are subsumed by broad wildcards. Optionally clean up the file.
+
+## Steps
+
+### 1. Read the user-level settings file
+
+```bash
+cat ~/.claude/settings.json
+```
+
+If the file does not exist, report "No user-level settings.json found" and stop.
+
+### 2. Identify broad wildcards
+
+Parse the `permissions.allow` array. A **broad wildcard** is an entry with no parentheses -- it matches all invocations of that tool.
+
+Examples of broad wildcards:
+
+- `"Bash"` -- matches all Bash commands
+- `"Read"` -- matches all Read operations
+- `"mcp__*"` -- matches all MCP tools
+
+### 3. Find redundant specific entries
+
+For each broad wildcard found, identify specific entries it subsumes:
+
+- `"Bash"` subsumes `"Bash(git add:*)"`, `"Bash(gh pr merge 30 --squash --admin)"`, etc.
+- `"Read"` subsumes `"Read(d:/DevSpace/**)"`, etc.
+- `"mcp__*"` subsumes `"mcp__memory__create_entities"`, `"mcp__MCP_DOCKER__mcp-find"`, etc.
+
+An entry is redundant if a broader entry in the same array already covers it.
+
+### 4. Report findings
+
+Display a summary:
+
+```text
+Settings audit for ~/.claude/settings.json
+
+Broad wildcards found: N
+  - Bash
+  - Read
+  - Edit
+  ...
+
+Redundant specific entries: N
+  - Bash(git add:*)          (subsumed by Bash)
+  - Bash(gh pr merge 30 --squash --admin)  (subsumed by Bash)
+  - Read(d:/DevSpace/**)     (subsumed by Read)
+  ...
+
+Deny rules (preserved): N
+  - Bash(rm -rf /)
+```
+
+If zero redundant entries found, report "Settings are clean -- no redundant entries" and stop.
+
+### 5. Ask user to confirm cleanup
+
+Present the list of entries that would be removed. Explain:
+
+- Broad wildcards are kept
+- Deny rules are never removed
+- Non-redundant specific entries are kept
+- Only entries fully covered by a broad wildcard are removed
+
+Ask: "Remove N redundant entries? (This modifies ~/.claude/settings.json)"
+
+### 6. Clean up if confirmed
+
+Read the current file, remove redundant entries from `permissions.allow`, and write back.
+
+Use `Read` to get the current content, modify the JSON in a code block, and `Write` the cleaned version.
+
+**Preserve:**
+
+- All `permissions.deny` entries (never touch deny rules)
+- All entries NOT subsumed by a broad wildcard
+- All non-permission fields (`hooks`, `enabledPlugins`, `autoUpdatesChannel`, etc.)
+- JSON formatting (2-space indent)
+
+### 7. Report results
+
+Show before/after entry count and the cleaned file path.
+
+## Edge cases
+
+- **No broad wildcards**: Report "No broad wildcards found. Specific entries are all necessary." and stop.
+- **Mixed tool formats**: `"Bash(git:*)"` is subsumed by `"Bash"` but NOT by `"Bash(gh:*)"`. Only exact tool name match counts.
+- **settings.local.json**: This workflow only audits the user-level `~/.claude/settings.json`. Project-level and local files are not touched.
+- **Backup**: Before writing, create a backup at `~/.claude/settings.json.bak`.