gacha-event-tracker/docs/superpowers/plans/2026-10-13-periodic-tasks-2a.md

# Weekly and Monthly Tasks (Phase 2a) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Let the reader add their own weekly and monthly tasks per game — ticked N days per period, or a number against a target (`1900 / 2100`) — shown beside the dailies, and let an event's check-in goal be a number too.

**Architecture:** One status shape for everything periodic: `GoalStatus` (from `goal.ts`) gains month scope, an `amount` measure and the period's start key, and `taskStatus` returns it. That lets the Dailies chip, its count, label and tallying serve chores, events and tasks alike. Two new stores: `tasks` (raw records kept, validated for display only) and `amounts` (a value per item per period). Both travel in the export.

**Tech Stack:** Bun, TypeScript, React 19 (static-render tests), Zod 3, Tailwind 4.

**Spec:** `docs/superpowers/specs/2026-10-13-periodic-tasks-design.md` (phase 2a), building on `docs/superpowers/specs/2026-10-03-check-in-goals-design.md`.

## Global Constraints

- No change to `GachaEvent`, event IDs, day-log keys or existing storage keys. New keys: `gacha-tracker:v1:tasks`, `gacha-tracker:v1:amounts`.
- Never drop a stored record on load: the task store keeps raw records and filters for display; the amount store never prunes a period.
- Import merges and never removes: tasks by id, later `updatedAt` wins; amounts per item **and** period, later `at` wins; malformed incoming entries are skipped.
- `Task.game` is `z.string()`, never `GameId` (AGENTS.md § retirement rule).
- `mytask` joins `RESERVED_ID_SEGMENTS` (and `routine`, reserved now for 2b).
- A chip is one target: an amount chip opens an editor, it never ticks.
- The header's `Today's dailies · n/total` counts day-cadence items only; weekly and monthly tasks get their own counts; only a real tick today celebrates.
- All calculations pure, `now` explicit. Commits: one coherent change each, green, pathspec, one command per Bash call.

## Review Focus

1. **A task record a later version wrote** (unknown measure) — hidden, never removed from storage, and survives export/import.
2. **An amount typed as `1,900`, `1900.5`, empty or negative** — amounts are whole numbers: separators are stripped, decimals rounded, empty or unreadable is mid-edit (Save disabled), negative refused.
3. **A monthly task with start day 31 in a 30-day month** — period boundaries from `periodOf`'s clamping; the amount key is the clamped start.
4. **Importing an older backup onto a device whose amount for the same week is newer** — the newer value stays.
5. **A task on a game the reader has hidden or isn't focused on** — not shown; its data untouched.

## Tasks

Each task: write the named tests first and watch them fail, implement, run `bun test` + `bun run typecheck`, commit by pathspec.

### Task 1: Amount goals and month scope in the goal model
**Files:** `src/shared/goal.ts`, `test/goal.test.ts`
**Produces:**
- `GoalSchema` adds `{ period: "week", measure: "amount", target: number (>0, ≤1e9), weekStartsOn }` and `{ period: "event", measure: "amount", target }`.
- `type AmountLog = Record<string /*periodStart*/, { value: number; at: string }>`.
- `GoalStatus` gains `measure: "days" | "amount"`, `periodStart: string`, and `scope: "week" | "month" | "event"`.
- `goalStatus` input gains `amounts?: AmountLog`. For amount: `count = amounts[periodStart]?.value ?? 0`, `required = target`, `open` = remaining days in scope (null for an unknown-end event), `shortfall = false`. `periodStart` = the week's start, or the event's first game-day for event scope.
- Copy: `goalCaption` amount → `1,900 of 2,100 this week · 200 to go`, met → `2,100 of 2,100 · Done this week`; `goalCount` amount → `1,900/2,100` (+` wk`/` mo`); month scope → `this month` / `mo` / `done this month`. Numbers via `toLocaleString("en-US")`.
- `goalRequired(goal): number` (required or target) for callers that showed `goal.required`.

**Tests:** amount week counts the stored value for this week only; last week's value ignored; met at ≥ target; event-scope amount keyed by first game-day; captions/count/label for amount and month; `readGoal` accepts amount shapes and still rejects `{measure:"amount"}` without target.

### Task 2: The task model
**Files:** create `src/shared/task.ts`, `test/task.test.ts`; modify `src/shared/custom.ts` (`RESERVED_ID_SEGMENTS` += `"mytask"`, `"routine"`).
**Produces:**
- `TaskId = z.string().regex(/^mytask:[a-z0-9]{6,32}$/)`, `mintTaskId(random = Math.random): string`.
- `MeasureSchema` = `{ kind: "days", required: 1–31 }` | `{ kind: "amount", target: >0 ≤1e9, unit?: string ≤24 }`.
- `TaskSchema` = `{ id, game: z.string().min(1), title: 1–80 trimmed, period: PeriodSchema, measure, from?: string, at, updatedAt }`, `type Task`.
- `taskStatus({ task, region, now, logged, amounts }): GoalStatus` — scope = `period.unit`; days: distinct ticks in `periodOf(...)` ≤ today; amount: value at the period start; `open` = period days ≥ today unticked (days) or remaining (amount); `required` for days capped at the period length.
- `taskCaption(task): string` — `every week from Monday · tick 1 day` / `every month from the 1st · reach 2,100 points`.

**Tests:** weekly days task done once this week; monthly amount task reads its month's key with 31→30 clamping; per-region boundary at reset (Genshin Europe); reserved segments include `mytask` (extend the existing `custom.test.ts` loop expectation if needed); caption strings.

### Task 3: Task and amount stores
**Files:** create `src/client/state/useTasks.ts`, `src/client/state/useAmounts.ts`, `test/tasks-store.test.ts`; modify `src/client/state/storage.ts` (KEYS `tasks`, `amounts`).
**Produces:**
- `mergeTasks(current: Record<string, unknown>, incoming: unknown): Record<string, unknown>` — validates incoming with `TaskSchema`, skips bad ones, keeps current records (even unreadable), later `updatedAt` wins.
- `visibleTasks(raw: Record<string, unknown>): Task[]` — the parseable ones, sorted by game then title.
- `useTasks()` → `{ tasks: Task[], addTask(draft), editTask(id, draft), removeTask(id), merge(incoming: unknown) }` with `type TaskDraft = { game, title, period, measure }`.
- `mergeAmounts(current: AmountLogMap, incoming: unknown): AmountLogMap` — per item and period, finite numbers only, later `at` wins, never removes.
- `useAmounts()` → `{ amounts: AmountLogMap, amountsFor(key): AmountLog, setAmount(key, periodStart, value: number | undefined), merge(incoming: unknown) }`. `setAmount(undefined)` removes that one period's entry (reader's own action).

**Tests:** unreadable stored task kept by merge and hidden by `visibleTasks`; merge later-wins both directions; amounts merge per period (older backup cannot roll back a newer week; a period only on one side survives; strings/NaN skipped).

### Task 4: Tasks and amounts in export and import
**Files:** `src/client/state/export.ts`, `src/client/App.tsx`, `test/progress.test.ts`.
**Produces:** `ExportData.tasks?`, `ExportData.amounts?`; `buildExportData(..., own: { games, events, tasks?, amounts? }, prefs?)` writes them when given; `ParsedImport.tasks: unknown`, `ParsedImport.amounts: unknown`; `importProgress` gains `mergeExtra(tasks, amounts)` before `restorePrefs`.
**Tests:** round trip keeps tasks (including an unreadable one) and amounts; an export without the keys parses with both `undefined`.

### Task 5: Tasks and amounts in the Dailies strip
**Files:** `src/client/components/Dailies.tsx`, create `src/client/components/AmountEditor.tsx`, `src/client/App.tsx`, `test/views.test.tsx`.
**Produces:**
- `DailyItem` gains `cadence: "day" | "week" | "month"` and `period?: Period` (tasks). Chores and events are `"day"`.
- `dailyGroups(..., goalFor, tasks: readonly Task[] = [], taskStatusFor: (t: Task) => GoalStatus = …)` appends a lane's tasks after its events, **only for lanes in `games`** (no stragglers: a hidden game's tasks stay hidden).
- `dailyTally` returns `{ total, complete, tickedToday, week: { total, complete }, month: { total, complete } }`, where `total/complete` count `"day"` items only.
- An item whose `goal.measure === "amount"` renders as an amount chip: label, `1,900/2,100`, a 2px underline in the hue at `count/required` width; click opens `AmountEditor` under the strip (`<label>{title} this week: <input> / 2,100 <unit>` · Save · Cancel; Enter saves, Escape cancels; empty or invalid disables Save; negative refused; integers).
- Header: `Today's dailies · n/total` then, when present, `· Weekly a/b · Monthly c/d`.
- Catch up: a days task gets `catchUpDays` pips as a chore does; an amount task gets an `AmountEditor` for the previous period.
- `Dailies` props: `tasks?`, `taskStatusFor?`, `onSetAmount?: (key, periodStart, value) => void`, `amountFor?: (key, periodStart) => number | undefined`.
**Tests:** task placement after events; hidden-lane tasks absent; separate counts; amount chip renders `1,900/2,100` with no `aria-pressed`; `chipLabel` for amount and month (`…, 1,900 of 2,100 this week`, `…, done this month`); `AmountEditor` static render with value and target.

