grove-audit

# Grove Audit A fleet of 10 narrow-scoped subagents, each checking one thing well. Deterministic violations get auto-fixed and committed. Judgment calls get reported inline with `file:line` evidence. ## When to Activate - User says `/grove-audit`, `/grove-audit quick`, `/grove-audit standard`, or `/grove-audit full` - User asks for a comprehensive code review, compliance check, or codebase sweep - Before major merges or releases - After large refactors to catch regressions - During active development to sweep for legacy violations ## Modes | Mode | Scope | When to Use | |------|-------|-------------| | `quick` | Branch diff vs main | Iterative development, pre-commit check | | `standard` | Changed packages (git diff + affected deps) | Pre-merge, after refactors | | `full` | Entire codebase via Lumen + grep | Periodic sweeps, post-refactor cleanup, first-time audit | Default when no mode specified: infer from context. On a feature branch with changes → `standard`. On main with no changes → `full`. User specified a scope → use that. --- ## Protocol ``` SCOPE → DISCOVER → DISPATCH → COLLECT → FIX → REPORT ↓ ↓ ↓ ↓ ↓ ↓ Mode Files 10 agents Results Commit Inline ``` ### Phase 1: SCOPE Determine the audit mode and file set. **Quick mode:** ```bash git diff main...HEAD --name-only ``` **Standard mode:** ```bash git diff main...HEAD --name-only # Plus: identify affected packages from changed files # Include downstream consumers of changed libs ``` **Full mode:** - No file filtering — each lane agent discovers its own targets via Lumen semantic search + grep/glob - Each agent gets the full codebase as its search space ### Phase 2: DISCOVER For quick/standard modes, build the file list and pass it to each agent. For full mode, each agent does its own discovery — this is the key advantage of full sweeps. **Lumen is the primary discovery tool.** Each agent should query Lumen first to find files related to its concern, then use grep/glob to verify and catch stragglers. Agents have full access to all search tools — Lumen, grep, glob, find. No handicaps. ### Phase 3: DISPATCH Launch all 10 lane agents **in parallel** using the Agent tool. Each agent gets: 1. Its lane reference doc (from `references/`) 2. The mode and file scope (for quick/standard) or "full sweep" instruction 3. Clear output format expectations **The 10 Lanes:** | # | Lane | Agent Type | Reference | Auto-Fix? | |---|------|------------|-----------|-----------| | 1 | Barrel Imports | sonnet-coder | `references/barrel-imports.md` | Yes | | 2 | Icon Gateway | sonnet-coder | `references/icon-gateway.md` | Yes | | 3 | CSRF / Fetch Safety | sonnet-coder | `references/csrf-fetch.md` | Yes | | 4 | Accent Tokens | sonnet-coder | `references/accent-tokens.md` | Yes | | 5 | Signpost Compliance | sonnet-coder | `references/signpost.md` | No | | 6 | SDK Boundaries | sonnet-coder | `references/sdk-boundaries.md` | No | | 7 | Data Primacy | sonnet-coder | `references/data-primacy.md` | No | | 8 | Type Safety | sonnet-coder | `references/type-safety.md` | No | | 9 | Security (STRIDE) | opus-coder | `references/security.md` | No | | 10 | Test Coverage | sonnet-coder | `references/test-coverage.md` | No | **Why opus for security only:** STRIDE threat modeling requires deeper reasoning about attack surfaces and trust boundaries. The other lanes are pattern-matching tasks where sonnet excels. **Agent prompt template:** Each agent receives: 1. The full content of its reference doc (read it and include it in the prompt) 2. Mode + file scope 3. Instructions to use Lumen (`mcp__lumen__semantic_search`) as primary discovery, supplemented by grep/glob 4. Output format: structured findings list with `file:line`, severity, and fix description 5. For auto-fix lanes (1-4): instructions to make the fixes directly 6. For report lanes (5-10): read-only — return findings only ### Phase 4: COLLECT Wait for all 10 agents to complete. Gather their results. ### Phase 5: FIX For auto-fix lanes (1-4) that made changes: 1. Review the changes each agent made (verify they're correct) 2. Stage the fixed files 3. Commit with a descriptive message: ```bash git commit -m "$(cat <<'EOF' fix(audit): auto-fix [barrel imports|icon gateway|CSRF fetch|accent tokens] [Summary of what was fixed, e.g., "12 barrel imports converted to direct imports"] Co-Authored-By: Claude (Grove Agent) EOF )" ``` Group related fixes into logical commits — one per auto-fix lane that had changes. ### Phase 6: REPORT Compile the inline report from all 10 lanes. Format: ``` ================================================================================ GROVE AUDIT REPORT Mode: [quick|standard|full] | Files scanned: N | Date: YYYY-MM-DD ================================================================================ AUTO-FIXED (committed) -------------------------------------------------------------------------------- Lane 1 — Barrel Imports: N fixes applied Lane 2 — Icon Gateway: N fixes applied Lane 3 — CSRF / Fetch: N fixes applied Lane 4 — Accent Tokens: N fixes applied FINDINGS (requires manual attention) -------------------------------------------------------------------------------- [CRITICAL] ────────────────────────────────────── 1. [SDK Boundaries] libs/engine/src/lib/foo.ts:42 Raw env.DB.prepare() — use GroveDatabase from @autumnsgrove/infra ... [HIGH] ────────────────────────────────────────── ... [MEDIUM] ──────────────────────────────────────── ... [LOW] ─────────────────────────────────────────── ... SUMMARY -------------------------------------------------------------------------------- ┌──────────────────────────┬────────┬───────┬──────────────┐ │ Lane │ Status │ Found │ Fixed │ ├──────────────────────────┼────────┼───────┼──────────────┤ │ 1. Barrel Imports │ ✓ FIXED│ 12 │ 12 auto-fix │ │ 2. Icon Gateway │ ✓ CLEAN│ 0 │ — │ │ 3. CSRF / Fetch │ ✓ FIXED│ 3 │ 3 auto-fix │ │ 4. Accent Tokens │ ✓ CLEAN│ 0 │ — │ │ 5. Signpost Compliance │ ⚠ WARN │ 5 │ manual │ │ 6. SDK Boundaries │ ✗ FAIL │ 8 │ manual │ │ 7. Data Primacy │ ✓ PASS │ 0 │ — │ │ 8. Type Safety │ ⚠ WARN │ 2 │ manual │ │ 9. Security (STRIDE) │ ✓ PASS │ 0 │ — │ │ 10. Test Coverage │ ⚠ WARN │ 4 │ manual │ └──────────────────────────┴────────┴───────┴──────────────┘ Total: 34 findings | 15 auto-fixed | 19 manual | 0 critical ================================================================================ ``` --- ## Severity Classification | Severity | Meaning | Examples | |----------|---------|---------| | CRITICAL | Exploitable vulnerability or data leak | Raw env.DB without tenant scoping, adminMessage in client response, timing-unsafe secret comparison | | HIGH | Architectural violation that compounds | Raw SDK bypass (env.DB, env.BUCKET), duplicated data sources, missing rate limiting on auth | | MEDIUM | Pattern violation, not dangerous | Barrel imports, bare Lucide icons, hardcoded accent colors, missing Signpost errors | | LOW | Style/hygiene, no functional impact | Missing tests for utilities, Svelte 5 store usage, stale TODO comments | --- ## Agent Prompting Guide When dispatching each lane agent, read the corresponding reference file and include its full content in the agent prompt. Structure each prompt as: ``` You are a focused code auditor for the Grove/Lattice monorepo. Your ONLY job is: [lane description]. MODE: [quick|standard|full] SCOPE: [file list for quick/standard, or "full codebase" for full] RULES (from reference doc): [paste full reference content] DISCOVERY: - Use mcp__lumen__semantic_search as your primary discovery tool - Supplement with grep and glob for exact pattern matching - For full mode: discover your own targets, don't wait for a file list OUTPUT FORMAT: Return a structured list of findings: - file_path:line_number - severity: CRITICAL | HIGH | MEDIUM | LOW - description: what's wrong - fix: what to do instead (or "auto-fixed" for lanes 1-4) [For auto-fix lanes 1-4 only:] AUTO-FIX: You MUST fix deterministic violations directly using Edit. After fixing, report what you changed. [For report lanes 5-10:] READ-ONLY: Do NOT edit any files. Report findings only. ``` --- ## Suppression Comments Each lane respects specific suppression comments. These are documented in the lane references: | Lane | Suppression | Effect | |------|-------------|--------| | Barrel Imports | `// barrel-ok` | Skip this import | | Icon Gateway | `// prism-ok` | Allow bare Lucide import | | CSRF / Fetch | `// csrf-ok` | Allow bare fetch() | | Accent Tokens | `// accent-ok` | Allow hardcoded color | | SDK Boundaries | `// boundary-ok` | Allow raw binding | | Signpost | `// error-ok` | Allow bare throw/console | --- ## What Grove Audit Does NOT Do - **Run tests or type checks** — use `gw ci` for that - **Review prose or documentation** — code patterns only - **Judge style preferences** — "I'd name this differently" is not a finding - **Audit dependencies** — use `pnpm audit` for that - **Replace targeted skills** — hawk-survey for deep security, deer-sense for a11y, etc. --- ## Integration **Before audit:** Ensure Lumen index is fresh (`mcp__lumen__index_status`) **After audit:** Use the report to prioritize manual fixes **For auto-fixes:** Review the committed changes with `git diff HEAD~1` if desired