docs: define provider presentation precedence

[steipete]

Summary

• define one pure status-item presentation policy for provider pins beside the merged icon
• define a three-choice merged-icon source without mutating menu, account, or Overview selection
• bound frontmost-app matching to privacy-safe native bundle metadata; defer terminal inference
• record migration, lifecycle, edge cases, model/controller tests, Tahoe proof, and six owner decisions
• include a synthetic redacted current-state screenshot

Issue disposition

Decision document for #1167 and #780. This PR intentionally does not close either issue or change runtime behavior. Implementation remains held for owner signoff on the decision table.

The design also avoids a second provider-content filter, preventing overlap with #1781 and preserving the existing Overview subset.

Validation

• swift test --filter 'StatusMenuOverviewScrollTests|MenuCardViewRecyclingTests' — 30 tests passed
• make check — passed; 0 SwiftFormat files and 0 SwiftLint violations
• make test — passed
• autoreview — clean; no accepted/actionable findings
• live baseline: packaged exact-main build on macOS Tahoe 26.5.2; merged item visible; 300 smooth down-ticks plus 300 up-ticks completed; exact process remained responsive and inspectable

Product recommendation

Approve the six defaults together: additive pins, persistent merged item, one source picker, collapsed-icon-only focus effect, native-app MVP, and separate off-by-default terminal follow-up.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 1, 2026, 5:41 AM ET / 09:41 UTC.

Summary
The PR adds a provider presentation precedence design document and a synthetic redacted screenshot for merged-icon behavior.

Reproducibility: not applicable. This PR is a design document and does not report a runtime bug. Current source inspection confirms the baseline merged-icon behavior described by the doc.

Review metrics: 1 noteworthy metric.

• Docs-only surface: 2 files added, 240 markdown lines, 0 runtime files. This confines review to design accuracy and artifact quality rather than app behavior.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] The document asks maintainers to accept six product defaults before implementation; merging it should be treated as direction-setting, not as a runtime fix.
• [P1] The linked provider-pinning and focus-aware icon issues remain open, so implementation still needs follow-up PRs after signoff.

Maintainer options:

1. Decide the mitigation before merge
   Keep this draft open until the owner accepts or revises the spec, then use it as the bounded design source for separate implementation PRs.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] The remaining action is owner product approval of the documented defaults, not an automated code repair.

Security
Cleared: The diff is docs-only and does not change code execution, dependencies, CI, signing, secrets, or provider auth paths.

Review details

Best possible solution:

Keep this draft open until the owner accepts or revises the spec, then use it as the bounded design source for separate implementation PRs.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR is a design document and does not report a runtime bug. Current source inspection confirms the baseline merged-icon behavior described by the doc.

Is this the best way to solve the issue?

Yes for a decision artifact: the PR records precedence, migration, privacy boundaries, and acceptance criteria without changing runtime behavior before signoff.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 735a91ac3c25.

Label changes

Label changes:

• add P3: This is a low-risk docs/design PR for future provider presentation behavior.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: This is a low-risk docs/design PR for future provider presentation behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read in full; its docs/testing guidance and owner-sensitive review stance were applied to this docs-only PR. (AGENTS.md:1, 735a91ac3c25)
• Diff surface: The PR adds one markdown spec under docs/superpowers/specs and one PNG under docs/screenshots, with no runtime code, tests, workflows, dependencies, or signing changes. (docs/superpowers/specs/2026-07-01-provider-presentation-and-focus-design.md:1, 4ebc55fef042)
• Current merged-mode lifecycle: Current main removes provider status items when shouldMergeIcons is true, matching the spec's baseline that behavior is currently binary merged-vs-split. (Sources/CodexBar/StatusItemController.swift:769, 735a91ac3c25)
• Current unified icon precedence: Current main resolves the merged icon from highest usage, Overview selection, selected provider, enabled providers, then Codex fallback, with no focus-aware branch. (Sources/CodexBar/StatusItemController+Animation.swift:996, 735a91ac3c25)
• Related feature comments: The linked issue comments for Allow selected providers to stay as separate menu bar icons in Merge Icons mode #1167 and Feature Request: Automatically switch provider based on window focus when "Merge Icons" is enabled #780 both point to this PR as a decision-ready design while explicitly leaving implementation and approval open.
• Adjacent provider-selection PR: Scope most-used provider to Overview selection #1781 remains open on product hold for Overview-scoped highest-usage behavior, and this PR explicitly avoids adding a second provider-content filter that would overlap it. (be4c748db5f5)

Likely related people:

• Peter Steinberger: Current blame for the central merged-icon lifecycle/resolver lines points to the v0.37.2 main commit, and history shows prior merge-icon status-item lifecycle fixes in the same files. (role: recent area contributor; confidence: high; commits: f380287041b8, 6534c6d9c26d, 30218e29c971; files: Sources/CodexBar/StatusItemController.swift, Sources/CodexBar/StatusItemController+Animation.swift)
• Behnam M: Symbol history shows the single unified icon model was introduced in the commit that consolidated status items into one unified icon. (role: original unified icon contributor; confidence: medium; commits: 157802bced26; files: Sources/CodexBar/StatusItemController.swift, Sources/CodexBar/StatusItemController+Animation.swift)
• Phillip Cohen: Commit history shows the existing Show highest-usage provider menu-bar feature was added in this area, which the new merged-icon source picker would replace or subsume. (role: adjacent feature introducer; confidence: medium; commits: ffaf32b7ce7d, 3c41e8ecbedf, 75e6c98d5040; files: Sources/CodexBar/StatusItemController+Animation.swift, Sources/CodexBar/UsageStore.swift)
• Ratul Sarna: History shows Overview selection persistence and reconciliation work that overlaps the spec's requirement to avoid changing Overview membership or adding a second provider-content subset. (role: adjacent Overview contributor; confidence: medium; commits: 549f7583156c, 856cbcad82f6, a64539b4d464; files: Sources/CodexBar/SettingsStore+Defaults.swift, Sources/CodexBar/PreferencesDisplayPane.swift, Sources/CodexBar/StatusItemController+Menu.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.