docs: mark wave 3 done; add wave 4 provider registry overhaul plan (#13, #21)

[AndresL230]

https://claude.ai/code/session_01K4tepaje9rv5Z2HX1hHU4u

Summary by CodeRabbit

• New Features

  • Aggregator now exposes overflow event tracking with a new overflowCount metric when bucket capacity limits are reached
  • Custom providers merge with built-in rules using specificity-based priority ordering (path length, host type, custom-wins-ties)

• Improvements

  • Unknown provider endpoints now normalize to "other" category instead of raw path values

• Documentation

  • Updated configuration guides to reflect new custom provider priority semantics
  • Added detailed implementation plan for provider registry overhaul

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements the complete Wave 4 plan for provider registry and aggregator correctness improvements: specificity-based rule ordering (preventing custom catch-alls from shadowing built-ins), normalized catch-all endpointCategory ("other" instead of raw pathname), ingest-time soft bucket cap with overflow bucketing and tracking, and coordinated documentation updates.

Changes

Wave 4 Implementation: Registry Specificity & Aggregator Cap

Layer / File(s)	Summary
Provider Registry Specificity Sorting & Catch-all Normalization src/core/provider-registry.ts, tests/provider-registry.test.ts	ProviderRegistry constructor now merges custom and built-in rules and sorts by specificity: pathPrefix presence/length, exact host over wildcard, custom wins ties. Twilio refinement returns "other" for unrecognized paths; generic catch-all defaults endpointCategory to "other" instead of raw pathname. Tests comprehensively verify rule ordering precedence, tie-breaking, and catch-all normalization across OpenAI, Anthropic, and Twilio.
Aggregator Ingest-Time Soft Cap with Overflow Bucketing src/core/aggregator.ts, tests/aggregator.test.ts	Aggregator enforces bucket cardinality synchronously during ingest() by redirecting events that would exceed maxBuckets into per-provider _overflow buckets. New _overflowCount counter tracks redirections; public overflowCount getter exposes the count, resetting to 0 after flush(). Tests verify correct aggregation of overflow metrics, normal ingestion for existing keys, and state reset.
Documentation & Planning: Wave 4 Roadmap & Specification Updates docs/superpowers/plans/2026-05-15-provider-registry-overhaul.md, docs/superpowers/roadmap-2026-05-13-issue-waves.md, README.md, CLAUDE.md	Complete Wave 4 plan document with step-by-step tasks, git workflow, expected test changes, and PR template. Roadmap updated: Wave 3 marked done with PR link, Wave 4 marked in-progress. README and CLAUDE.md reflect new specificity-based priority semantics (longer pathPrefix wins, custom wins ties) and catch-all normalization behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Provider registry: custom catch-alls shadow built-ins; cardinality leaks; soft bucket cap #13: This PR directly addresses the same code-level objectives: specificity-based rule ordering (preventing custom catch-alls from shadowing built-ins), normalized catch-all endpointCategory to "other" (preventing high-cardinality paths), and ingest-time soft bucket cap with overflow bucketing via _overflowCount mechanism.

Possibly related PRs

• recost-dev/middleware-node#34: Both PRs modify src/core/aggregator.ts and its flush() method; PR #34 changes WindowSummary timestamp/projectId construction while this PR adds overflow bucketing and overflowCount reset in the same code path.

Poem

🐰 Rules now sort by specificity's art,
Custom rules win ties, that's the smart part!
Overflow buckets catch what won't fit,
"Other" for unknowns—a cleaner bit!
Wave 4's done right, the registry's lit! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary changes: marking wave 3 as done and introducing wave 4's provider registry overhaul plan, with references to relevant issue numbers.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/fix-coderabbit-comments-4Xko6

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/superpowers/plans/2026-05-15-provider-registry-overhaul.md (1)

71-86: ⚡ Quick win

Make command examples repo-relative instead of machine-specific absolute paths.

The hardcoded /home/andresl/... paths make the plan non-reproducible for other contributors. Prefer $REPO_ROOT, git rev-parse --show-toplevel, or purely relative paths in all command snippets.

Also applies to: 97-99

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/superpowers/plans/2026-05-15-provider-registry-overhaul.md` around lines
71 - 86, Replace machine-specific absolute paths in the plan's command examples
(e.g., the "git -C /home/andresl/Projects/recost/middleware-node worktree list"
and the series of commands that cd into
"/home/andresl/Projects/recost/middleware-node" and ".claude/worktrees/...")
with repo-relative variants; use a variable like $REPO_ROOT, a one-liner to
compute the repo root (git rev-parse --show-toplevel), or purely relative paths
(./) and update the git worktree add and cd examples accordingly so contributors
can run the steps from any environment.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/superpowers/plans/2026-05-15-provider-registry-overhaul.md`:
- Around line 71-86: Replace machine-specific absolute paths in the plan's
command examples (e.g., the "git -C
/home/andresl/Projects/recost/middleware-node worktree list" and the series of
commands that cd into "/home/andresl/Projects/recost/middleware-node" and
".claude/worktrees/...") with repo-relative variants; use a variable like
$REPO_ROOT, a one-liner to compute the repo root (git rev-parse
--show-toplevel), or purely relative paths (./) and update the git worktree add
and cd examples accordingly so contributors can run the steps from any
environment.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cd7576d0-6e03-4784-bcdb-0bdf3573bd22

📥 Commits

Reviewing files that changed from the base of the PR and between c2ad485 and 3da79a7.

📒 Files selected for processing (8)

• CLAUDE.md
• README.md
• docs/superpowers/plans/2026-05-15-provider-registry-overhaul.md
• docs/superpowers/roadmap-2026-05-13-issue-waves.md
• src/core/aggregator.ts
• src/core/provider-registry.ts
• tests/aggregator.test.ts
• tests/provider-registry.test.ts