docs: define predictive pace warning decision

[steipete]

Decision

Define a bounded, opt-in predictive pace warning before any implementation work. This PR intentionally contains only the reviewed decision spec; it does not change runtime behavior.

Recommendation

• Default off.
• Codex and Claude only.
• Session and weekly windows only.
• One-hour cooldown per provider/account/window while risk persists.
• A successful recovery clears cooldown; missing/incomplete data does not.
• In-memory state only.
• Reuse existing notification delivery, sound, localization, and privacy redaction paths.

Tradeoff

Hourly repetition keeps sustained risk visible but is noisier than one alert per relapse. The spec therefore makes the feature opt-in, fixes the cooldown rather than adding more settings, and offers one-alert-per-relapse as the explicit alternative for maintainer sign-off.

Scope boundary

PR #1789 owns pace presentation, historical confidence settings, and localization. This proposal does not alter those surfaces and calls for a separate implementation only after approval.

Validation

• make check
• Focused structured autoreview: clean; patch correct (0.89)

Refs #1299.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 3, 2026, 3:58 PM ET / 19:58 UTC.

Summary
Adds a docs/superpowers decision spec for default-off predictive pace warning notifications, covering scope, eligibility, episode state, privacy copy, implementation seams, and required tests.

Reproducibility: not applicable. this is a docs-only decision PR, not a bug with a failing current-main behavior. Source inspection confirms the runtime feature is not changed here.

Review metrics: 2 noteworthy metrics.

• Docs-only diff: 1 file added, +116/-0. The patch records a product decision and does not change runtime, dependencies, workflows, or persisted data.
• Runtime files changed: 0 source/test/workflow files. This keeps merge risk low but confirms the predictive notification feature remains unimplemented until a separate PR lands.

Root-cause cluster
Relationship: partial_overlap
Canonical: #1299
Summary: The open feature request remains the canonical product work; this PR supplies the decision spec for that request, while the related pace-headroom and notification-identity PRs are adjacent but distinct.

Members:

• canonical: Feature request: predictive pace warning notifications #1299 - The issue tracks the predictive pace warning feature request that this docs spec references and remains open.
• adjacent_distinct: [codex] Add Codex pace headroom hint #1789 - That PR changes pace presentation and historical confidence settings, while this PR explicitly avoids those surfaces and only records notification policy.
• adjacent_distinct: docs: define provider notification identity #1831 - That closed decision draft covered provider notification identity on the same delivery path, but it did not alter this predictive warning spec.

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: 🐚 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:

• Update the PR body so its recommendation matches the one-alert-per-risk-episode policy now recorded in the spec.

Risk before merge

• [P1] The PR body still describes a one-hour cooldown while the added spec now accepts one alert per risk episode and rejects hourly repeats, so reviewers could follow the wrong policy if they read only the body.
• [P1] Merging this documentation does not ship predictive notifications; the linked feature request still needs a separate runtime implementation if maintainers accept the decision.

Maintainer options:

1. Decide the mitigation before merge
   Use this PR as the maintained decision record after synchronizing the PR body, then implement the accepted default-off pace warning in a separate focused PR tied to the open feature request.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] Owner-authored docs-only decision PR needs maintainer merge/close judgment and PR-body synchronization; no branch repair is needed.

Security
Cleared: The diff adds one Markdown spec under docs and introduces no code execution, dependency, secret, workflow, or supply-chain surface.

Review details

Best possible solution:

Use this PR as the maintained decision record after synchronizing the PR body, then implement the accepted default-off pace warning in a separate focused PR tied to the open feature request.

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

Not applicable: this is a docs-only decision PR, not a bug with a failing current-main behavior. Source inspection confirms the runtime feature is not changed here.

Is this the best way to solve the issue?

Yes for the current step if the PR body is synchronized: documenting scope, notification noise, privacy, and test expectations before runtime work is the narrow maintainable path. The actual feature should remain a separate implementation PR.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 58968bd8b52e.

Label changes

Label justifications:

• P3: This is a low-risk docs/product-decision PR for a speculative notification feature, not an urgent regression.
• 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 present and read fully; its docs, focused validation, no-live-Keychain-prompt, and read-only review guidance applied to this PR review. (AGENTS.md:1, 58968bd8b52e)
• Vision requires sign-off for features: VISION.md lists documentation fixes as merge-by-default but new features and privacy-affecting behavior changes as needing sign-off, which supports treating this as a decision record before implementation. (VISION.md:9, 58968bd8b52e)
• Docs-only PR diff: The PR adds one Markdown spec under docs/superpowers/specs with 116 additions and no source, test, workflow, dependency, or runtime file changes. (docs/superpowers/specs/2026-07-01-predictive-pace-warning-notifications-design.md:1, 6e8a8301eb59)
• Latest spec rejects hourly repeats: The added document now specifies one alert per provider/account/reset-window risk episode and explicitly says hourly repeats are rejected. (docs/superpowers/specs/2026-07-01-predictive-pace-warning-notifications-design.md:16, 6e8a8301eb59)
• Current pace inputs exist: Current main exposes UsagePace.etaSeconds, willLastToReset, and runOutProbability, which are the forecast fields the spec proposes to reuse. (Sources/CodexBarCore/UsagePace.swift:18, 58968bd8b52e)
• Current quota warnings remain reactive: Current main posts quota warnings from configured remaining-percent threshold crossings, not from pace forecasts. (Sources/CodexBar/UsageStore+QuotaWarnings.swift:6, 58968bd8b52e)

Likely related people:

• steipete: Authored this decision spec and appears in current history for weekly pace configuration and notification/usage paths relevant to the feature boundary. (role: owner-decision holder and recent area contributor; confidence: high; commits: 926a5fbe8aaa, 2f92ee97e46e, 0de6cac0a3c8; files: docs/superpowers/specs/2026-07-01-predictive-pace-warning-notifications-design.md, Sources/CodexBarCore/UsagePace.swift, Sources/CodexBar/SessionQuotaNotifications.swift)
• Alekstodo: Commit history shows this contributor added configurable quota warning controls and markers, the existing notification surface this spec would sit beside. (role: threshold warning controls contributor; confidence: high; commits: 18eb73dde236; files: Sources/CodexBar/SessionQuotaNotifications.swift, Sources/CodexBar/UsageStore+QuotaWarnings.swift, Tests/CodexBarTests/UsageStoreSessionQuotaTransitionTests.swift)
• Remedy92: Commit history shows this contributor introduced the weekly pace indicator and core UsagePace surface reused by the proposed predictive warning. (role: pace feature introducer; confidence: medium; commits: a679311227fc; files: Sources/CodexBarCore/UsagePace.swift, Sources/CodexBar/UsagePaceText.swift)
• Yuxin-Qiao: Commit history shows recent fixes to historical pace run-out forecasts, including behavior that supplies runOutProbability for the proposed eligibility gate. (role: recent historical pace repair contributor; confidence: medium; commits: f986661480c7; files: Sources/CodexBar/HistoricalUsagePace.swift, Tests/CodexBarTests/HistoricalUsagePaceTests.swift, Tests/CodexBarTests/UsagePaceTextTests.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]

Maintainer closeout on exact head 6e8a8301eb5960bc3ac52693130ef2cf02fcae5e:

• Accepted the default-off Codex/Claude session-and-weekly predictive warning boundary.
• Chose one notification per provider/account/reset-window risk episode. Continuous risk never repeats merely because an hour passed.
• Re-arm requires a successful authoritative observation with willLastToReset == true; low-confidence, missing, incomplete, and failed refreshes preserve episode state rather than manufacturing recovery.
• New reset-window identities start independently and expired keys must be pruned. State remains memory-only.
• Proof: make check passed; exact-head CI is green (both Linux builds, lint, aggregate gate, GitGuardian; macOS correctly skipped for docs-only scope).

This lands the product/state-machine decision only; runtime implementation remains separate.