perf(benchmarks): P1 — establish a reproducible ADR Guard performance baseline #196

Child of P1 quality roadmap #193. Start implementation after PR #192 is merged or explicitly abandoned. Recheck current main first.

Problem / existing baseline

ADR Guard has bounded parsing, Git inventory, MCP search/listing and architecture-analysis contracts, but the existence of hard bounds is not evidence of latency, throughput or memory characteristics across realistic ADR sets. Optimize only after measuring.

Goal

Create a small, repeatable informational performance baseline for core ADR workflows that future changes can compare against, without production data, telemetry or fragile CI gates.

Scope / methodology

1. Inventory any existing benchmark scripts, relevant fixture generators, limits and release/build paths. Reuse them where appropriate.
2. Generate deterministic, version-controlled synthetic scenarios/seed for approximately 100, 500 and 900 ADRs, below the documented MCP 1,000-ADR ceiling. Include plausible statuses, relationships, sizes, and some representative errors; avoid accidental quadratic fixture generation.
3. Measure at minimum check and index using a packaged/release-built CLI in a disposable repository, without mutating source fixtures; optionally add an MCP list_adrs / search_adrs handshake suite only if straightforward and meaningfully comparable.
4. Record cold/warm behavior separately where practical, repeated-run timings (median and spread, optionally p95), peak memory where portable, scenario sizes, OS/CPU/RAM, .NET runtime, exact commit/tool version and commands. Separate setup/generation time from measured invocation time.
5. Keep the run manual/local or informational at first. Document runner noise and prevent automated fail/pass performance thresholds until a stable measured baseline exists.
6. Identify any observed bottlenecks, but open follow-up optimization issues only when supported by profiling and user-relevant evidence.

Acceptance criteria

• A deterministic generator or checked-in small fixture recipe is available and documented; no confidential or identifiable repository content.
• Reproduction works from a clean checkout with explicit build/install, seed and command steps; outputs carry source revision/environment metadata.
• Baseline measurements for 100, 500 and 900 ADRs, for check and index, include multiple samples, reported variability and (where feasible) peak process memory.
• Benchmarks isolate setup cost, avoid external network/provider calls and leave repository files clean.
• Findings clearly separate observed numbers from hypotheses and proposed optimizations.
• Scripts/tests and EN/PT-BR usage docs (if publicly exposed) are reviewed; no brittle mandatory CI threshold or release commitment.

Non-goals

No speculative algorithm rewrites, mandatory benchmark gating on shared runners, arbitrary latency SLAs, repository telemetry, AI-provider benchmarks, SaaS load testing or promises based on fabricated results.

Completion: A focused benchmark harness + documented real baseline, or an evidence-based no-change report if an equivalent reproducible harness already exists.