# Engineering standards

## Repository shape

Target:

```text
apps/
  web/
  api/
  worker/
  agent/
packages/
  contracts/
  ui/
  test-fixtures/
internal/
  domain modules or Go internal packages
config/
deploy/
tests/
docs/
artifacts/evidence/
```

Codex may refine the shape through an ADR, but privilege boundaries and clear ownership must remain.

## General

- Optimize for correctness, observability and maintainability.
- Keep changes vertically complete.
- Validate external inputs at boundaries.
- Avoid global mutable state.
- Use deterministic IDs/fingerprints where required.
- Use UTC internally.
- Add correlation IDs to request/job/event paths.
- Preserve error causes and add context.
- Never log secrets.
- Use feature flags only when they have an owner, default and removal plan.

## Git and commits

- Focused commits aligned to task IDs.
- Commit message format: `<TASK_ID>: <imperative summary>`.
- Do not rewrite shared history.
- No force push or destructive reset.
- Keep generated evidence out of commits only when too large; summaries remain.
- Tag releases only after final acceptance.

## Go

- Current supported stable Go version selected during M0 and recorded.
- `go fmt`, `go vet`, static analysis and tests required.
- Context propagated through I/O boundaries.
- Errors wrapped with operation context.
- Interfaces defined near consumers; avoid interface proliferation.
- Goroutines have ownership, cancellation and bounded lifetime.
- Worker jobs are idempotent.
- SQL is parameterized; transactions explicit.
- Migrations are forward/recovery tested.
- HTTP handlers contain no core domain logic.

## TypeScript/React

- Strict TypeScript.
- No `any` except narrow justified boundary adapters.
- Runtime validation for external JSON.
- Components separate data orchestration from presentation.
- Server state uses a deliberate query/cache layer.
- Live chart buffers do not live in broad global state.
- Effects are cancellable and cleanup subscriptions.
- Accessible semantic HTML first.
- All user copy goes through localization.
- Avoid giant components and prop drilling; centralize domain-specific hooks appropriately.

## API and contracts

- OpenAPI/JSON Schema is validated in CI.
- Breaking changes are versioned.
- Generated types are reproducible.
- Error codes are stable.
- Pagination, filtering and sorting are bounded.
- Every endpoint has authz tests.
- WebSocket messages are schema validated.

## Database

- Explicit migrations, no startup auto-mutation outside migration command.
- Indexes justified by access path.
- Constraints enforce invariants where practical.
- JSONB payloads have size/schema limits.
- Optimistic concurrency for user-edited versioned resources.
- Timeouts and connection pool limits.
- Test upgrade, restart, backup and restore.

## Configuration

- `.env.example` documents non-secret values.
- Startup validates configuration and reports all invalid fields.
- Secrets use secret files/runtime injection when possible.
- No environment-specific values embedded in images.
- Production and test compose overrides are separate.
- Feature capability detection is visible in UI/system status.

## Observability

Pulse emits:
- structured logs;
- internal metrics;
- health/readiness;
- job status;
- trace/correlation IDs;
- redacted upstream error classes.

Avoid recursive monitoring dependence: an external dead-man check must detect total Pulse failure.

## Documentation

Behavioral changes update:
- relevant specification;
- API/schema;
- runbook if operational;
- evidence;
- current state;
- ADR when architectural.