docs(Popover): compact component contract

[cixzhang]

Status: benchmark blocked

This draft is not ready for approval. A two-attempt reviewer benchmark at frozen authority 701fd39b found that the compact Popover contract reduced contract context by 44.6%, but did not preserve review quality on #5675:

• not every compact attempt recovered the below-400 ineffective-cap blocker;
• objective precision fell from 1.00 under the current contract to 0.83;
• both attempts classified the case as an objective finding instead of the settled/no-reask boundary;
• reviewer output grew from 1,443 to 1,640 estimated tokens.

The compact record remains semantically faithful as documentation, but it fails the stricter question that now matters: whether it helps reviewers identify the right decisions and blockers. Keep this PR draft until the compact structure restores that signal and passes the repeatable benchmark.

Why

The current Popover contract repeats evidence and shared-system rules, making its durable promises harder to scan and audit. This documentation-only change keeps the settled contract intact while making it substantially smaller.

What

• preserves the exact metadata, authority, approval, ownership boundaries, public concepts and defaults, normative behavior and accessibility, theming target compatibility and refinement model, relationships, decision rulings, and pending implementation/evidence gaps
• replaces duplicated shared policy with links to canonical owners while keeping the unlanded AST-009 proposal explicitly non-authoritative
• reduces the contract from 421 to 190 lines without changing its semantic scope

Risk

Documentation-only compaction. No runtime, public API, consumer-facing documentation, target, behavior, migration, or release-status change.

The reviewer benchmark identifies a separate risk: semantic parity does not guarantee equal review-decision quality.

Testing

• pnpm exec prettier --check packages/core/src/Popover/Popover.spec.md
• pnpm check:knowledge --base origin/main
• pnpm exec vitest run packages/core/src/Popover/Popover.test.tsx packages/core/src/hooks/useFocusTrap.test.tsx (60 tests)
• pnpm check:repo
• public-hygiene review: no internal links, identifiers, paths, or hostnames
• private repeatable reviewer benchmark: failed strict gate on objective recall, precision, label accuracy, and output-size parity

No Changeset: this compacts an existing contract without changing a published package or consumer-facing promise.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 2, 2026 1:53am UTC