Project-SDE-WP-Suite/docs/waves/wave-0.md

Wave 0 — Orientation

Do this before wave 1. Nothing else in the plan should be started until T0.1 is merged.

The item IDs and file references throughout this plan come from a UX review conducted on branch users/directory-super-user, not from a fresh read of the repo you are in. The line numbers were accurate at the time of the review. Confirm them before relying on them.

---

T0.1 — Build the file map

• Items: none (prerequisite)
• Depends on: nothing
• Blocks: every other task
• Surface: documentation only
• Files: creates docs/reference/file-map.md

Do:

Inventory the frontend and record it. The review described html/ as 6 pages, 4 stylesheets, roughly 11,900 lines. Confirm that and write down what is actually there.

For each of the 6 pages record: file path, what it is called in this plan (launcher, SOP wizard, creator, admin, field view, directory/users, login), which stylesheets it loads, which scripts it loads, and whether it renders inside an iframe or hosts one.

For each stylesheet record: path, and which pages consume it.

Then verify these specific references from the review and record the current line number next to each, or mark it NOT FOUND:

Reference	Claim
wp-creation-app.js:1144	alert() reading "Subject and WP Type are required"
wp-creation-app.js:1962-1972	logged-override path for predecessor constraints
work-package-suite-app.js:326	the only beforeunload listener, analytics dwell tracking
work-package-suite-styles.css:322-328	outline: none plus a pale 3px focus glow
work-package-suite-styles.css:336	comment about .field-hint rendering unstyled
console.css:85-87	the contrast fix that was not propagated
admin.js:484-517	language and time localization
server/seed_demo.py	seeding script that does not authenticate

Also record counts, so later waves can prove they went down:

• occurrences of alert(, confirm(, prompt( — review found 79 app-wide, 43 in the creator
• <div and <span elements carrying onclick — review found 12 and 2
• declarations of #0f62fe — review found 4
• .help-tip elements — review found 15
• aria-live regions — review found 0
• pushState calls — review found 0

Do not: change any application code in this task. It is a read and a document.

Done when:

• docs/reference/file-map.md exists and lists all pages, stylesheets and scripts
• every reference in the table above is confirmed with a current line number or marked NOT FOUND
• the seven counts are recorded with the command used to produce each
• any file path used in a later wave file that does not exist is listed under a Discrepancies heading

---

T0.2 — Confirm the app runs and the baseline is captured

• Items: none (prerequisite)
• Depends on: T0.1
• Blocks: every task with a visual done-when
• Surface: local environment
• Files: creates docs/reference/baseline/

Do:

Run the app locally (uvicorn server.app:app against a throwaway SQLite database) and drive the first-run flow: sign in, create a project, SOP wizard, creator, directory, field view.

Capture baseline screenshots at 390px and 1440px for each of the 6 pages into docs/reference/baseline/. Name them <page>-<width>.png. These are the before images every later PR compares against.

While doing this, confirm each of F1 through F6 still reproduces and note it. If one does not reproduce, say so in the PR rather than deleting the task from wave 1.

Do not: fix anything you see. Wave 1 does that.

Done when:

• the app runs locally from a clean database
• 12 baseline screenshots exist (6 pages x 2 widths)
• each of F1–F6 is marked reproduces / does not reproduce, with a screenshot reference
• the exact run command and any setup steps are recorded in docs/reference/file-map.md