Document MiMo reserve evidence contract

[steipete]

Summary

• accepts a fail-closed MiMo reserve evidence contract
• keeps windowMinutes and reserve/deficit text absent until an authoritative start, duration, cadence, or token-reset contract exists
• rejects inference from 30/31-day proximity, plan validity, price, or plan-name text
• leaves runtime behavior unchanged and keeps Implement reserve for Xiaomi MiMo plan #1205 open for evidence plus a separately reviewed implementation

Evidence

• Xiaomi publicly offers monthly and annual token plans: https://platform.xiaomimimo.com/token-plan
• the redacted live response documented on Implement reserve for Xiaomi MiMo plan #1205 has usage percent and period end, but no start, duration, or cadence discriminator
• closed PR feat: Add reserve/pace indicator for Xiaomi MiMo token plan #1310 demonstrated why period-end proximity misclassifies annual plans
• PR Fix MiMo Firefox session cookie import #1565 changes MiMo cookie import, not cadence data

Verification

• make check
• documentation links: 144 local links clean
• SwiftFormat: 0/1237 files require formatting
• SwiftLint: 0 violations in 1236 files

Docs only; no UI or runtime behavior changed.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 3, 2026, 4:27 PM ET / 20:27 UTC.

Summary
Adds a docs/superpowers decision brief defining a fail-closed MiMo reserve evidence contract while leaving runtime behavior unchanged.

Reproducibility: not applicable. this is a docs-only decision brief, not a runtime bug report. Source inspection confirms the documented current behavior without live MiMo provider validation.

Review metrics: 1 noteworthy metric.

• Changed surface: 1 docs file added, +100/-0. The patch records product guidance without changing runtime code, so review should focus on evidence and maintainer acceptance.

Root-cause cluster
Relationship: partial_overlap
Canonical: #1205
Summary: This PR documents the product/evidence contract for the canonical open MiMo reserve request, while the runtime implementation remains unmerged and separately tracked.

Members:

• canonical: Implement reserve for Xiaomi MiMo plan #1205 - The issue remains the canonical open request for MiMo reserve/deficit display.
• superseded: feat: Add reserve/pace indicator for Xiaomi MiMo token plan #1310 - The earlier implementation was closed unmerged because monthly-window inference was unsafe for annual plans.
• adjacent_distinct: Fix MiMo Firefox session cookie import #1565 - That open PR changes MiMo Firefox cookie import and does not supply cadence or reserve-window evidence.
• partial_overlap: [codex] Add Codex pace headroom hint #1789 - That open PR touches shared pace presentation for Codex headroom, but it does not solve MiMo cadence evidence.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
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:

• [P1] Approve or revise the fail-closed MiMo reserve contract before merge.

Risk before merge

• [P1] Merging this docs PR makes the fail-closed MiMo reserve contract repository guidance, so maintainers should explicitly accept that Implement reserve for Xiaomi MiMo plan #1205 remains blocked until authoritative cadence or period evidence exists.

Maintainer options:

1. Approve or revise the evidence contract (recommended)
   Before merge, maintainers should either accept the fail-closed contract as written or revise the brief to the authorized MiMo reserve policy.
2. Merge as explicit owner guidance
   Maintainers can intentionally land the brief knowing it keeps MiMo reserve text disabled until upstream evidence satisfies the documented contract.
3. Pause for annual-plan proof
   Keep the PR open if maintainers want redacted annual-plan payloads or an authoritative token-credit reset source before accepting repository guidance.

Next step before merge

• [P2] Maintainer review is the next action because the remaining question is acceptance of product guidance, not an automated code or docs repair.

Security
Cleared: The diff is docs-only and introduces no code execution, dependency, secret-handling, or supply-chain surface.

Review details

Best possible solution:

Merge the decision brief once maintainers accept the fail-closed contract, and keep runtime MiMo reserve implementation under #1205 until authoritative period evidence exists.

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

Not applicable: this is a docs-only decision brief, not a runtime bug report. Source inspection confirms the documented current behavior without live MiMo provider validation.

Is this the best way to solve the issue?

Yes, documenting the fail-closed evidence contract is a narrow maintainable step while MiMo cadence data is missing. Runtime reserve work should stay separate and use authoritative evidence or continue to fail closed.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 692da32ecbbb.

