Status: ✅ done · 🚧 partial · ❌ not started

A normal alarm asks for a clock time, so the user has to add up preparation, travel and a safety margin in their head, and people misjudge all three. JustInTime asks instead how sure the user wants to be of arriving on time (τ, for example 0.90 for a class and 0.99 for an exam) and works backwards from the event: the alarm is the event start minus a 10-minute buffer minus the τ-quantile of preparation plus travel time. Travel comes from Kakao routes, corrected by trips observed on the same route, and preparation is learned from one tap per finished routine block. The alarm rings on a locked screen and after a reboot even when the server is down, and departure and arrival are recorded automatically by GPS. The app shows how each alarm was derived, labels every figure as measured or fixed, and lets the user pick the risk they accept from a few wake-up options with their on-time probability. A weekly report says whether the promised on-time rate held and sums up the week in a few sentences.

JustInTime is for people who must be somewhere at a set time and wake up by alarm for it: university students, commuters and anyone with an early appointment. Routes come from Kakao, so it works anywhere in Korea; in Seoul, real-time subway and bus arrivals are added to the routes.

Primary: U1 and U3.

Competitors are arrival-based alarm apps such as Arrive, which turn a destination, preparation time and buffer into a wake-up time; alarm apps such as Alarmy, which make waking up hard to skip; and Google Calendar's "time to leave" reminder.

O = yes · X = no · △ = partly

Not claimed as new: backward calculation, live traffic, wake-up missions. Our claims are that (1) the margin is a probability, not minutes, (2) personal preparation time is learned, and (3) predictions are checked after the fact and shown to the user.

Iteration 1 goal: one flow end to end: sign in → add an event → the server computes the alarm → the alarm fires → departure and arrival land in the server DB. Done on the emulator as of 0.10.0, including an automated run through the real UI (qa/demo/run.py).

Iteration 2 goal: turn the single alarm into a choice the user can reason about, and close the loop with a report: routes grouped by mode, risk options with their probability, home as a destination, arrival that is detected reliably, and a weekly report with a plain-language summary. Done on the emulator as of 0.11.0 against a local server, with the same automated UI run (signing up, adding an event, alarm, routine, GPS departure and arrival, report).

Each story follows As a <role>, I want <capability>, so that <benefit> and carries at least one acceptance test (AT) in Given–When–Then form. Stories are grouped by the iteration they are planned for; the code is ahead of the plan in places. [CORE] tests are the candidates for the user acceptance test and are frozen after Iteration 3. IDs are never reused; new stories and tests take the next free number. AT-28 to AT-32 were added in 1.3 from the task lists in the full specification so that every story has a test; they will be refined when their iteration starts. Statuses were re-checked against main 8148108 on 2026-10-18 (version 2.0).

US-1 As a user, I want to sign in with email and password, so that my alarm data stays mine.
Status: 🚧 email only; the server checks the password rules and requires terms consent

• AT-1 ✅ Given an unused email · When signing up · Then 201 with a JWT pair and a profile, and the consent time is stored; a reused email, no terms consent, or a password that fails the rules (8+ characters, letters and digits) → 400. The 11th sign-up attempt from one IP within an hour, successful or not → 429 with a Korean message and Retry-After, and no account is created
• AT-2 [CORE] ✅ Given user A's event · When user B requests it by id · Then 404, not 403; 403 would reveal that the id exists

US-2 As a new user, I want to set my home and usual prep time once, so that I don't enter them per event.
Status: ✅

• AT-3 ✅ Given an account with no home · When opening Home · Then a banner asks for a home and plans stay no_home; saving a home recomputes them. A usual prep time outside 5–240 min is rejected by the server too (400 with a Korean reason on that field), and nothing else in the request is saved

US-3 As a student, I want to add an event with time, category, destination and route, so that I get an alarm right away.
Status: 🚧 a saved event can't be edited

• AT-4 ✅ Given a home is set · When creating an event with a place · Then the response carries its alarm_plan; without a place the status is no_place and no time is invented. An origin and destination less than 50 m apart → 400, shown under the destination field
• AT-26 ❌ server PATCH ready · Given a saved event · When changing its time, place or route in the app · Then the server recomputes and the new alarm replaces the old one

