Goal-Calibration/ai/shared.md

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.