Label changes

Label justifications:

• P3: This is a low-risk docs/product-guidance PR for provider reserve behavior, not an urgent runtime regression.
• merge-risk: 🚨 other: The non-obvious merge risk is accepting a MiMo reserve evidence contract as repository guidance before maintainers intentionally approve that policy.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• 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 fully; its guidance to prefer focused source/docs review and avoid live provider or Keychain-prompting validation shaped this docs-only review. (AGENTS.md:1, 692da32ecbbb)
• PR adds one decision brief: The PR head adds a 100-line decision brief whose status is accepted fail-closed and not implemented, with the final decision explicitly keeping runtime MiMo reserve behavior unchanged. (docs/superpowers/specs/2026-07-01-mimo-reserve-decision.md:10, 42ba910000d5)
• Current MiMo mapping is durationless: Current main maps MiMo token usage to a primary RateWindow with used percent and planPeriodEnd, but leaves windowMinutes nil. (Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift:62, 692da32ecbbb)
• Shared pace fails closed without duration: Current main returns nil for generic non-Codex weekly pace when windowMinutes is absent, matching the proposed contract that MiMo should not fabricate reserve/deficit text. (Sources/CodexBar/UsageStore+HistoricalPace.swift:29, 692da32ecbbb)
• Decision brief is not already on main or latest release: The new decision brief is absent from current main and from v0.38.0, so this PR still contains unique docs work. (docs/superpowers/specs/2026-07-01-mimo-reserve-decision.md, 692da32ecbbb)
• Canonical issue remains open: The related MiMo reserve issue includes live API analysis showing usage percent and currentPeriodEnd but no period start, duration, billing cycle, reset cycle, or cadence discriminator.

Likely related people:

• steipete: Authored the decision brief and the owner comment on the related MiMo reserve issue, and current history shows recent MiMo/pace area activity under this name. (role: owner-decision holder and recent area contributor; confidence: high; commits: 42ba910000d5, 913b1a6412b5, 2f92ee97e46e; files: docs/superpowers/specs/2026-07-01-mimo-reserve-decision.md, Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift, Sources/CodexBar/UsageStore+HistoricalPace.swift)
• Deb Pramanik: Authored the merged commit that added MiMo token-plan usage tracking, including snapshot mapping, fetcher, docs, and tests referenced by this brief. (role: introduced MiMo token-plan behavior; confidence: high; commits: f9a2918afcf1; files: Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift, Sources/CodexBarCore/Providers/MiMo/MiMoUsageFetcher.swift, Tests/CodexBarTests/MiMoProviderTests.swift)
• Yuxin-Qiao: Provided the live MiMo API field analysis in the canonical issue and authored a recent merged MiMo auth redirect fix. (role: API evidence contributor and recent MiMo contributor; confidence: medium; commits: 77044e418aa7; files: Sources/CodexBarCore/Providers/MiMo/MiMoUsageFetcher.swift, Tests/CodexBarTests/MiMoProviderTests.swift)
• AdrianSimionov: Authored merged MiMo token usage and balance breakdown changes and the earlier reserve implementation attempt that this brief responds to. (role: recent MiMo token-plan contributor; confidence: medium; commits: ca948292c164; files: Sources/CodexBarCore/Providers/MiMo/MiMoUsageSnapshot.swift, Sources/CodexBarCore/Providers/MiMo/MiMoUsageFetcher.swift, Tests/CodexBarTests/MiMoProviderTests.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.

[steipete]

Accepted and refreshed on exact head 42ba910000d5fc6987338dccf98830e9fc26888c.

Changes:

• records the fail-closed policy as the accepted decision
• keeps windowMinutes and reserve/deficit text absent without authoritative period evidence
• explicitly rejects missing, malformed, contradictory, or undocumented cadence data
• leaves Implement reserve for Xiaomi MiMo plan #1205 open for evidence and a separately reviewed runtime implementation

Proof:

• make check passed
• documentation links: 144 local links clean
• SwiftFormat: 0/1237 files require formatting
• SwiftLint: 0 violations in 1236 files
• exact-head CI: 6 successful checks plus the intended docs-only macOS skip
• CI run: https://github.com/steipete/CodexBar/actions/runs/28681897996

Docs only; runtime MiMo behavior is unchanged.