US-4 As an over-bufferer, I want the alarm broken into prep, travel and buffer, so that I can trust it and sleep longer.
Status: ✅

• AT-5 [CORE] ✅ Given prep 30 + travel 27 + buffer 10 for a 14:30 event · When opening the alarm screen · Then the alarm is 13:23, prep + travel + buffer = start − alarm exactly, and each item is labeled measured or fixed

US-5 As a user, I want the alarm to fire on a locked screen and after a reboot, so that I can fall asleep trusting it.
Status: ✅ emulator

• AT-6 [CORE] ✅ emulator · Given a registered alarm and a locked screen · When the time comes, also after a reboot without opening the app · Then the full-screen alarm shows at the same absolute time

US-6 As a user, I want departure and arrival recorded automatically, so that predictions improve without daily input.
Status: ✅

• AT-7 [CORE] ✅ emulator · Given tracking started at dismissal · When 2 fixes in a row are ≥ 150 m from home (or the user keeps moving), then the first valid fix (accuracy ≤ 50 m) lands within 100 m of the destination · Then arrival is confirmed at once with no waiting, departure and arrival are uploaded with the time the radius was entered, tracking stops, and the arrival stays on screen. Changed in 2.0 from "within 50 m for 2 min", which left users indoors stuck on "confirming arrival"
• AT-8 ✅ Given an upload that was cut off · When it is resent with the same client_uuid · Then {accepted: 0, duplicated: 1}, no new row

US-26 As a student with several events a day, I want only the first one to wake me unless I turn others on, so that later events don't wake me again.
Status: ✅

• AT-27 ✅ Given two events on the same day, both with computed alarms · When no switch has been touched, then the earlier one is switched off · Then only the earlier alarm is on and marked first; once it is off, the later one becomes first. The phone registers only alarms that are on
• AT-33 ✅ Given events A and B on the same day, A switched off and B switched on by hand · When the user adds a later event C on that day · Then A, B and C go back to the automatic rule (A on as the first alarm, B and C off), switches on other days are kept, and a switch the user set on C itself is kept. Calendar import does not reset switches

US-7 As a user, I want my preparation split into blocks with time ranges, so that I can pick only today's.
Status: ✅

• AT-9 ✅ Given prep is a single value · When declaring "shower 12–18 min" · Then prep sd = (18 − 12) / 4 = 1.5

US-8 As a user, I want to uncheck "wash hair" and get a later alarm, so that I don't wake up for something I skip.
Status: ✅

• AT-10 [CORE] ✅ (N10 not met) · Given an event with shower, hair and clothes blocks · When unchecking hair · Then the alarm moves later by that block and its line disappears

US-9 As a commuter, I want to choose among transit, walk, bicycle and car routes, so that I decide whether avoiding a transfer is worth 4 minutes.
Status: ✅ grouped by mode (up to 4 car, 3 transit, 1 walk, 1 bicycle) with the fastest preselected; 🚧 the server still asks Kakao for one car route (four car options planned), and times are not yet matched to the target arrival time or actual service hours

• AT-11 ✅ Given route candidates for an event · When choosing "27 min, bus, 0 transfers" · Then the plan uses that route and 27 min; with no choice, the faster of transit and walking
• AT-37 ✅ Given an origin and a destination · When opening ⑬ Route choice · Then candidates are listed per mode tab, the fastest one across all modes is already selected, each card shows a guide sentence built only from the route data (origin → destination, mode and distance, the roads taken by car or the lines taken by transit, minutes), transit cards carry "최단 시간 / 최소 비용 / 최소 환승" (fastest / cheapest / fewest transfers) badges, and tapping the walking or cycling route opens its map preview

US-10 As a user, I want one tap per finished prep block, so that the app learns my pace.
Status: ✅

• AT-12 ✅ Given a morning session · When marking "shower" done · Then its duration and the slack at its start are uploaded

US-11 As a user, I want tomorrow's alarm to fire even if the server or network is down, so that an outage can't make me late.
Status: ✅

• AT-13 [CORE] ✅ Given 3 registered alarms · When background sync can't reach the server · Then all 3 stay registered; only a retry is scheduled
• AT-14 [CORE] ✅ Given an expired access token · When refresh fails with a 5xx or network error · Then the user stays signed in; only 400/401/403 sign out

