shoc-frontend-new/AGENTS.md

# AGENTS.md — frontend mandatory conventions

This file is the binding entry point for **every contributor — human or AI coding
or review agent** — working in this repository (`seahaven-new-app`, the SHOC
frontend). It makes the validated React/TypeScript conventions mandatory and
points to the operational documents and executable gates that enforce them.

Read these before writing or reviewing code. They override generic "best
practice" suggestions from any agent or model. This repository contract may
strengthen, but never weaken, the workspace-level `AGENTS.md`.

- [QUALITY_GATES.md](QUALITY_GATES.md) — the executable gates, the single
  command, and the no-false-pass guarantees.
- [ARCHITECTURE_AND_CODE_QUALITY.md](ARCHITECTURE_AND_CODE_QUALITY.md) — the
  MUST / MUST NOT conventions (conditional rendering, typography, forms, state,
  data access, security, maintainability) with evidence and thresholds.
- [REVIEW_AND_PR_FRAMEWORK.md](REVIEW_AND_PR_FRAMEWORK.md) — the PR review
  contract (exact-head review, board regression inventory, behavior-based
  testing, security/performance/Big-O review, no style-only comments).
- [docs/FRONTEND_MAINTAINABILITY.md](docs/FRONTEND_MAINTAINABILITY.md) — the
  detailed rationale for the conditional-rendering and typography rules.

## One command to run every gate

```bash
npm run verify
```

This chains the full set: Prettier check, ESLint (`--max-warnings=0`), TypeScript
build (`tsc -b && vite build`), unit tests (`vitest run`), and the governance
checks (`npm run governance`), including G13 app/Terraform isolation. **Do not
claim a task is done until `npm run verify` is green locally.** CI runs the same
gates as parallel jobs in [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml)
(`static`, `build`, `unit`, `visual`, `browser-smoke`, `governance`) with
`ci-complete` failing if any of those jobs did not succeed.

## Non-negotiable rules (enforced; do not work around)

These are already enforced by lint/build or the governance script. Disabling,
baselining, or per-line-suppressing them is forbidden (see exceptions below).

- **No one-sided `cond ? <Element/> : null`** — use `&&` or the `when` prop.
- **The left operand of `&&` in JSX must be entirely boolean** — coerce with
  `Boolean(...)` / an explicit comparison; `{count && ...}` is rejected.
- **Shared `Text` for `p` / `h1`–`h6` / error typography** — raw `<p>`/`<h*>` and
  the `vp-error` class outside `Text` are rejected.
- **Zero lint warnings** — `--max-warnings=0` makes a warning a failure; fix it,
  do not silence it.
- **Hooks correctness** — the `react-hooks` recommended rules (including
  `exhaustive-deps`) run under the zero-warnings gate.
- **Godfile ratchet** — no source file may exceed 500 lines. Existing named debt
  has a frozen per-file cap that may only decrease.
- **Changed-file maintainability** — changed TS/TSX must meet
  `complexity ≤ 20`, function `≤ 150` lines, `≤ 4` params, `≤ 4` depth.

## How to add / change a convention

1. Land it **green**: a new or tightened rule must ship with the codebase passing
   it (a migration in the same change), not as a warning-only backlog.
2. If legacy would break, use changed-file enforcement or migrate it. Do not add
   new baseline debt or raise a frozen cap.
3. Document the rule, its threshold, and its evidence in
   [ARCHITECTURE_AND_CODE_QUALITY.md](ARCHITECTURE_AND_CODE_QUALITY.md).

## Exceptions and the ADR process

Exceptions are **not granted by disabling a rule inline**. To deviate:

1. Record an **Architecture Decision Record** under `docs/adr/`
   (`NNNN-title.md`: context, decision, consequences, alternatives).
2. Existing grandfathered entries may only be removed or have their caps
   reduced. New entries and cap increases fail the governance gate.
3. Get it reviewed like any other change. The ADR + baseline entry is the
   auditable record; an `eslint-disable` comment is not.

## Toolchain (do not change without an ADR)

React 19, TypeScript 6, Vite, Tailwind 4 + MUI, TanStack Query, React Hook Form +
Zod, Ky. Node ≥ 22.22.1 (CI runs Node 24); npm 11.16.0 (pinned via
`packageManager`, invoked through corepack). **No new dependencies without an
ADR** — prefer the libraries already established (see
[ARCHITECTURE_AND_CODE_QUALITY.md](ARCHITECTURE_AND_CODE_QUALITY.md) §Forms and
data access).