# Development Planning Guidelines

This guide captures the planning and quality expectations expressed by the
current repository documentation and task surface.

## Planning process

### Evaluate requests against the shipped architecture

Before planning work, check:

- whether the behavior already exists in `apps/gateway/routes/*`, `packages/*`,
  or `apps/control-ui/src/*`
- whether the decision log already records the behavior as deferred, shipped, or
  intentionally absent
- whether the change affects the canonical request lifecycle, same-origin UI
  model, PostgreSQL hard dependency, or middleware order

### Write plans in implementation terms

Useful plan anchors in this codebase:

- route files for HTTP behavior
- shared contracts for cross-boundary shape changes
- provider adapters for upstream behavior
- settings, governance, cache, and telemetry packages for cross-cutting work
- control UI views and components for operator-facing behavior

### Break work down by seam

Good task slices in this repo are usually:

- one route family
- one provider adapter or provider capability
- one governance or telemetry behavior
- one control-plane view plus its API contract
- one deployment or observability path

## Development guidelines

### Code review expectations

- Preserve the middleware order unless the change explicitly requires a routing
  or policy move.
- Keep the canonical error envelope intact.
- Do not bypass shared contracts with route-local ad hoc JSON shapes.
- When changing provider, cache, governance, or settings behavior, verify both
  the API surface and the control-plane projection.

### Testing expectations

- Fixed bugs should gain regression coverage in the matching suite.
- Route or contract changes should include the narrowest relevant route,
  integration, or contract test.
- UI changes should include `test-ui` coverage when they affect reusable
  components or view behavior.
- Release-facing changes should be checked against the full gate, not only a
  local slice.

### Documentation expectations

- Update reference docs when routes, settings, environment variables, commands,
  or data shapes change.
- Update concept docs when architectural or security-relevant behavior changes.
- Regenerate the SBOM on dependency changes.

## Best practices

### Performance

- Use `deno task test:load` for end-to-end gateway-over-HTTP measurement.
- Use `deno task bench` for pure-function or micro-benchmark work.
- Treat measure-first performance guidance as a real requirement, not a
  suggestion.

### Security

- Protect `/api/*` in non-local environments with `FROSTY_ADMIN_TOKEN`.
- Respect the fail-closed behavior around PostgreSQL and config encryption.
- Do not widen Deno permissions casually; the current permission set is part of
  the runtime contract.
- Keep secrets out of browser responses and committed files.

### Accessibility

- Follow the control UI conventions around `PageHeader`, keyboard paths, hit
  targets, and shared primitives.
- Keep route-change focus behavior intact.

### Internationalization

- No i18n framework is present in the shipped UI. Any i18n work would be new
  implementation, not an existing extension point.

## Definition of done

- Code or docs match the intended seam and do not fight the repository's core
  architecture.
- Relevant tests or validation commands pass for the changed slice.
- Documentation is updated where the public, operator, or developer contract
  changed.
- For dependency work, the SBOM is regenerated.
- For deployment or observability work, the Compose and runtime implications are
  reflected in the docs.