n.siegfried/Project-SDE-WP-Suite
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
03d24138ed343cadfeebc99a4b587a5b438f0e37
Project-SDE-WP-Suite/CLAUDE.md
n.siegfried 3d99d4b9d0 Import the R2 implementation spec into the repo 
The plan was delivered as wp-suite-implementation-spec.zip and lived only in
Downloads, so every "read CLAUDE.md first" instruction in it pointed at a file
the repo did not have. Bring it in unchanged: CLAUDE.md, IMPLEMENTATION.md, and
docs/waves/wave-0 through wave-9 plus backlog.md.

UX-REVIEW-2026-08-14.md is committed alongside it. It is the review that
produced F1-F6, S1-S13 and the A/B/C assessments, and item IDs throughout the
wave files cite it, so it belongs under version control rather than sitting
untracked in the working tree.

No application code changes here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 17:42:56 -05:00

5.1 KiB
Raw Blame History

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.