# Contributing & code hygiene

Working rules for anyone (human or AI) changing this repository. Read
[CLAUDE.md](CLAUDE.md) for the architecture and the full conventions; this is
the day-to-day hygiene.

## First-time setup

```powershell
npm run setup            # frontend + e2e dependencies, Playwright browser
npm run db:migrate       # create and seed the app database
npm run db:test          # create the empty database the Go tests use
.\scripts\install-hooks.ps1   # activate pre-commit / pre-push gates
```

`core.hooksPath` is a local git setting — every clone must run the last step.

## Branching & commits

- **Branch from `main`.** Never commit or push directly to `main`; it is
  protected and changes land via pull request.
- One logical change per commit; write a clear subject line (imperative mood)
  and a body explaining the *why*.
- Keep attribution lines as the project specifies for commits and PRs.
- If a push is rejected because the remote moved, **rebase** onto it (keep
  history linear) — do not force-push.

## Code style

- **Go:** `gofmt` and `go vet` must be clean. Wrap errors with `%w` and context.
  SQL only in `repository/`, always parameterised.
- **Angular/TypeScript:** `tsc` clean; Prettier formatting; standalone
  components and signals; services in `core/`. No `any` where a type is known.
- **SCSS:** theme-aware and responsive; no horizontal scroll at 390px.
- **SQL/migrations:** idempotent and re-runnable; tenant tables carry
  `tenant_id` with `ON DELETE CASCADE`.

## Tests are part of the change

- Every behavioural change ships with tests. New behaviour gets a **scenario
  card** in `qa/scenarios/` first (see [`qa/README.md`](qa/README.md)).
- Run the relevant layer before pushing: `.\run-tests.ps1 -Layer <layer>`.
  The pre-push hook runs the unit layers automatically.
- **Never weaken an assertion** to get green. Assert on observable behaviour,
  not implementation.
- Leave data as you found it — a test that creates a booking cancels it.

## Definition of done

A change is done only when **all** hold:

- [ ] Tests for the change pass (`run-tests.ps1` green).
- [ ] For UI/binding work, the evidence report proves the scenario.
- [ ] No secret added; `.env` untouched in the diff.
- [ ] Scope is exactly the task — nothing unrelated.
- [ ] Docs updated if behaviour, API, or conventions changed (incl. this file,
      CLAUDE.md, the wiki).
- [ ] `gofmt`/`go vet`/`tsc` clean.

## File hygiene

- **Never commit:** `.env`/secrets, `node_modules/`, build output
  (`dist`, `bin`, `.angular`), run artifacts (`.testlogs/`, `e2e/results/`,
  `e2e/evidence-report/`, `.run/`), coverage files, PDFs. These are git-ignored;
  keep it that way.
- Do not check in large binaries or generated reports — they are regenerated.
- Keep the docs in sync with the code; a stale wiki is worse than none.

## Destructive actions

Ask before anything hard to reverse or outward-facing (dropping data, force
operations, pushing to a shared remote, deleting). `db:reset` drops the dev
database — expected in dev, never run it against shared data.