# CLAUDE.md

## Project

TypeScript/JavaScript project. Customize this section with your own
description, layout, and conventions.

**Typical layout:**
- `src/` — source modules
- `tests/` or `*.test.ts` beside the source — test files
- `package.json` — scripts and dependencies
- `tsconfig.json` — compiler options

## Build & Test Commands

If the project has a Makefile, document targets here. Common pattern:

```bash
make test                   # run the test suite
make coverage               # suite + coverage report
make typecheck              # tsc --noEmit across the project
make lint                   # eslint
make build                  # production build
```

Direct equivalents: `npm test`, `npx tsc --noEmit`, `npx eslint src/`,
`npx prettier --check .`, `node --test`.

## Language Rules

See rule files in `.claude/rules/`:
- `typescript-testing.md` — test conventions and mocking discipline
- `verification.md` — verify-before-claim-done discipline

## Git Workflow

Commit conventions: see `.claude/rules/commits.md` (author identity,
no AI attribution, message format).

Pre-commit hook in `githooks/` scans for secrets and parse-checks staged TS/JS.
Activate on a fresh clone with `git config core.hooksPath githooks`.

## Problem-Solving Approach

Investigate before fixing. When diagnosing a bug:
1. Read the relevant module and trace what actually happens
2. Identify the root cause, not a surface symptom
3. Write a failing test that captures the correct behavior
4. Fix, then re-run tests

## Testing Discipline

TDD is the default: write a failing test before any implementation. If you can't
write the test, you don't yet understand the change. Details in
`.claude/rules/typescript-testing.md`.

## Editing Discipline

A PostToolUse hook parse-checks every TS/JS file after Edit/Write/MultiEdit and
blocks on a syntax error. It covers `.ts`, `.tsx`, `.mts`, `.cts`, `.js`,
`.jsx`, `.mjs`, and `.cjs`.

Two checkers, because one tool can't do both jobs: `node --check` for
JavaScript, `tsc` filtered to syntax diagnostics for TypeScript. Do not
substitute `node --check` for the TypeScript path — it ignores
`--experimental-strip-types`, so it rejects valid TypeScript and accepts broken
TypeScript (measured on node v26.4.0).

Full type checking is not enforced by the hook: it needs the whole project graph
and its dependencies resolved, which is a build-scale operation rather than a
per-keystroke one. Run it via `make typecheck`. Formatting is likewise not
enforced; adopt a style per project in the project's own config.

## What Not to Do

- Don't add features beyond what was asked
- Don't refactor surrounding code when fixing a bug
- Don't reach for `any` to silence a type error — narrow the type instead
- Don't use `==` where `===` is meant
- Don't add comments to code you didn't change
- Don't commit `.env` files, credentials, or API keys — the pre-commit hook
  catches common patterns but isn't a substitute for care