sinapse-ai 7.0.5 → 7.2.0

package/squads/claude-code-mastery/tasks/audit-settings.md

@@ -0,0 +1,206 @@
+# Task: Audit Claude Code Settings
+
+**Task ID:** CCM-CONFIG-002
+**Version:** 1.0.0
+**Command:** `*audit-settings`
+**Orchestrator:** Sigil (config-engineer)
+**Purpose:** Audit all active Claude Code settings layers for conflicts, redundancies, security gaps, and optimization opportunities by reading managed, project, local, and user configuration files.
+
+---
+
+## Overview
+
+```
+  +------------------+     +------------------+     +------------------+
+  | 1. Read All      | --> | 2. Check for     | --> | 3. Validate      |
+  |    Settings Files|     |    Conflicts     |     |    Deny Rules    |
+  +------------------+     +------------------+     +------------------+
+       |                                                    |
+       v                                                    v
+  +------------------+     +------------------+     +------------------+
+  | 4. Check         | --> | 5. Verify MCP    | --> | 6. Generate      |
+  |    Permission    |     |    Configs       |     |    Audit Report  |
+  |    Mode          |     |                  |     |                  |
+  +------------------+     +------------------+     +------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Working directory | Yes | Must contain .claude/ or be a project root |
+| check_managed | boolean | User parameter | No | Whether to check managed-settings.json (default: true) |
+
+---
+
+## Preconditions
+
+- Read access to all settings file locations
+- Claude Code installed on the system
+- At least one settings file must exist (.claude/settings.json minimum)
+
+---
+
+## Execution Phases
+
+### Phase 1: Read All Settings Files
+
+Locate and read each settings layer in precedence order:
+
+| Layer | Priority | Path | Scope |
+|-------|----------|------|-------|
+| 1 (Highest) | Managed | Platform-specific managed-settings.json | Organization |
+| 2 | CLI args | (Runtime only -- cannot be audited from files) | Session |
+| 3 | Local | .claude/settings.local.json | Personal/project |
+| 4 | Shared | .claude/settings.json | Team/project |
+| 5 (Lowest) | User | ~/.claude/settings.json | Personal/global |
+
+**Managed settings locations:**
+- macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`
+- Linux/WSL: `/etc/claude-code/managed-settings.json`
+- Windows: `C:\Program Files\ClaudeCode\managed-settings.json`
+
+For each file found:
+1. Parse JSON and validate structure
+2. Extract permission rules (deny, ask, allow arrays)
+3. Extract MCP server configurations
+4. Extract hook configurations
+5. Extract sandbox settings
+6. Record file modification timestamp
+
+### Phase 2: Check for Conflicts Between Scopes
+
+1. **Rule conflicts**: Same Tool(specifier) pattern appearing in different rule types across layers
+   - Example: `Bash(npm run *)` in local allow but shared deny
+   - Resolution: Deny always wins (merge + dedup behavior)
+   - Flag as WARNING if user likely intended allow
+2. **Mode conflicts**: Different defaultMode across layers
+   - Higher precedence layer wins
+   - Flag if local overrides shared (may confuse team)
+3. **Array merging analysis**: Permission arrays merge across scopes
+   - Identify duplicate rules (same pattern in multiple layers)
+   - Identify contradictions (pattern in both allow and deny)
+4. **Hook conflicts**: Same event with different configurations across layers
+   - Managed hooks cannot be overridden
+
+### Phase 3: Validate Deny Rules Cover Sensitive Paths
+
+Check that critical sensitive files are protected:
+
+**Required deny rules (flag if missing):**
+
+| Pattern | Protects | Severity if Missing |
+|---------|----------|---------------------|
+| `Read(./.env)` | Environment variables | CRITICAL |
+| `Read(./.env.*)` | Environment variants | CRITICAL |
+| `Read(./secrets/**)` | Secrets directory | HIGH |
+| `Read(./**/*.pem)` | SSL/TLS certificates | HIGH |
+| `Read(./**/*.key)` | Private keys | HIGH |
+| `Bash(rm -rf *)` | Destructive deletion | CRITICAL |
+| `Bash(curl * \| bash)` | Pipe-to-shell attacks | HIGH |
+
+**SINAPSE-specific deny rules (if .sinapse-ai/ exists):**
+
+| Pattern | Protects | Severity if Missing |
+|---------|----------|---------------------|
+| `Edit(.sinapse-ai/core/**)` | L1 Framework Core | HIGH |
+| `Edit(.sinapse-ai/constitution.md)` | Constitution | HIGH |
+| `Edit(bin/sinapse.js)` | CLI entry point | MEDIUM |
+
+### Phase 4: Check Permission Mode Appropriateness
+
+1. Determine effective permission mode (highest precedence layer wins)
+2. Assess appropriateness for the project:
+   - `bypassPermissions` on a team project -> CRITICAL warning
+   - `autoApprove` without deny rules -> HIGH warning
+   - `askAlways` with extensive allow rules -> INFO (could upgrade to acceptEdits)
+   - `acceptEdits` with proper deny rules -> GOOD (recommended setup)
+3. Check for enterprise lockdown:
+   - `disableBypassPermissionsMode` in managed settings
+   - `allowManagedPermissionRulesOnly` flag
+
+### Phase 5: Verify MCP Server Configurations
+
+1. Collect MCP configurations from all layers
+2. For each server:
+   - Verify command/URL is specified
+   - Check that environment variables reference env vars (not hardcoded values)
+   - Verify the server has a matching MCP permission rule (allow or ask)
+3. Check for enterprise restrictions:
+   - `allowManagedMcpServersOnly` flag
+   - `allowedMcpServers` / `deniedMcpServers` lists
+4. Flag any MCP servers not in the allow list
+
+### Phase 6: Generate Audit Report
+
+Compile all findings into a structured report.
+
+---
+
+## Output Format
+
+```markdown
+## Settings Audit Report
+
+**Project:** {project-name}
+**Date:** {YYYY-MM-DD}
+**Layers Found:** {count}/5
+
+### Layer Summary
+
+| Layer | File | Exists | Rules | Mode |
+|-------|------|--------|-------|------|
+| Managed | {path} | {Yes/No} | {N deny, N allow} | {mode or --} |
+| Local | .claude/settings.local.json | {Yes/No} | {N deny, N allow} | {mode or --} |
+| Shared | .claude/settings.json | {Yes/No} | {N deny, N allow} | {mode or --} |
+| User | ~/.claude/settings.json | {Yes/No} | {N deny, N allow} | {mode or --} |
+
+### Effective Configuration
+
+- **Permission mode:** {effective mode} (from {layer})
+- **Total deny rules:** {N} (after merge + dedup)
+- **Total allow rules:** {N} (after merge + dedup)
+- **MCP servers:** {N}
+- **Hooks:** {N} events configured
+
+### Findings
+
+| # | Severity | Finding | Layer(s) | Recommendation |
+|---|----------|---------|----------|----------------|
+| 1 | {CRITICAL/HIGH/MEDIUM/LOW/INFO} | {description} | {layer} | {fix} |
+
+### Security Gaps
+
+{List of missing deny rules that should be present}
+
+### Conflicts
+
+{List of rule conflicts between layers}
+
+### Optimization Opportunities
+
+{List of redundancies and improvements}
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** modify any settings files during the audit. This is a read-only diagnostic.
+- **NEVER** display the actual values of API keys, tokens, or secrets found in settings. Report presence only.
+- **NEVER** report a clean audit if critical deny rules (for .env, secrets) are missing. Always flag these.
+- **NEVER** recommend `bypassPermissions` mode as a fix for any issue.
+- **NEVER** skip the managed-settings.json check in enterprise environments -- it is the highest authority layer.
+
+---
+
+## Completion Criteria
+
+- [ ] All accessible settings layers read and parsed
+- [ ] Conflicts between layers identified and documented
+- [ ] Sensitive path deny rules validated (missing rules flagged)
+- [ ] Permission mode assessed for appropriateness
+- [ ] MCP server configurations verified
+- [ ] Audit report generated with severity-ranked findings

package/squads/claude-code-mastery/tasks/audit-setup.md

@@ -0,0 +1,225 @@
+# Task: Audit Claude Code Setup
+
+**Task ID:** CCM-CHIEF-002
+**Version:** 1.0.0
+**Command:** `*audit`
+**Orchestrator:** Orion (claude-mastery-chief)
+**Purpose:** Perform a comprehensive audit of the Claude Code setup in the current project, generating a scored report with actionable recommendations.
+
+---
+
+## Overview
+
+```
+  +-------------------+     +-------------------+     +-------------------+
+  | 1. Directory      | --> | 2. Settings       | --> | 3. CLAUDE.md      |
+  |    Structure      |     |    Validation     |     |    Analysis       |
+  +-------------------+     +-------------------+     +-------------------+
+       |                          |                          |
+       v                          v                          v
+  +-------------------+     +-------------------+     +-------------------+
+  | 4. Hooks          | --> | 5. MCP Servers    | --> | 6. Rules          |
+  |    Inventory      |     |    Inventory      |     |    Coverage       |
+  +-------------------+     +-------------------+     +-------------------+
+       |                          |                          |
+       v                          v                          v
+  +-------------------+     +-------------------+     +-------------------+
+  | 7. Agents         | --> | 8. Score &        | --> |    REPORT         |
+  |    Definitions    |     |    Recommendations|     |                   |
+  +-------------------+     +-------------------+     +-------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Working directory | Yes | Must contain a .claude/ directory or be a valid project root |
+| depth | string | User parameter | No | `quick` (checks 1-3 only) or `full` (default, all 8 checks) |
+
+---
+
+## Preconditions
+
+- Working directory is a project root (has package.json, .git/, or similar project markers)
+- Read access to .claude/ directory and its subdirectories
+- Read access to project configuration files
+
+---
+
+## Execution Phases
+
+### Phase 1: Check .claude/ Directory Structure
+
+Verify the presence and structure of the .claude/ directory:
+
+```
+.claude/
+  settings.json          # [REQUIRED] Project-shared settings
+  settings.local.json    # [OPTIONAL] Personal local settings (gitignored)
+  CLAUDE.md              # [OPTIONAL] Project instructions (alt: ./CLAUDE.md)
+  rules/                 # [RECOMMENDED] Conditional rules directory
+  agents/                # [OPTIONAL] Custom subagent definitions
+  commands/              # [OPTIONAL] Custom slash commands
+  skills/                # [OPTIONAL] Skill definitions with SKILL.md
+  mcp.json               # [OPTIONAL] MCP server configuration
+```
+
+Score each item:
+- REQUIRED missing = -20 points
+- RECOMMENDED missing = -10 points
+- OPTIONAL missing = informational only
+
+### Phase 2: Validate settings.json Schema
+
+1. Read `.claude/settings.json` and parse as JSON
+2. Validate the schema structure:
+   - `permissions` object exists with `allow`, `deny`, and/or `ask` arrays
+   - `permissions.defaultMode` is a valid mode (askAlways, acceptEdits, autoApprove)
+   - Permission rules use valid Tool(specifier) syntax
+   - No contradicting rules (same pattern in both allow and deny)
+3. Check `.claude/settings.local.json` if present (same validation)
+4. Check `~/.claude/settings.json` for user-level settings
+5. Flag any conflicts between settings layers
+
+### Phase 3: Check CLAUDE.md Quality
+
+1. Locate CLAUDE.md (check: `./CLAUDE.md`, `./.claude/CLAUDE.md`)
+2. Measure line count (target: under 200 lines)
+3. Check structure:
+   - Has markdown headers for organization
+   - Uses bullet points for instructions
+   - Contains concrete, verifiable instructions (not vague)
+4. Check for @imports usage
+5. Check for SINAPSE-managed sections (if SINAPSE project)
+6. Flag if over 200 lines without @imports or .claude/rules/ usage
+
+### Phase 4: List Configured Hooks
+
+1. Read hooks configuration from settings.json (`hooks` key)
+2. For each hook event, document:
+   - Event name (PreToolUse, PostToolUse, etc.)
+   - Hook type (command, http, prompt, agent)
+   - Matcher pattern (if applicable)
+   - Timeout value
+3. Check for common recommended hooks:
+   - PreToolUse for Bash command validation
+   - PreCompact for context preservation
+   - Stop for session cleanup
+4. If SINAPSE project: check for Python hooks in `.sinapse-ai/monitor/hooks/`
+
+### Phase 5: List MCP Servers
+
+1. Read MCP configuration from `.claude/mcp.json` or settings.json `mcpServers`
+2. For each server, document:
+   - Server name
+   - Transport type (stdio, http, sse)
+   - Command or URL
+   - Environment variables (names only, not values)
+3. Check for common recommended servers (context7, exa, browser)
+4. Verify no secrets are hardcoded in committed configuration files
+
+### Phase 6: Check .claude/rules/ Coverage
+
+1. List all files in `.claude/rules/`
+2. For each rule file:
+   - Check for `paths:` frontmatter (conditional loading)
+   - Document the glob patterns if present
+   - Measure line count
+3. Assess coverage:
+   - Are there rules for major directories (src/, tests/, docs/)?
+   - Are rules using conditional loading where appropriate?
+   - Are there any unconditional rules that should be conditional?
+
+### Phase 7: Check .claude/agents/ Definitions
+
+1. List all files in `.claude/agents/`
+2. For each agent file:
+   - Verify YAML frontmatter is present and valid
+   - Check for required fields (name, description, tools)
+   - Measure definition size
+3. Check for potential issues:
+   - Agents without tool restrictions (too permissive)
+   - Agents with overlapping responsibilities
+   - Missing agent definitions referenced elsewhere
+
+### Phase 8: Generate Audit Report
+
+Calculate the final score and generate recommendations.
+
+**Scoring System (100 points max):**
+
+| Check | Max Points | Criteria |
+|-------|-----------|----------|
+| Directory structure | 15 | Required files present, recommended dirs exist |
+| Settings validation | 20 | Valid schema, deny-first rules, no conflicts |
+| CLAUDE.md quality | 20 | Under 200 lines, well-structured, uses imports |
+| Hooks coverage | 15 | At least PreToolUse configured, proper timeouts |
+| MCP servers | 10 | Configured and no hardcoded secrets |
+| Rules coverage | 10 | Conditional loading used, major dirs covered |
+| Agent definitions | 10 | Valid frontmatter, scoped tools |
+
+---
+
+## Output Format
+
+```markdown
+## Claude Code Setup Audit Report
+
+**Project:** {project-name}
+**Date:** {YYYY-MM-DD}
+**Depth:** {quick | full}
+
+### Score: {N}/100 ({GRADE})
+
+| Grade | Range | Meaning |
+|-------|-------|---------|
+| A | 90-100 | Excellent -- production-ready configuration |
+| B | 75-89 | Good -- minor improvements recommended |
+| C | 60-74 | Fair -- several gaps to address |
+| D | 40-59 | Poor -- significant configuration work needed |
+| F | 0-39 | Critical -- minimal or broken setup |
+
+### Check Results
+
+| # | Check | Status | Score | Notes |
+|---|-------|--------|-------|-------|
+| 1 | Directory Structure | {PASS/WARN/FAIL} | {N}/15 | {notes} |
+| 2 | Settings Validation | {PASS/WARN/FAIL} | {N}/20 | {notes} |
+| 3 | CLAUDE.md Quality | {PASS/WARN/FAIL} | {N}/20 | {notes} |
+| 4 | Hooks Coverage | {PASS/WARN/FAIL} | {N}/15 | {notes} |
+| 5 | MCP Servers | {PASS/WARN/FAIL} | {N}/10 | {notes} |
+| 6 | Rules Coverage | {PASS/WARN/FAIL} | {N}/10 | {notes} |
+| 7 | Agent Definitions | {PASS/WARN/FAIL} | {N}/10 | {notes} |
+
+### Recommendations (Priority Order)
+
+1. **[{severity}]** {recommendation} -- {specialist to consult}
+2. ...
+
+### Quick Wins
+
+- {Easy improvement that can be done immediately}
+- ...
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** modify any files during the audit. This is a read-only diagnostic task.
+- **NEVER** expose secret values (API keys, tokens) found in configuration files. Report their presence but mask values.
+- **NEVER** score above 50 if settings.json is missing or invalid -- it is the foundation of Claude Code configuration.
+- **NEVER** skip Phase 2 (settings validation) even in quick mode -- it is the most critical check.
+
+---
+
+## Completion Criteria
+
+- [ ] All applicable phases executed (quick: 1-3, full: 1-8)
+- [ ] Numeric score calculated with breakdown
+- [ ] Grade letter assigned
+- [ ] Recommendations listed in priority order
+- [ ] No configuration files modified during audit
+- [ ] Report generated in specified markdown format