docs(adr): add Architecture Decision Records for v3.x structural changes

[jptosso]

Summary

Introduces docs/adr/ — 54 MADR-3.0 records documenting every
structural change landed across the v3.x release train, from v3.0.0
(2023-05-31) through v3.7.0 (2026-04-06) plus two unreleased post-v3.7.0
changes on main.

Each ADR links to its PR and any linked issue, lists deciders,
summarises the decision, and quotes the specific reviewer / author
comments that drove it — or explicitly notes "No substantive technical
discussion recorded" when the change merged without architectural
debate.

What's in scope

Structural PRs only — new directives, operators, actions,
transformations, variables, collections, subsystems, breaking API
changes, algorithmic performance shifts, and internal refactors that
change shape.

Not in scope: bugfixes, doc-only / CI / chore changes, Renovate &
Dependabot bumps.

Numbers at a glance

Category	Count	Share
Feature — net-new capability / API / subsystem	17	31 %
Parity — ModSecurity / RFC / framework / platform compatibility	23	43 %
Perf — algorithmic or allocation change, same semantics	10	19 %
Refactor — internal shape or public-surface cleanup	4	7 %
Sum of upkeep (Parity + Perf + Refactor)	37	69 %

≈ 1 in 3 structural changes in v3.x is a Feature; the other 2 are
upkeep. Parity — mostly catching up to ModSecurity's documented
surface — dominates the upkeep share.

Silent architecture: 14 / 54 ADRs (26 %) shipped without substantive
on-GitHub technical discussion (only approvals and / or bot comments);
the PR body or out-of-band threads (OWASP Slack) were the decision
record. Those ADRs use the explicit "No substantive technical
discussion recorded" marker rather than inventing dialogue.

Per-release timeline (sketch)

• v3.0.x (2023) — parity-heavy release stabilisation. First Feature
  weight (HTTPS audit log, MatchedRule.Log()) lands in v3.0.3.
• v3.1 → v3.3 (2024–early 2025) — mostly ModSecurity-parity
  variables / transformations. OCSF audit log and transaction
  context.Context are the standout Features.
• v3.4.0 (March 2026) — the biggest single release by structural
  count: 18 ADRs, carrying the 12-month backlog between v3.3.3 and
  v3.4.0. Syslog writer, rule observer callback, WAFWithRules, JSON
  depth limit, ANTLR4 parser behind a build tag.
• v3.5 → v3.7 (spring 2026) — pivot to Perf. Memoize default-on,
  WAF.Close(), @rx prefilter, transformation cache, Aho-Corasick →
  bitmap. Features are mostly APIs that enable the Perf work.
• Post-v3.7 main — 100 % Perf so far.

Format

ADRs follow MADR 3.0 with a mandatory Technical Discussion section.
Every ADR contains:

• direct GitHub permalink to the PR (and to linked issues where they
  exist),
• at least one quoted comment with a permalink — or the explicit
  "No substantive technical discussion recorded" marker,
• a participants roster (authors, reviewers, commenters),
• Context / Drivers / Options / Outcome / Consequences sections.

See docs/adr/0000-template.md for the
canonical form and docs/adr/README.md for the
full chronological index with a Cat. column (F / P / ⚡ / R) per
entry.

Why draft

Opening as draft so the maintainer team can:

1. spot-check classification calls on individual ADRs (especially the
   Feature-vs-Parity line),
2. flag any structural PR that was missed, or any ADR that is on a
   non-structural PR,
3. correct attribution / participants lists.

Test plan

• ls docs/adr/ | wc -l → 56 (54 ADRs + 0000-template.md +
  README.md).
• Spot-check 5 random ADRs: verify quoted lines appear verbatim in
  the linked PR / issue threads.
• grep -L "https://github.com/corazawaf/coraza/pull/" docs/adr/[0-9]*.md
  returns empty.
• grep -L "^## Technical Discussion" docs/adr/[0-9]*.md returns
  empty.
• Every ADR contains either a blockquote with a permalink or the
  explicit "No substantive technical discussion recorded" marker.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e72bf253-d11c-44a9-ac05-dd5213cac4eb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/adr-v3-structural

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}