# Rewrite Agent Rules

These rules apply when implementing the Next.js rewrite on the `rewrite/next` branch.

## Checklist Tracking

`CHECKLIST.md` uses three checkbox states:
- `[ ]` — pending and **required**; blocks the next phase
- `[x]` — done
- `[~]` — optional or deferred; **never blocks phase advancement**

Rules:
- The ✅ column is yours; the ✔️ column belongs to the review agent.
- After completing each numbered item, mark its ✅ box by changing `[ ]` to `[x]`.
- If you complete an optional item (`[~]`), change it to `[x]`. If you skip it, leave it as `[~]`.
- Before starting any item in a new phase, read `CHECKLIST.md` and confirm that every **required** (`[ ]`/`[x]`) item in all preceding phases has `[x]` in both ✅ and ✔️. Items marked `[~]` in both columns do not need to be completed first.
- If any required box in a previous phase is unchecked, stop and report which items are blocking progress instead of proceeding.

## Rewrite Context

- `REWRITE_PLAN.md` is the guiding plan for the migration from the current CRA + Express app to a Next.js App Router + TypeScript app.
- When working on the rewrite, follow the migration phases in `REWRITE_PLAN.md` unless the user explicitly asks for a different order.
- Treat each numbered migration item as a checkpoint: implement it, update its ✅ box in `CHECKLIST.md`, add or update tests, run the relevant verification, then continue.
- Prefer building the new Next.js structure in parallel until feature parity is proven. Do not delete `server/`, `oebb-planner-app/`, or `oebb-planner.jsx` before equivalent Next.js behavior is implemented, tested, and the user has clearly asked for cleanup.
- Preserve existing API contracts and user-visible behavior during migration unless the rewrite plan or user request explicitly changes them.
- Use `npm` consistently because the existing project uses `package-lock.json`.

## Work Step By Step

- Start by reading the relevant files and identifying the smallest safe next step.
- State the plan before making non-trivial changes.
- Implement one coherent change at a time.
- After each step, review the diff and check whether it still matches the intended behavior.
- Do not move on to the next step while the current step has unresolved compile errors, failing tests, or obvious regressions.
- Prefer small, targeted edits over broad rewrites.
- Preserve existing behavior unless the user explicitly asks to change it.
- When a task spans multiple rewrite phases, complete one vertical slice at a time where practical: type or library code, route or hook, UI integration, tests, then verification.
- Keep reusable logic in `src/lib`, side effects in hooks or route handlers, and shared contracts in `src/types`.

## Testing Requirements

- Add or update tests for every new feature, bug fix, and behavior change.
- Put tests near the code they cover and follow the existing test style.
- Cover the main success path, important edge cases, and failure behavior.
- Do not remove or weaken tests just to make the suite pass.
- If a change cannot reasonably be tested, explain why and add the closest practical verification.
- For the Next.js rewrite, prefer unit tests for `src/lib`, route tests for `src/app/api`, and component smoke or behavior tests for UI components.
- Mock external services in automated tests, including ÖBB HAFAS, Nominatim, OSRM, geolocation, time, and calendar downloads. Do not make tests depend on live network availability.
- Test TypeScript data shapes and boundary parsing where API responses are transformed into app types.

## Verification Before Moving On

- Run the narrowest relevant tests after each meaningful change.
- Run the broader project checks before finishing.
- For server changes, run:

```bash
cd server
npm test
```

- For React app changes, run:

```bash
cd oebb-planner-app
CI=true npm test -- --watchAll=false
npm run build
```

- For the Next.js rewrite, once the root Next.js project exists, run the relevant root checks instead:

```bash
npm test
npm run build
```

- If available, also run type-checking and linting scripts before finishing:

```bash
npm run typecheck
npm run lint
```

- If a change touches both server and app behavior, run both sets of checks.
- If a command fails, stop, inspect the failure, fix the cause, and rerun the command.
- Do not claim the work is complete until the relevant checks pass, or until the remaining blocker is clearly reported.

## Quality Bar

- Make sure additions do not introduce compile errors, lint errors, runtime crashes, or broken imports.
- Check that public APIs, endpoint contracts, props, and data shapes remain compatible with existing callers.
- Keep error handling explicit and user-facing failures understandable.
- Avoid hidden global state, timing assumptions, and network-dependent tests unless the project already uses that pattern.
- Keep dependencies unchanged unless they are necessary for the task and justified.
- Do not commit generated artifacts, caches, logs, or local environment files.
- Keep TypeScript strictness intact once introduced. Do not use `any` as a shortcut around unclear domain types.
- Keep server-only code out of client components. Route handlers and `src/lib` clients that use secrets, privileged headers, or upstream service details must not be imported into browser-only code.
- Respect Nominatim usage requirements when implementing geocoding: configurable base URL, clear user agent, rate-limit-aware caching, and no direct browser calls to the public service.
- Keep OSRM and HAFAS clients behind API routes or server-side utilities so failures can be normalized and tested.
- For UI work, preserve accessibility basics: semantic buttons and links, labels for inputs, keyboard-operable controls, visible loading and error states.

## Completion Checklist

Before finishing a step, confirm:

- The requested behavior is implemented.
- The ✅ box for the corresponding item in `CHECKLIST.md` is checked.
- The change matches the relevant phase or numbered item in `REWRITE_PLAN.md`, when applicable.
- Tests were added or updated where appropriate.
- Relevant tests and build checks pass.
- The change is scoped to the request.
- No unrelated user changes were overwritten.
- Old implementation files were not removed unless parity is tested and cleanup was requested.
- Any limitations or skipped checks are reported clearly.