ai-readiness Phase 3 — long-tail uplift

[jon-devlapaz]

The long-tail items that round out the AI-readiness uplift. Each is independent, low-risk, and drip-fed; no single item gates the others.

See AI_READINESS.md for the full rubric.

Checklist

• Add ruff baseline config (criterion B3 reinforcement). Pair with mypy.ini since pyproject.toml is unavailable (Vercel build generates and removes it per scripts/preflight-deploy.sh). Use ruff.toml instead. Start with the same lenient floor as mypy: green on current code, tighten per-rule over time. Wire into scripts/doctor.sh and .github/workflows/preflight.yml.
• Push Python type-hint coverage to ≥80% annotated returns (criterion B1). Current baseline: 232 annotated returns; denominator needed. Drip-fed; tighten disallow_untyped_defs = True per-module via [mypy-<module>] overrides as coverage grows. Target the most-touched modules first.
• Freshness audit of AGENTS.md and UBIQUITOUS_LANGUAGE.md (criterion C1, C2). Pick 5 architectural claims from each doc; grep to verify each still matches current code. Fix or remove stale ones. Add a quarterly reminder. Decay is the silent failure mode.
• Wire .code-review-graph/graph.db refresh into CI (criterion E2). The graph last refreshed 2026-05-12; if it goes months stale, agents that consult it get false caller/callee data. Trigger refresh on push to main/dev, or nightly. Use existing mcp__crg__* infrastructure.

Acceptance

• ruff.toml exists; ruff check . exits 0 in CI.
• Mypy coverage report shows ≥80% return-annotated functions outside tests/ and scripts/.
• AGENTS.md / UBIQUITOUS_LANGUAGE.md freshness check has a documented ritual.
• .code-review-graph/graph.db mtime is never older than 7 days on main.

Refs

• Rubric: AI_READINESS.md (criteria B1, B3, C1, C2, E2).
• Vercel constraint on pyproject.toml: mypy.ini header comment, lines 5–8.