gacha-event-tracker/docs/superpowers/plans/2026-10-22-version-routines.md

Version routines 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: Built-in routines can reset with a game's version, from a hand-kept, cited table of version timers; WuWa's three shop-pull lines are the first.

Architecture: A new src/shared/versions.ts holds VERSIONS, VERSION_DAYS and a pure versionWindow(game, now). Built-in routines gain a { unit: "version" } period (never in the stored PeriodSchema); taskStatus resolves it through versionWindow and reports it as scope cycle. The About tab of a game in Your games shows the version row.

Tech Stack: Bun, TypeScript, zod, React 19, bun test.

Spec: docs/superpowers/specs/2026-10-22-version-routines-design.md

Global Constraints

• The stored PeriodSchema, TaskSchema, gacha-tracker:v1:tasks and the export format do not change.
• A routine resets only at a recorded end; an estimate is displayed, never acted on (decision 3).
• Version start/end are ISO UTC instants; end is when the next version's stock appears.
• WuWa 3.7: end = 2026-11-11T10:30:00Z, next = "3.8"; VERSION_DAYS.wuwa = 42.
• Version routines are amount measures only; scope reported as "cycle".
• The period key is the start instant's UTC date, bare YYYY-MM-DD (AmountLog keys are free strings, but PinnedRoutine and the catch-up code compare periodStart with day keys, so a date stays comparable).
• Captions (exact): resets with 3.8 · 11 Nov; resets with next version (3.9) · expected ~23 Dec; resets with next version · expected ~23 Dec; past the estimate append , not yet confirmed.
• Every figure cites an https page; an in-game figure's note says Confirmed in game, YYYY-MM-DD.

Review Focus

• The moment of the switch: one minute before end, the old count is shown; at end exactly, 0/7. Pinned in Task 1 and Task 2.
• Past the estimate with no recorded end: the count holds and the key does not move. Task 1 tests the same key on 2027-02-01.
• A routine row with daysLeft null: the chip shows n/7 with no · 0d. Task 2 goalCount test.
• Catch-up "Last version:": without a periodOf for version, the Dailies catch-up would throw. Task 2 skips amount catch-up for version items, with a test.
• The timeline band for an open-ended version: routinePeriod must not throw or draw a zero-width band. Task 2 test: it ends at the estimate.

---

Task 1: Version table and window

Files:

• Create: src/shared/versions.ts
• Modify: src/shared/period.ts (add RoutinePeriodSchema, RoutinePeriod)
• Test: test/versions.test.ts

Interfaces:

• Produces:

  • period.ts: export const RoutinePeriodSchema = PeriodSchema.or(z.object({ unit: z.literal("version") })); export type RoutinePeriod.
  • versions.ts: interface GameVersion (fields as the spec § Shape), VERSIONS: readonly GameVersion[], VERSION_DAYS: Partial<Record<GameId, number>>, interface VersionWindow { number?: string; key: string; start: number; end?: number; estimate?: number; nextNumber?: string }, versionWindow(game: string, now: number, versions = VERSIONS, days = VERSION_DAYS): VersionWindow | undefined, versionCaption(w: VersionWindow, now: number): string (the exact caption strings; dates as asOfLabel minus the year, e.g. 11 Nov).

• Step 1: Write failing tests in test/versions.test.ts:

  • table invariants over VERSIONS: per game sorted, non-overlapping; end > start; recorded end equals the next entry's start; https source; both instants parse; checked is a date.
  • versionWindow("wuwa", Date.parse("2026-10-22T14:30:00Z")) → { number: "3.7", key: "2026-09-30", end: Date.parse("2026-11-11T10:30:00Z"), nextNumber: "3.8", estimate: undefined }.
  • at 2026-11-11T10:29:00Z → number "3.7"; at 2026-11-11T10:30:00Z → { number: "3.8", key: "2026-11-11", end: undefined, estimate: Date.parse("2026-12-23T10:30:00Z"), nextNumber: undefined }.
  • at 2027-02-01T00:00:00Z → still number: "3.8", key: "2026-11-11".
  • a fixture table with one entry and no end → window is that entry, estimate = start + 42d.
  • versionWindow("genshin", now) → undefined; with days lacking the game → estimate undefined.
  • versionCaption: "resets with 3.8 · 11 Nov"; "resets with next version (3.9) · expected ~23 Dec" (fixture with next: "3.9"); "resets with next version · expected ~23 Dec"; past the estimate → "…expected ~23 Dec, not yet confirmed"; no estimate → "resets with next version".

• Step 2: Run bun test test/versions.test.ts — expect FAIL (module missing).

• Step 3: Implement. First entry per the spec § First entry. Before writing it, check a page for 3.7's start (Game8 / Fandom / Prydwen). If one states it, cite it; otherwise use 2026-09-30T10:30:00Z and say in note that the start is 42 days before the in-game end. Comment on VERSION_DAYS.wuwa citing 3.7's length and AGENTS.md's six weeks. Window rules exactly as the spec § Shape.

• Step 4: Run bun test test/versions.test.ts — PASS.

• Step 5: Commit feat(versions): a cited table of version timers, and the window holding now.

Task 2: Routines can follow a version

Files:

• Modify: src/shared/routines.ts (schema period → RoutinePeriodSchema), src/shared/task.ts (TaskShape.period: RoutinePeriod; taskStatus; taskCaption), src/shared/goal.ts (goalCount), src/client/state/reader/routines.ts, src/client/components/Dailies.tsx, src/client/components/redesign/TimelinePage.tsx, src/client/components/redesign/RoutinesPage.tsx, src/client/components/redesign/RoutineDrawer.tsx (period line), plus whatever else bun run typecheck names.
• Test: test/task.test.ts, test/routines.test.ts, test/reader-routines.test.ts, test/redesign-routines.test.tsx

Interfaces:

• Consumes: Task 1's RoutinePeriod, versionWindow, versionCaption.

• Produces: taskStatus accepts task.period: RoutinePeriod; for version it returns scope: "cycle", periodStart: window.key, daysLeft/open = Math.ceil((end - now) / DAY) when end is recorded, else null. taskCaption(task, now?) uses versionCaption for version. A routineVersioned(r): boolean helper in routines.ts.

• Step 1: Write failing tests:

  • task.test.ts: a wuwa version routine (amount 7) with amounts = { "2026-09-30": { value: 3, at } } at 2026-10-22T14:30Z → count 3, required 7, scope "cycle", periodStart "2026-09-30", daysLeft 20; at 2026-11-11T10:30Z → count 0, periodStart "2026-11-11", daysLeft null, open null.
  • goalCount({ scope: "cycle", count: 3, required: 7, daysLeft: null, open: null, ... }) → "3/7"; with daysLeft: 20 → "3/7 · 20d".
  • routines.test.ts: every routine with period.unit === "version" has measure.kind === "amount"; RoutineSchema accepts { unit: "version" }; TaskSchema still refuses it.
  • reader-routines.test.ts: a version routine row has cadence "cycle".
  • Dailies catch-up renders no "Last version" editor for a version item (render test in the existing Dailies/edit tests' style).
  • routinePeriod for an open-ended version row ends at the estimate; with a recorded end, at end.
  • redesign-routines.test.tsx: Make it mine is absent for a version routine.

• Step 2: Run those files — FAIL.

• Step 3: Implement. In taskStatus, branch on version before dayKey. goalCount's cycle form drops · Nd when both daysLeft and open are null. Cadence: version → "cycle". Dailies: amount catch-up returns null for a version period. routinePeriod: version → [window.start, end ?? estimate ?? now + DAY]. RoutinesPage: hide Make it mine when routineVersioned. RoutineDrawer's read-only period line: the caption. Run bun run typecheck and fix every site it lists the same way (version never reaches periodOf).

• Step 4: Run bun test and bun run typecheck — all PASS.

• Step 5: Commit feat(routines): a routine can reset with its game's version.

Task 3: WuWa's shop pulls

Files:

• Modify: src/shared/routines.ts (three entries after Tower of Adversity), test/routines.test.ts (the "each game's, as sourced" wuwa expectation)

• Step 1: Find the source. One page describing the shop's Tide stock (prefer one naming the shop and its currency). Record its date as asOf, checked: "2026-10-22". Title Shop: <Tide>, or <Shop name>: <Tide> if the page names the shop.

• Step 2: Update the test expecting, after Tower of Adversity, the three rows with { unit: "version" } and { kind: "amount", target: 7, unit: "<Tide name>" }; Radiant and Forging pulls: "premium", Lustrous "standard". Run — FAIL.

• Step 3: Add the entries (ids routine:wuwa:shop-radiant-tide, -forging-tide, -lustrous-tide; note ends Confirmed in game, 2026-10-22., ≤140 chars). Run bun test — PASS.

• Step 4: Commit feat(routines): Wuthering Waves' shop pulls, each version.

Task 4: The version row in Your games

Files:

• Modify: src/client/components/redesign/GameSettings.tsx (About group, after the reset rows)

• Test: test/game-settings.test.tsx

• Step 1: Failing test: WuWa's About tab at 2026-10-22T14:30Z shows a row Version 3.7 with ends 11 Nov 2026 (formatted with formatInZone in the reader's zone), (in 19d), a link to the source, and the note. At 2026-11-12 it shows Version 3.8 and next version expected ~23 Dec 2026 (estimate). Genshin's About has no version row.

• Step 2: Run — FAIL. Step 3: Implement with versionWindow and the existing trow markup. Step 4: Run — PASS.

• Step 5: Commit feat(settings): show a game's version timer on its About tab.

Task 5: Docs, browser check, changelog

• Step 1: docs/DATA-MODEL.md (version period built-in only; amounts under the version's start date), docs/PRD.md F17, AGENTS.md bullet (versions hand-kept and cited; estimates shown, never acted on; add each version's end when known), TODO.md (Oscillated Coral partly addressed; follow-ups from spec § Not in this change; "record WuWa 3.8's end"), spec status → shipped with commit range. Commit docs: version routines.
• Step 2: bun run build and drive the app (run skill): WuWa routines show 0/7 · 20d and the caption; About shows the version row. Fix anything found.
• Step 3: Changelog entry in src/shared/changelog.ts in a follow-up commit naming the feature commits, matching recent chore(changelog): … commits; bun test test/changelog*.ts*.