chore: implement audit quick wins and architectural doc updates (#5506)

This PR addresses several quick wins identified in the recent audit:
- Fix legacy Python 2 except syntax in scripts and plots
- Update Claude model name to valid Anthropic identifier
- Sync architectural docs and agentic commands with modular router
structure
- Complete Web Vitals reporting (added FCP and TTFB)
- Fix typo in agentic command filename (dokument.md -> document.md)
- Use settings.claude_max_tokens in scripts to avoid hardcoded limits
- Optimize model routing in plan.py (Phase 1 uses small model)

Author: MarkusNeusinger

agentic/audits/2026-04-27-all.md

@@ -0,0 +1,67 @@
+# Audit Report: anyplot
+
+**Date:** 2026-04-27 | **Scope:** all | **Mode:** full
+**Health Score:** 30 | **Baseline:** ruff: 0 issues, format: formatted
+**Auditors:** 15 ran (backend, frontend, infra, quality, llm-pipeline, db, security, observability, agentic, gcloud, github, plausible, pagespeed, seo, catalog) | **Findings:** 22 | **Auto-fixable:** 3/22
+**External sources:**
+- GCP project: pyplots (gcloud-auditor - BLOCKED: project mismatch)
+- Plausible site: anyplot.ai (plausible-auditor - BLOCKED: credentials missing)
+- Search Console mode: structural-only | freshness: 2026-04-27 (seo-auditor)
+- GitHub: MarkusNeusinger / anyplot (github-auditor)
+- Catalog DB rows: 327 specs (catalog-auditor)
+
+## Summary
+The anyplot repository exhibits high technical excellence in its frontend and core AI generation workflows but suffers from critical infrastructure and baseline safety issues. The use of experimental Python 3.14, a major command injection vulnerability in CI/CD, and broken Python syntax in automation scripts significantly compromise production readiness.
+
+**Note:** Several critical and high-severity findings listed below (Python syntax errors, invalid model name, documentation drift, and missing Web Vitals) were addressed in PR #5506.
+
+## Quick Wins (Importance ≥4 & Effort=S)
+| # | Finding | Auto-fix | Files | Hint |
+|---|---------|----------|-------|------|
+| 1 | SyntaxError: Python 2 style 'except' blocks | ruff | `automation/scripts/sync_to_postgres.py`, `plots/stereonet-equal-area/implementations/python/highcharts.py` | Change `except E1, E2:` to `except (E1, E2):` |
+| 2 | Critical Versioning Risk: Python 3.14 | manual | `pyproject.toml`, Dockerfiles, `.github/workflows/*.yml` | Downgrade to stable Python 3.12 or 3.13 |
+| 3 | Invalid Claude Model Name | manual | `core/config.py` | Change `claude-sonnet-4-6` to `claude-3-5-sonnet-20240620` |
+| 4 | Stale Agentic Commands / Docs | manual | `agentic/commands/*.md`, `docs/reference/*.md` | Update structure references to modular routers |
+
+## Critical (Importance 5)
+| # | Finding | Effort | Auto-fix | Files | Hint |
+|---|---------|--------|----------|-------|------|
+| 1 | Command Injection in Workflows | M | manual | `.github/workflows/spec-create.yml` | Use unquoted heredoc `<<'EOF'` to prevent shell expansion of untrusted content |
+| 2 | SyntaxError in Python scripts | S | ruff | `automation/scripts/sync_to_postgres.py`, `plots/.../highcharts.py` | Fix Python 2 style except blocks |
+| 3 | Experimental Python 3.14 in Production | S | manual | `pyproject.toml`, `Dockerfile`, `.github/workflows/` | Downgrade to stable Python (3.12/3.13) |
+| 4 | Missing Branch Protection on `main` | S | manual | `gh:branches/main` | Enable required reviews and status checks via GH settings |
+
+## High (Importance 4)
+| # | Finding | Effort | Auto-fix | Files | Hint |
+|---|---------|--------|----------|-------|------|
+| 1 | Model-migration Drift (Missing Indexes) | M | manual | `alembic/versions/`, `core/database/models.py` | Run `alembic revision --autogenerate` to sync indexes |
+| 2 | Invalid Model Name `claude-sonnet-4-6` | S | manual | `core/config.py` | Use valid Anthropic model identifier |
+| 3 | Missing Prompt Caching | M | manual | `.github/workflows/`, `prompts/` | Add `cache_control: {"type": "ephemeral"}` to static guides |
+| 4 | Missing Web Vitals (FCP/TTFB) | S | manual | `app/src/analytics/reportWebVitals.ts` | Instrument missing Core Web Vitals |
+| 5 | Missing LLM Observability | M | manual | `scripts/evaluate-plot.py`, `scripts/upgrade_specs_ai.py` | Log token counts and latency for all LLM calls |
+| 6 | Lack of Request/Correlation IDs | M | manual | `api/main.py`, `core/config.py` | Add Request-ID middleware for async log correlation |
+| 7 | Type-checking Bypass (mypy ignore_errors) | M | manual | `pyproject.toml` | Remove `ignore_errors = true` for core modules |
+| 8 | Architectural Drift in Documentation | S | manual | `docs/reference/`, `README.md` | Update docs to reflect modular router structure |
+
+## Medium (Importance 3)
+| # | Finding | Effort | Auto-fix | Files | Hint |
+|---|---------|--------|----------|-------|------|
+| 1 | Scalability Bottleneck in Filtering | L | manual | `api/routers/plots.py` | Move filtering logic from in-memory to SQL |
+| 2 | God Test File `test_routers.py` | M | manual | `tests/unit/api/test_routers.py` | Split large test file into modular router tests |
+| 3 | Implementation Gaps in Catalog | XL | manual | `plots/` | Generate missing implementations for newer specs |
+| 4 | Label Fragmentation | S | manual | `gh:labels` | Consolidate quality score labels |
+| 5 | Agentic Command Typo (`dokument.md`) | S | codemod | `agentic/commands/dokument.md` | Rename to `document.md` and update references |
+
+## Positive Patterns (Importance 1)
+- **Exceptional Frontend Quality**: React 19, zero `any` usage, robust accessibility, and smart error boundaries.
+- **Secure Prompt Design**: Hallucination mitigation via grounding examples and strict role definitions.
+- **Strong Test Coverage**: 1:1 test mapping for automation scripts ensuring reliability of the generation pipeline.
+- **Conditional Context Loading**: `agentic/commands/context.md` efficiently manages context window.
+
+## Statistics
+- Total: 22 | Critical: 4, High: 8, Medium: 6, Low: 0, Positive: 4
+- Effort: S 10, M 8, L 2, XL 2
+- Auto-fix: ruff 1, codemod 1, manual 20
+- By Auditor: backend 5, frontend 0, infra 2, quality 2, llm 3, db 1, security 1, obs 4, agentic 2, gcloud 0, github 1, plausible 0, pagespeed 0, seo 0, catalog 1
+- Cross-validation: 13 reviewed, 0 dropped, 0 downgraded
+- Coverage: 8 auditors complete, 4 partial, 3 blocked (gcloud, plausible, pagespeed)