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 — the executable gates, the single command, and the no-false-pass guarantees.
• 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 — 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 — the detailed rationale for the conditional-rendering and typography rules.

One command to run every gate

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 (static, build, unit, visual, 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.

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 §Forms and data access).