### Task 6: Amount goals on events in the detail sheet
**Files:** `src/client/components/GoalControl.tsx`, `src/client/components/EventDetail.tsx`, `src/client/components/DailyChecklist.tsx` (none if the caption already handles amount), `src/client/App.tsx`, `test/views.test.tsx`, `test/custom-ui.test.tsx`.
**Produces:** `GoalControl` shows, once a goal is set, a measure toggle **Days · Points**; Points shows `[2100] points each week` / `in total` with its own draft field. `chooseGoal` keeps the measure when switching period. `EventDetail` gets `amount?: number`, `onSetAmount(id, periodStart, value)`, and renders an `AmountEditor` (always open, inline) under the goal control for an amount goal.
**Tests:** `chooseGoal` keeps measure; switching Days→Points carries a sensible default target (100); sheet renders the editor with the current value.

### Task 7: Your tasks in settings
**Files:** create `src/client/components/TaskForm.tsx`; modify `src/client/components/YourOwn.tsx`, `src/client/components/Controls.tsx` only if props pass-through needs it, `src/client/App.tsx`, `test/custom-ui.test.tsx`.
**Produces:** "Your weekly and monthly tasks" list in the Your own group (game short name, title, `taskCaption`, Edit, Delete) and **Add a task**. `TaskForm`: game (select of lanes by name), title, Every week (weekday select, default Monday) / Every month (day 1–31, default 1), Tick it off (`[1]` days) / Reach a number (`[target]` + optional unit). Save disabled until valid against `TaskSchema`.
**Tests:** form renders defaults; list shows caption; empty state shows the add button.

### Task 8: Docs and a look
PRD new feature entry (F17 — weekly and monthly tasks); DATA-MODEL keys, shapes, merge rules, reserved segments, export keys; AGENTS.md § Events the reader entered themselves (tasks join the reader's spaces; task store never drops on load); DESIGN.md amount chip + editor; spec status; recurring-events spec Phase C pointer. Build and screenshot the strip with a weekly amount task and a monthly tick task, and the settings form, dark and light, on a fresh port.