US-12 As a student, I want to import events from my device calendar, so that I don't type them twice.
Status: ✅ from the Android calendar provider (accounts synced to the phone, such as Google, included); more sources and automatic re-sync are planned

• AT-15 ✅ Given 5 device calendar events · When importing the same 2 twice · Then the second run reports unchanged and adds no rows

US-27 As a user who doesn't want to read every chart, I want a few plain sentences about my week, so that I know at a glance whether I was on time and what to change.
Status: ✅ written by an LLM on the server when one is configured, otherwise a fixed template from the same numbers (added in 2.0)

• AT-35 ✅ Given a week with arrivals · When opening ⑧ Weekly report · Then a "주간 요약" (weekly summary) card states the on-time rate against the target, the main cause of lateness, the change from last week and one suggestion, labeled "AI 요약 · 집계 수치만 사용함" (AI summary, aggregate numbers only) when an LLM wrote it. When the week is still running or has fewer than 3 arrivals, or the LLM has no key, times out, fails, uses a number that isn't in the week's figures, or the daily limit is reached, the same card shows the template sentence and the report still opens

US-28 As a user who goes out and comes back, I want to set my home as an event's destination, so that the trip back home gets an alarm too.
Status: ✅ (added in 2.0)

• AT-36 ✅ Given an event whose origin is a searched place · When choosing "집" (home) as its destination and saving, then changing the home address in ⑯ · Then the event computes its travel to the current home, no copy of the home is stored as a place, and an origin within 50 m of home is rejected under that field

US-13 As a user, I want to see my probability of arriving on time, so that I judge the margin by a number.
Status: 🚧 blank until travel variance is observed

• AT-16 [CORE] ✅ Given an account with no observations · When opening the alarm screen · Then the probability is blank: Home hides the probability line, and ④ says "정시 도착 확률 · 아직 계산할 수 없음" (on-time probability can't be computed yet) with the reason and "이동 기록이 쌓이면 변동성이 생김" (variability appears as trip records accumulate); a 0–100 value appears only when prep and travel both have variance. Changed in 2.0: the screen no longer says "learning", which promised a number that waiting alone would not produce

US-14 As a new user, I want a usable alarm on day one, so that I don't wait weeks for data.
Status: ✅

• AT-17 ✅ Given "shower 12–18" declared and 8 observations · When computing the alarm · Then observations weigh 8/(8+5) ≈ 0.62 and the declared range 0.38
• AT-34 ✅ Given a route whose travel correction was built from 20 trips · When opening ④ · Then the travel line reads "카카오 추정 · 이동 기록 20회로 보정" (Kakao estimate, corrected by 20 trips), the count being the samples the estimator actually used; with no correction or a failed route lookup the count is 0 and the line reads "카카오 경로 추정" (Kakao route estimate)

US-15 As a user deciding whether to trust the app, I want to see whether its promised on-time rate held, so that I know if I can sleep longer.
Status: ✅

• AT-18 [CORE] ✅ Given 90 days of events with arrivals · When opening the calibration report · Then each 0.05 τ bucket shows predicted vs. actual on-time rate, buckets under 3 samples are marked unreliable, and the verdict is calibrated / overconfident / conservative / insufficient
• AT-38 ✅ Given a week with three arrivals, one of them late · When opening ⑧ · Then it shows the on-time count against the target, arrivals per weekday (early above the line, late below), the late days with their cause or "원인 측정 못 함" (cause not measured), the week's average plan-versus-actual gaps, and the change from last week; tapping a day or a late event opens ⑨ with that morning's plan against what was measured
• AT-21 [CORE] ❌ no fixed-buffer baseline yet · Given the same events planned personally and with a fixed buffer · When both reach a comparable on-time rate · Then the personal plans leave significantly less total slack

US-16 As a chronically late user, I want my lateness broken into causes (woke late, prep ran over, left late), so that I know what to change.
Status: 🚧 the dismissal time is now recorded (alarm log), but "woke late" isn't derived from it yet

• AT-19 ✅ Given a late event with a departure but no block observations · When opening the weekly report · Then depart_late is filled, prep_over is null (not 0), and the cause is picked only among measured terms
• AT-25 🚧 Given a ringing alarm · When the user dismisses it · Then a wake observation with the dismissal time is queued and uploaded. Since 2.0 the phone queues and uploads ring, snooze, dismiss and auto-silence events with their times (POST alarm-logs/batch); the weekly report doesn't read them yet

US-17 As a student, I want the fastest route from where I am and a warning when I fall behind, so that I still make the attendance call.
Status: 🚧 live route (fastest for the chosen mode) and ETA only

• AT-20 ❌ Given a morning session in progress · When a block finishes later than planned · Then the on-time probability is recomputed from the remaining blocks and a warning appears past a threshold

US-18 As a student, I want a few wake-up options with their on-time probability (7:20 97% / 7:40 90%), so that I choose the trade-off instead of guessing.
Status: ✅ since 2.0; the probability on each option still needs a spread in both prep and travel (US-13)

• AT-28 ✅ Given an event whose total duration has a spread (for example, prep blocks with a min–max range) · When opening ⑤ Risk choice · Then "안전 / 보통 / 도박" (safe τ 0.97 / normal 0.90 / gamble 0.65) each show a wake-up time, and an on-time probability when prep and travel both have a spread; a chart shows the modeled total duration with its median and 90th percentile. Choosing one and tapping "…로 계속하기" (continue with …) saves it as that event's τ, recomputes the alarm, re-registers it on the phone, and keeps it after reopening. A τ outside the three (an exam's 0.99) stays until the user picks one. Without a spread, ⑤ says why there are no options

