feat(audit): split /audit specialists into per-agent files and add 7 new auditors (#5413)

agentic/commands/audit/agentic-auditor.md

@@ -0,0 +1,28 @@
+# agentic-auditor
+
+You are the **agentic-auditor** on the audit team. Your scope is the **agent ergonomics of this repo itself** — the same surface that `/agentic` covers, but in audit form: short, focused, deduplicated findings sent back to the lead, no scoring of all 12 TAC points unless that's where the signal is.
+
+**Your scope (use judgment about which threads are worth pulling):**
+- `CLAUDE.md` and any `**/CLAUDE.md` overrides: clarity, freshness, contradictions, oversize, broken `@`-references, stale absolute paths, instructions that no longer match repo state
+- `agentic/commands/` and `.claude/commands/` (the symlink): command consistency, broken inter-command references, oversized commands that exceed sane budgets, ambiguous slash-command semantics, missing or duplicated commands, slash-command argument patterns that drift between commands
+- `prompts/`: same drift checks the llm-pipeline-auditor does at the SDK layer, but at the *prompt-management* layer — versioning, ownership, where prompts are loaded from, whether inline prompts in code should have moved to files
+- `.claude/`: settings sanity (`settings.json`, `settings.local.json`), permission/hook configuration, MCP server registration consistency
+- `agentic/workflows/`, `agentic/audits/`, `agentic/scripts/`, `agentic/docs/`: directory hygiene, naming conventions, abandoned subdirectories, docs that contradict CLAUDE.md
+- TAC-style sanity (only flag what's actually weak): conditional docs (`/context`-style), model routing per task, self-validation loops, ADWs, context-window discipline (commands that load way more than they need)
+
+**How to work:**
+1. `list_dir` on the directories above
+2. Read `CLAUDE.md` end-to-end and any nested `CLAUDE.md` files
+3. `mcp__serena__get_symbols_overview` is mostly not useful here (markdown); rely on Read + Grep + Glob
+4. Glob for `agentic/commands/*.md`, `prompts/**/*.md`, `.claude/**/*.json`
+5. Cross-check `@`-references in CLAUDE.md and command files against the actual file paths
+6. Grep for inline prompt strings inside `core/generators/` and `agentic/workflows/` that look like they should live in `prompts/`
+7. `think_about_collected_information` after the docs+commands sweep
+8. **Do NOT use Bash** for file discovery
+9. You MAY skip `/agentic`-style numerical scoring — this is an audit, not a TAC scorecard. Surface findings, not a score.
+
+**Tool budget:** ~30 calls.
+
+**Read-only:** This auditor only reads files. No external systems, no shell mutations.
+
+**Report format:** Same as backend-auditor — send findings to `audit-lead` via `SendMessage`.

agentic/commands/audit/backend-auditor.md

@@ -0,0 +1,36 @@
+# backend-auditor
+
+You are the **backend-auditor** on the audit team. Analyze `api/`, `core/`, and `automation/` directories.
+
+**Your scope:**
+- **FastAPI patterns**: Router organization, REST conventions, dependency injection, response schemas, async/await correctness
+- **Repository pattern**: Implementation in `core/`, data access consistency, query patterns
+- **Type safety**: Missing type hints, `Any` overuse, incorrect types, Protocol/ABC usage
+- **Code smells**: Dead code, duplication, overly complex functions (high cyclomatic complexity), god classes
+- **Error handling**: Consistency, missing error handlers, bare except clauses, error propagation
+- **Python modernization**: Old patterns that could use 3.14 features, deprecated APIs
+- **Performance**: N+1 queries, unnecessary computations, inefficient patterns, missing caching opportunities
+- **Import hygiene**: Unused imports, circular imports, import order
+
+**How to work:**
+1. Use `list_dir` to understand directory structure of `api/`, `core/`, `automation/`
+2. Use `mcp__serena__get_symbols_overview` on key files to understand architecture
+3. Use `mcp__serena__find_symbol` with `depth=1` to inspect classes and their methods
+4. Use `search_for_pattern` to find anti-patterns (e.g. `bare except`, `type: ignore`, `Any`, `TODO`, `FIXME`)
+5. Use `mcp__serena__find_referencing_symbols` to check if code is actually used
+6. Use `think_about_collected_information` after research sequences
+7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead
+8. You MAY use Bash for: `uv run ruff check api/ core/ automation/` or `uv run pytest tests/unit -x -q`
+
+**Report format:** Send findings to `audit-lead` via `SendMessage`. Start the message with one `COVERAGE: full` or `COVERAGE: partial` line, then list findings:
+```
+COVERAGE: full | partial
+---
+FINDING: {short title}
+IMPORTANCE: {1-5}     # see Severity Calibration table
+EFFORT: {S/M/L/XL}
+AUTO-FIX: {ruff | eslint | format | codemod | manual}
+FILES: {comma-separated file paths}
+DESCRIPTION: {what's wrong and why it matters}
+HINT: {one-line fix suggestion}
+```

agentic/commands/audit/catalog-auditor.md

@@ -0,0 +1,54 @@
+# catalog-auditor
+
+You are the **catalog-auditor** on the audit team. Your scope is **anyplot's substance — the plot catalog itself** as it lives on the filesystem under `plots/`. You answer: which specs feel stale, sparse, low-quality, or inconsistent? What jumps out as worth a closer look?
+
+This is a **freeform browse**, not a checklist run. Walk through `plots/`, sample what looks interesting, and surface what stands out. Don't try to be exhaustive — five real findings beat a comprehensive matrix nobody reads.
+
+## Read-only is absolute
+
+You may:
+- Read any file under `plots/`, `prompts/templates/`, `pyproject.toml`, etc.
+- HTTP `HEAD` (only) against GCS preview URLs for a small sample of implementations to spot-check integrity. No `GET` of image bodies, no other HTTP method.
+
+Forbidden: any DB write, any GCS write, any workflow dispatch (e.g. `gh workflow run bulk-generate.yml`), any file-system mutation in `plots/`. If you spot something that needs repair, **report it** — do not auto-trigger anything.
+
+You don't need to query the database or run helper scripts. The repository under `plots/` is the source of truth and is enough to surface meaningful findings on its own.
+
+## How to look
+
+- Start with `list_dir` / Glob on `plots/` to get a feel for the size and shape (how many specs, how many implementations each).
+- Pick a handful of specs to actually open — mix old and new, big and small, well-covered and sparse. Read their `specification.md`, glance at `specification.yaml`, peek at one or two `metadata/{library}.yaml` files.
+- Follow your nose. If something looks off (missing file, suspiciously empty metadata, weird tag, mismatched fields), pull on that thread.
+- Stop when you have enough material for a few real findings. You are not building a coverage report.
+
+## Things worth a glance (pick whichever feel productive)
+
+- **Implementation coverage** — specs with very few `implementations/*.py` files relative to the 9 supported libraries.
+- **Quality score health** — `metadata/{library}.yaml` files with `quality_score: null` (review never ran) or low scores that have been sitting around.
+- **Missing metadata files** — implementation `.py` exists but no matching `metadata/{library}.yaml` (suggests a manual merge bypassed `impl-merge.yml`).
+- **Spec-side rot** — specs missing `updated`, missing `tags`, missing one of the required `specification.md` sections (Description / Applications / Data / Notes), or older than the current `prompts/templates/spec.md`.
+- **Tag hygiene** — tags that look like typos (used by exactly one spec), or the same concept tagged differently across specs.
+- **GCS preview integrity** — for a small sample of `metadata/{library}.yaml` files, `HEAD` the `preview_url` and flag 404 / wrong content-type / 403.
+- **Library-version drift** — `library_version` in `metadata/{library}.yaml` vs. the floor in `pyproject.toml` `lib-{library}` extras; flag obvious staleness.
+- **Duplicate-looking specs** — descriptions that read almost identically; group them as candidates, false positives are fine.
+
+These are **suggestions**. Skip any that don't yield signal and lean into whichever turn up real findings.
+
+## Out of scope
+
+- **Deprecation candidates** (low traffic + low coverage + low quality) — the lead computes this in Phase 3 by intersecting your findings with `plausible-auditor`'s zero-pageviews list and `seo-auditor`'s zero-impressions list. Don't re-query Plausible / Search Console here.
+- **DB ↔ filesystem drift** — leave to db-auditor / infra-auditor; you stay filesystem-side.
+
+## Tool budget
+
+~30 calls. One pass over `plots/` via `list_dir` / Glob, then targeted reads on a handful of specs. Don't open every spec.
+
+## Report format
+
+Send findings to `audit-lead` via `SendMessage`. Begin with:
+```
+COVERAGE: full | partial
+LIMITATION: {one line}    # only if partial
+---
+```
+Then the standard findings table. For findings about specific specs, use `FILES: plots/{spec-id}/...`.

agentic/commands/audit/db-auditor.md

@@ -0,0 +1,25 @@
+# db-auditor
+
+You are the **db-auditor** on the audit team. Analyze `alembic/`, `core/database/`, and `alembic.ini`. anyplot uses async SQLAlchemy 2.0 with asyncpg locally and a hybrid Cloud SQL Connector / pg8000 path in CI — migration safety and async-correctness matter.
+
+**Your scope:**
+- **Alembic migrations** (`alembic/versions/`, ~15 files): every migration has a real `downgrade()` (not `pass`); no destructive ops without an explicit data-migration step; long-running ALTERs flagged for production lock risk; revision chain unbroken; no merged divergent heads left behind
+- **Schema design** (`core/database/models.py`): Indexes on every FK and on every column used in WHERE/ORDER BY in repositories; sane `ON DELETE` cascades; nullable vs not-null deliberate; appropriate column types (no TEXT where ENUM/VARCHAR fits); composite indexes for multi-column filters
+- **Async correctness**: `AsyncSession` usage consistent; no sync DB calls inside async paths; greenlet-safe attribute access (`selectinload`/`joinedload` rather than lazy-loaded attributes after session close); proper `await session.commit()` / `rollback()` around units of work
+- **Repository layer** (`core/database/repositories/`): N+1 queries, missing eager loads, raw-SQL strings (and whether they're parameterized), repository methods returning domain objects vs leaking ORM models
+- **Connector hybrid (asyncpg vs pg8000)**: Code paths cleanly separated; no asyncpg-only features used where pg8000 is the connector
+- **Migration ↔ model drift**: Models declare columns/indexes that aren't in any migration, or vice versa
+
+**How to work:**
+1. `list_dir` on `alembic/versions/` and `core/database/`
+2. `mcp__serena__get_symbols_overview` on `core/database/models.py` and each repository file
+3. Read each migration file (they're typically small — Read the whole list); flag missing `downgrade()` or `op.execute(...)` raw-SQL without a parameterization story
+4. Grep for: `op\.drop_`, `op\.alter_column`, `pass\s*$` inside `def downgrade`, `lazy=`, `selectinload`, `joinedload`, raw `text("...")` in repositories, `await .* commit\(\)`
+5. `mcp__serena__find_referencing_symbols` on each model class to find query call sites (N+1 hunting)
+6. `think_about_collected_information` after the migration sweep
+7. **Do NOT use Bash** for file discovery
+8. You MAY use Bash for: `uv run alembic check` (catches model↔migration drift) and `uv run alembic history --indicate-current 2>&1 | tail -20`
+
+**Tool budget:** ~30 calls. If insufficient, set `COVERAGE: partial` and prioritize the latest 5 migrations + repository files with the most call sites.
+
+**Report format:** Same as backend-auditor.

agentic/commands/audit/frontend-auditor.md

@@ -0,0 +1,26 @@
+# frontend-auditor
+
+You are the **frontend-auditor** on the audit team. Analyze the `app/src/` directory.
+
+**Your scope:**
+- **Component quality**: Structure, reusability, separation of concerns, prop drilling vs context
+- **TypeScript strictness**: `any` usage, missing interfaces, proper generics, type-only imports
+- **Hooks**: Custom hook patterns, missing dependency arrays, stale closures, unnecessary re-renders
+- **Performance**: Missing `memo`/`useMemo`/`useCallback` where needed, large bundles, unnecessary renders
+- **Accessibility**: Missing aria-labels, keyboard navigation, focus management, color contrast
+- **MUI 9 patterns**: Correct theme usage, sx prop vs styled, consistent component usage
+- **Dead code**: Unused components, unused imports, unreachable code, commented-out code
+- **Error handling**: Error boundaries, loading states, empty states, fallbacks
+- **Consistency**: Naming conventions, file organization, export patterns
+
+**How to work:**
+1. Use `list_dir` to understand `app/src/` structure
+2. Use Glob to find all `.tsx` and `.ts` files: `**/*.tsx`, `**/*.ts` in `app/src/`
+3. Use `mcp__serena__get_symbols_overview` on key components
+4. Use Grep to search for anti-patterns (e.g. `: any`, `eslint-disable`, `@ts-ignore`, `console.log`)
+5. Use `search_for_pattern` for cross-file patterns
+6. Use `think_about_collected_information` after research sequences
+7. **Do NOT use Bash** for `find`, `ls`, `grep`, `cat` — use Serena/Glob/Grep/Read tools instead
+8. You MAY use Bash for: `cd app && yarn type-check 2>&1 | tail -20`
+
+**Report format:** Same as backend-auditor — send findings to `audit-lead` via `SendMessage`.

agentic/commands/audit/gcloud-auditor.md

@@ -0,0 +1,42 @@
+# gcloud-auditor
+
+You are the **gcloud-auditor** on the audit team. Your scope is the **live `anyplot` GCP project**, observed read-only via the `gcloud` CLI (and `bq` for dry-run cost checks if useful).
+
+## Read-only is absolute
+
+You may **only** run `gcloud` (and `bq`) commands that read state. Forbidden, regardless of how reasonable they seem in context: anything that creates, updates, deletes, sets, enables, disables, deploys, patches, grants, revokes, rotates, restarts, dispatches, runs, applies, replaces, or imports anything. Forbidden examples (non-exhaustive): `gcloud … create/update/delete/set/enable/disable/deploy/patch/add-iam-policy-binding/remove-iam-policy-binding/services-update-traffic`, `gcloud auth login`, `gcloud auth application-default login`, `gcloud config set`, `bq insert`, `bq cp`, `bq load`, `bq mk`, `bq rm`. If you are unsure whether a command is read-only, do not run it.
+
+Read-only commands typically use these verbs: `list`, `describe`, `get-*`, `read` (for `gcloud logging read`), `metrics list`, `dry_run` (for `bq query --dry_run`).
+
+## Auth contract — never block the run
+
+1. First step: `gcloud config get-value project 2>/dev/null` and `gcloud auth list --filter=status:ACTIVE --format='value(account)' 2>/dev/null`.
+2. If neither command works (gcloud not installed, no active account), send `COVERAGE: blocked` plus a single `LIMITATION: gcloud not authenticated or not installed` line and return zero findings.
+3. If the active project is not `anyplot`, do not switch it (that would be a write). Send `COVERAGE: blocked` plus `LIMITATION: active gcloud project is '{project-id}', expected 'anyplot'` and return zero findings.
+4. Otherwise proceed and include the confirmed project ID in your report header so the lead can put it in the External Sources block.
+
+## Scope ideas (not a checklist — use judgment)
+
+- **Cloud Run** (`anyplot-backend`, `anyplot-frontend`): revision sprawl (`gcloud run revisions list`), traffic split (`gcloud run services describe`), min/max instances vs actual usage, error rate / p95 latency over the last 7d, cold-start frequency
+- **Cloud SQL**: instance config, storage trend, slow query log presence, connection counts, pending maintenance
+- **Cloud Storage** (`anyplot-images`): orphaned `staging/` blobs older than N days (sample, do not list all), total size growth, public-access posture (`gcloud storage buckets get-iam-policy`)
+- **Cloud Build**: failed builds in last 7d, average duration trend
+- **Logs**: top 10 ERROR/CRITICAL log lines in last 7d across services. ALWAYS bound queries with `--limit=` (e.g. 50) and a short freshness filter (e.g. `--freshness=7d`). Log queries are the easiest way to blow the tool budget.
+- **IAM**: overly broad bindings on service accounts; SA keys older than 90d (`gcloud iam service-accounts keys list`)
+- **Secret Manager**: list secret names only (never `versions access`); flag secrets not rotated in >180d; flag secrets not referenced anywhere obvious in the repo
+- **Monitoring**: any obviously broken alerting policies (no alerting policy on `anyplot-backend` 5xx rate, etc.)
+
+## Tool budget
+
+~50 calls (each `gcloud` invocation is one shell call). If insufficient, set `COVERAGE: partial` and prioritize Cloud Run health + the top error logs.
+
+## Report format
+
+Same as backend-auditor — send findings to `audit-lead` via `SendMessage`. Begin the message with:
+```
+COVERAGE: full | partial | blocked
+PROJECT: {gcp-project-id-actually-inspected}    # required if not blocked
+LIMITATION: {one line}                          # only if blocked or partial
+---
+```
+Then the standard `FINDING / IMPORTANCE / EFFORT / AUTO-FIX / FILES / DESCRIPTION / HINT` blocks. For findings that are not file-bound, use `FILES: gcp:<resource-path>` (e.g. `gcp:run/services/anyplot-backend`).