---
name: setup
description: >-
  Add a new form-field validator to this project the right way: derive an EARS
  requirement, implement a pure function returning ValidationResult, and cover
  it with one example test and one property test. Use when the user asks to add
  or change validation rules for a form field.
---

# Adding a validator (Form Validation Guardian)

This power encodes the conventions of this project so a new validator is
consistent with the existing ones. Follow the steps in order.

## 1. Write the requirement first (EARS)

Add a numbered requirement to `.kiro/specs/form-validation/requirements.md`
in EARS form, for example:

> REQ-n: WHEN a user submits a <field> THE SYSTEM SHALL accept it only if
> <condition>.

See `references/ears-cheatsheet.md` for the EARS keywords.

## 2. Implement a pure function

In `src/validators.ts`:

- Signature: `export function validate<Field>(input: string): ValidationResult`.
- No I/O, no mutation of the input. Trim before inspecting.
- Return `ok()` when valid, `fail("<message>")` otherwise.
- Add a doc comment that cites the REQ-n it implements.

## 3. Test it two ways

In `tests/validators.test.ts` add at least one example asserting a known
good and a known bad input. In `tests/validators.properties.test.ts` add a
fast-check property that states a general rule (see
`references/property-patterns.md`), such as "any input missing <required
part> is rejected".

## 4. Verify

Run `npm run lint` and `npm test`. Both must pass before the change is done.