diff --git a/docs/plans/2026-09-03-recurring-costs.md b/docs/plans/2026-09-03-recurring-costs.md new file mode 100644 index 0000000..e92be97 --- /dev/null +++ b/docs/plans/2026-09-03-recurring-costs.md @@ -0,0 +1,3037 @@ +# Recurring Costs Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Bills that repeat — rent monthly, a subscription every 28 days, a phone bill every 30 days whose clock restarts when the data cap is hit — project as *expected* charges and are confirmed into real purchases when the money moves. + +**Architecture:** A new `RecurringCost` entity projects occurrence dates through a pure walk (`src/domain/occurrences.ts`) built on new pure day arithmetic (`src/domain/days.ts`). Occurrences are computed on every fold and never stored. The fold gains a second balance track — `projected` alongside `remaining` — fed by unconfirmed occurrences. Confirming one writes an ordinary `Purchase` carrying `source: { recurringId, occurrenceDate }`, which suppresses that slot on the next fold. + +**Tech Stack:** Bun (runtime, test runner, bundler, package manager), TypeScript, React 19, Tailwind 4, shadcn/ui. No new dependencies. + +**Spec:** `docs/specs/2026-09-03-recurring-costs-design.md` — read it before Task 1. The plan argues from the spec; where they disagree, the spec wins and the plan is wrong. + +## Global Constraints + +Copied verbatim from `AGENTS.md`. Every task's requirements implicitly include these. + +- **Bun only.** `bun test`, `bun install`, `bun run