# Shared rules

Rules that apply to both backend and frontend work in this repo. Stack-specific
guides (`backend-context.md`, `frontend-context.md`) extend these.

## Process (TDD)

0. Before editing any file, ensure you are on a feature branch
   (`git status` to confirm). If on master/main, create a branch
   first.
1. Write the test first
2. Run the test to confirm it fails
3. Commit the failing test (the "tests committed first" rule in
   action - the test commit precedes the implementation commit, not
   merely the implementation lines)
4. Implement the code to make the test pass
5. Run the test to confirm it passes
6. Commit the implementation
7. Repeat for each new behavior

## Code style

- Lines should not exceed 80 columns, but should use up to 80 columns when
  possible - do not split lines unnecessarily
- Variable names: use explicit, descriptive names - never single-letter or
  abbreviated variables (e.g. `$text` not `$t`, `$node` not `$n`)
- Method/function/constructor parameters: do not use default values - every
  call site must pass every argument explicitly. This eliminates a class of
  bugs where an unintended default silently slips through (e.g. an
  `isAdmin=false` or an empty `passwordHash`). Apply the same rule in tests
  and fakes - if a helper accepts a value, every caller must supply it.
- First, explore the codebase to understand existing patterns - look at similar
  files for reference before writing anything
- Never use em dashes (—) in code, comments, or docblocks - use hyphens (-)
  instead

## Git commit style

- Present tense, imperative mood (add, create, wire, fix, test)
- Lowercase
- Short (3-6 words)
- Match patterns found in git history
- Do not add any section mentioning claude as a coauthor
- Add a commit body when the subject alone cannot convey the change - e.g.
  non-obvious motivation, multi-file coordination, or notable complexity
- Body: wrap at ~72 columns, separated from subject by a blank line, explain
  the why and any non-obvious what
- Skip the body for trivial or self-explanatory commits

## Git commits

- Tests should be committed first, before implementation
- One logical change per commit - a commit may span multiple files when they
  form a single logical unit (e.g. a use case with its request and exception,
  or a template with its page-level JS)
- Keep commits focused: not one file per commit, not unrelated work batched
- Make commits frequent - commit each meaningful logical step as you go
- Commits are for reviewing and documenting the development of code
- When the formatter or linter modifies files outside your intended
  change, either `git restore` them or land them as a separate
  `format <area>` / `lint <area>` commit - never bundle drive-by
  formatter churn into a feature commit
- If pre-commit lint fails on code you did not touch, do not bundle
  the fix - either land the unrelated fix as its own commit first, or
  note the pre-existing failure and proceed

## Branching

- Use kebab-case (e.g. `text-page`, `scheduled-node`, `auth-flow`)
- Use descriptive feature names
- Or use type/description: `feature/text-page`, `fix/bug-name`
- NEVER work directly on master/main - always create and work on a branch

Do not push anything. Make commits as you go.

## Pre-commit checklist

Before EVERY commit (no exceptions), verify each item. Treat this as
mechanical, not aspirational - a "yes" to all is required.

**Branch + scope:**
- [ ] On a feature branch (not master/main).
- [ ] This commit is one logical change. If it spans unrelated changes,
      stop and split it.
- [ ] Tests for new behavior were committed BEFORE this implementation
      (or this commit IS the failing-test commit).

**Code rules** (see `backend-context.md` PHP rules,
`frontend-context.md` JS rules):
- [ ] No arrow functions (`fn () =>`).
- [ ] No inline FQCNs in type hints, return types, or `::class`
      references (`\App\Foo\Bar` -> hoist to `use App\Foo\Bar;`).
- [ ] No default parameter values on methods/functions/constructors.
- [ ] Find/lookup repository methods return new instances, not stored
      references.
- [ ] No em dashes (use hyphens).
- [ ] Variable names are explicit (no `$t`, `$n`, `$res`, etc.).

**Mechanical checks:**
- [ ] `php-cs-fixer fix --config=.php-cs-fixer.dist.php <touched dirs>`
      run, output reports 0 fixes (or any fixes are committed).
- [ ] `./vendor/bin/phpunit tests` is green.

**Commit metadata:**
- [ ] Subject is lowercase, imperative, 3-6 words.
- [ ] No claude/AI coauthor lines.
- [ ] Body present iff the subject alone cannot convey the change.

If any item fails, fix it before committing - do not bundle the fix
into a future commit.