US-19 As a user who dislikes forms, I want to type "presentation at 9 tomorrow", so that one line creates the event.
Status: ❌

• AT-29 ❌ Given the line "presentation at 9 tomorrow" · When submitting it · Then a draft event titled "presentation" at 09:00 tomorrow with the presentation type is shown for confirmation before saving; when the parser is unsure (confidence < 0.7) the user confirms each field, and a place can only come from Kakao search results

US-29 As a student with a weekly timetable, I want to add a class once and have it repeat, so that I don't add the same event every week.
Status: ❌ ⑫ shows "준비 중" (coming soon) for repeat (added in 2.0)

• AT-39 ❌ Given a class repeating every Monday and Wednesday · When saving it · Then occurrences for the next 7 days are created, each with its own alarm and switch, and skipping or moving one occurrence leaves the others unchanged

US-20 As a friend in a group, I want each member to get their own alarm from one appointment, so that people farther away wake earlier.
Status: ❌

• AT-22 ❌ Given a 4-member room with a 0.9 group target · When fetching the room · Then each member's τ becomes 0.9^(1/4) ≈ 0.974 and their alarm is recomputed from their own origin

US-21 As a group member, I want to know who should wake earlier, so that we don't all lose sleep.
Status: ❌

• AT-23 ❌ Given members with different on-time probabilities · When the group target isn't met · Then τ rises for the one member that costs the group the least total sleep

US-22 As a phone user, I want to know which settings could silence my alarm, so that power saving doesn't make me late.
Status: ❌ ⑯ shows only the location permission

• AT-30 ❌ Given notifications, full-screen alarms or the battery-optimization exemption are not allowed · When opening ⑯ Settings · Then each setting that could silence the alarm is listed with its state and a shortcut to fix it

US-23 As a user, I want the alarm to fire every day for a week on my own phone, so that one miss doesn't end my trust.
Status: ❌

• AT-24 [CORE] ❌ Given the app on a physical Galaxy phone · When 7 mornings in a row, covering locked screen, power saving, reboot and network loss · Then it fires every morning within 5 s

US-24 As the team, we want on-time rate and sleep change from real use, so that our claim rests on data.
Status: ❌

• AT-31 ❌ Given a week of beta use · When the team runs the weekly aggregation · Then on-time rate, sleep-duration change and snooze count are reported per user and week, and the logs contain no coordinates, tokens or keys

US-25 As a beta tester, I want to use this as my real alarm for a week, so that I can judge whether to trust it.
Status: ❌

• AT-32 ❌ Given the signed release APK and its install guide · When a tester installs it on their own phone without developer tools · Then they can sign up, set home and get their first alarm without help

