Project-SDE-WP-Suite/CLAUDE.md

# Working rules — Work Package Suite

This repo is being changed against a fixed spec. Read `IMPLEMENTATION.md` before starting
any task, and read the wave file for the task you are on. Do not work from this file alone.

## The spec is the source of truth

Every change traces to an item ID (`CR-001`, `F1`, `S1`, `A1`, `B1`, `C1`). If you are about
to make a change that has no ID, stop. Either it belongs to an existing item and you should
say which, or it is out of scope and should be logged in `docs/waves/backlog.md` instead of
built.

Do not renumber, merge, or reinterpret item IDs. They are referenced in documents outside
this repo that other people are reading.

## Scope discipline

- **One task per PR.** Task IDs are `T<wave>.<n>`. Reference the task ID and the item IDs in
  the commit message and PR title.
- **Do not fix things you notice in passing.** The codebase has known problems documented as
  S1 through S13, all scheduled. Fixing S6 while doing T3.2 makes the diff unreviewable and
  breaks the wave ordering. Log it, move on.
- **Do not reorder waves.** The ordering is dependency-driven and documented in
  `IMPLEMENTATION.md` section 4. Waves 1 through 4 are prerequisites: they produce almost no
  visible change and every later wave assumes them.
- **Do not start a wave until the previous wave is merged**, unless the task explicitly says
  it is independent.

## Frontend and backend boundary

The UX review that produced F1-F6 and S1-S13 covered `html/` only. Several change requests
need server work and will be silently half-built if you treat them as frontend-only:

| Item | Needs server work |
|---|---|
| CR-004, CR-018 | Structured location storage and aggregate endpoints. Not localStorage. |
| CR-007 | File upload, storage, and retrieval for drawing attachments. |
| CR-011, CR-014 | Outbound email and a durable link target per work package. |
| CR-013 | Material request persistence. |
| B4 | Aggregate endpoints replacing localStorage-derived counts. |

If a task touches one of these and you find yourself writing to `localStorage`, you are
building the wrong thing. Say so and stop.

## Things that must not change

These are recorded decisions, not oversights. Do not "clean them up":

- **Actual Hours stays in Closeout (CR-017).** Its removal was proposed and rejected.
- **Localization stays (A7).** `admin.js` language and time handling is a shipped feature.
- **Uppercase card headers in `console.css` stay (A5).** The sentence-case rule applies to
  buttons and field labels only. The uppercase header idiom is deliberate.
- **The logged-override path for predecessors stays (A1).** It is an audited business rule,
  not a bug. See `wp-creation-app.js:1962-1972`.
- **Removed fields are hidden, not deleted (CR-002, CR-016).** Retain the data and the model.
  Removal is expressed through the CR-006 section toggles.

## The token rule

After wave 3 there is exactly one place a color, spacing or type value is defined. Page
stylesheets alias that source and declare nothing new.

Adding a raw hex value to a page stylesheet is a defect regardless of what the task asked
for. Four parallel token systems is what produced S5, and the `.field-hint` comment at
`work-package-suite-styles.css:336` is the bug that resulted. Do not recreate it.

## Accessibility is in scope

Approved Aug 14, 2026 (C1). Any component you rebuild ships accessible or it is not done:

- Interactive elements are `<button>`, `<a>`, or an input. Never a `<div>` with `onclick`.
  There are currently 12 `<div>` and 2 `<span>` click handlers app-wide; do not add a 15th.
- Anything conveying instructions is reachable by keyboard and by touch. Hover-only is not
  acceptable — Field View runs on tablets.
- Status changes and toasts announce through an `aria-live` region. `login.html` already does
  this correctly with `role="alert"` and `role="status"`. Copy that pattern.
- Focus is always visible. Do not use `outline: none` without a replacement of at least equal
  visibility.
- Text meets 4.5:1 against its background, 3:1 for large text.

## Verification

A task is not done because the code is written. Every task file lists its own done-when
checks. In addition, for any task touching the frontend:

1. Run the app locally: `uvicorn server.app:app` against a throwaway SQLite database.
2. Exercise the affected flow at **390px** and at **1440px**. Field View at 390px is the
   gloved-hands surface and is where the worst rendering was found.
3. Capture before and after screenshots into the PR.
4. Run the existing smoke test. It signs in; `server/seed_demo.py` does not, which is S13.

If a done-when check cannot be verified, do not mark the task complete. Say which check
failed and why.

## Asking versus assuming

The four gating decisions are closed and recorded in `IMPLEMENTATION.md` section 2. Nothing
else in the spec is a decision waiting to be made.

Where a task says "confirm with Nick", that is a product question, not an implementation
blocker: build to the written acceptance criteria, and raise the question in the PR
description. Do not invent a different behavior because the written one seems incomplete.