Grouped by quality attribute. IDs come from the full specification, so some numbers are skipped; new items take the next free number (N50 onward). Some acceptance tests double as checks: AT-24 (N1, N2), AT-13 (N3), AT-14 (N4), AT-8 (N7), AT-16 (N16), AT-35 (N49).

The app's text is Korean. Button and message text is quoted as it appears, with an English gloss in parentheses.

Figma board as of 2026-10-13 (version 2.0; the 2026-09-30 board is docs/figma-board.png). Columns are stages; frames below a screen are its children and state variants. Added or redrawn for Iteration 2: ⑬-c walking and ⑬-d cycling with ⑬-e their route map, ⑬ error states, ⑤ risk choice and ⑤-a no options, ④ without a probability, ⑮ prep time with ⑮-a the time dial, ③ and ⑯ variants, ⑧ weekly report with ⑧-a an empty week, and ⑨ day detail with ⑨-a an on-time day and ⑨-b a day without an arrival. The board shows layouts; 7.2 shows how the screens connect and which input moves between them, and 7.3 describes what each screen does, which inputs it accepts and how it handles failures. The board was drawn before the server sent risk options and before home could be a destination, so ⑤-a still reads "선택지 준비 중" (options coming); 7.3 describes those screens as built.

Screens in the app but not on the board yet are marked *: routine blocks, event blocks, calendar import, morning progress and the full-screen alarm. Not built yet: ⑥ replan before departure and ⑩ ⑪ group room and member detail. ⑦ replan in transit exists only as the trip progress inside ④.

Arrows are labeled with the user input that triggers them.

flowchart LR
  login["① Login"] -->|"tap Sign up"| signup["② Sign up"]
  signup -->|"tap Log in"| login
  login -->|"log in"| home["③ Home"]
  signup -->|"sign up"| home
  home -.->|"home or prep time not saved yet"| h14["⑭ Home address"]
  h14 -->|"save or later"| p15["⑮ Prep time"]
  p15 -->|"save or later"| home
  home -->|"tap + Add event"| add["⑫ Add event"]
  add -->|"tap Choose route"| route["⑬ Route choice"]
  route -->|"tap Use this route"| add
  route -->|"tap a walking or cycling route"| preview["⑬-e Route map"]
  preview -->|"tap Use this route"| add
  add -->|"tap Map"| mapPick["⑰ Map pick"]
  h14 -->|"tap Map"| mapPick
  mapPick -->|"tap Choose this place"| add
  mapPick -->|"tap Choose this place"| h14
  add -->|"tap Add (saved)"| home
  home -->|"tap an event"| decision["④ Alarm decision"]
  decision -->|"tap Change lateness risk"| risk["⑤ Risk choice"]
  risk -->|"pick an option, tap Continue"| decision
  decision -->|"tap Choose this morning's tasks"| blocks["Event blocks *"]
  decision -->|"tap OK or Delete"| home
  home -->|"tap avatar"| settings["⑯ Settings"]
  settings -->|"tap Change home"| h14
  settings -->|"tap Change prep time"| p15
  settings -->|"tap Log out"| login
  home -->|"tap Weekly report"| report["⑧ Weekly report"]
  report -->|"tap a day or a late day"| day["⑨ Day detail"]
  day -->|"back"| report
  home -->|"tap Morning routine"| routine["Routine blocks *"]
  home -->|"tap Import from calendar"| cal["Calendar import *"]
  home -->|"tap Morning record card"| morning["Morning progress *"]
  alarm["Full-screen alarm *"] -->|"tap I'm up / Dismiss"| morning
  alarm -->|"tap Snooze 5 min"| alarm

Key flows

• First run: sign up (live password check, terms consent) → ⑭ home → ⑮ prep time on the dial → ③ → ⑫ add event → ⑬ pick a route (fastest preselected) → ④ the alarm and its reasoning → ⑤ pick the risk
• Morning: full-screen alarm (only the day's first alarm unless others are switched on) → dismiss → one tap per prep block and GPS tracking → departure → fastest route for the chosen mode from the current position every minute → arrival (first fix within 100 m) → the result stays on screen
• Trust check: ③ → ⑧ weekly summary, on-time rate, arrivals per weekday, late days, plan versus actual, calibration verdict → ⑨ one morning in detail

Sign-in and onboarding

Events and alarms

Morning

Report and settings