# Project Rules

## Environment
- No git worktrees. Work inside the VS Code Dev Container (`.devcontainer/`).
- On "proceed" or session start: read `.claude/session_state.md` first.
- Container has limited memory — prefer Turbopack; watch for OOM before debugging hydration/auth.
- `DATABASE_URL` is baked into the container. Verify with `echo $DATABASE_URL` before seeds. Pass overrides inline: `DATABASE_URL="..." TENANT_CONFIG_PATH="..." pnpm db:seed`.
- Tenant name: `Confluent-CR` (hyphenated).
- Before debugging UI/auth/hydration: check container memory, dev server health, and `DATABASE_URL` first.

## Response Style
- Concise. No trailing summaries. No recap bullets unless asked.

## Session State
For typical small chores, tasks, and bug fixes, keep `.claude/session_state.md` empty.

Only write `.claude/session_state.md` when doing phased work such as "phase N of M" or a large feature spec/implementation in one shot. When session state is warranted, overwrite it with:
- **Objective** — high-level goal this session
- **Done** — completed steps (file paths, decisions)
- **Queue** — what's next, in order
- **Context** — gotchas and non-obvious constraints

## Development Workflow
- Conventional Commits: `feat:` `fix:` `docs:` `refactor:` `test:` `chore:`
- Read files in full before editing — never edit blind.
- Run `pnpm type-check && pnpm test` after any logic change; don't mark done if either is red.
- No concurrent `pnpm lint` + `pnpm build` — run sequentially.
- Prompt templates live in `prompts/`. Never hardcode long prompts in code.
- Clarify ambiguous requests before starting — don't guess and revert.
- Edit existing files; never create a new variant when one already exists.
- Medium/large features: write a spec doc in `docs/` first (ordered punchlist, clear done criteria).
- With a spec: follow `/tdd-from-spec` (`.claude/skills/tdd-from-spec/SKILL.md`) — failing tests (unit + integration + e2e) before implementation; full suite green twice before stopping.
- When using generic hooks (`useSyncExternalStore`, `useReducer`, etc.) always add an explicit return type annotation — TypeScript inference can widen union types silently under `next build`.

## Commit & Push Policy
- Never commit or push unless explicitly asked.
- Never auto-create placeholder/config files (e.g. `*.config.prod.yaml`) unprompted.
- Stop after completing a numbered session/task — don't auto-start the next.
- Commit message: concise one-line title, blank line, bulleted summary of changes.

## Deploy Model
- Production deploys are gated by `.github/workflows/deploy.yml`: migrations run first via `drizzle-kit migrate` (using `POSTGRES_URL_NON_POOLING`), then the Vercel deploy hook is triggered.
- `vercel.json` `ignoreCommand` is `exit 0` — Vercel's Git integration is fully disabled; all deploys go through the workflow.
- The Vercel build-time migration script (`scripts/migrate-for-vercel-build.ts`) remains as a fallback — it is a no-op once migrations have already been applied.
- Required GitHub secrets: `POSTGRES_URL_NON_POOLING` (direct DB URL), `VERCEL_DEPLOY_HOOK` (from Vercel dashboard → Settings → Git → Deploy Hooks).

## Testing
Every server-side change ships with tests in the same commit — non-negotiable.

**Requires a test:**
- New/modified API route → `tests/<feature>.integration.test.ts` (follow `respond-with-s-fields.integration.test.ts`)
- State machine change → update `tests/ticket-state-machine.test.ts`
- Config schema change → add cases to `tests/tenant-config-loader.test.ts`
- Inngest agent change → mock-LLM integration test (follow `completeness-agent.integration.test.ts`)

**No new test file needed:** pure UI/client components, email templates, config YAML values.

**Rules:**
- Curly apostrophes (`'` `'`) in schema strings break esbuild — use straight quotes.
- Never hollow out a failing test. Fix the code or update the test intentionally and explain in the commit.
- If a route already has a test, update it to cover the new behavior — don't leave it testing stale logic.

## Project References
- Architecture/schema: `docs/technical_spec.md`
- MVP scope: `docs/archive/mvp_punchlist.md`
- Standards: `.claude/project_rules.md`
- Tenant config: `tenant.config.yaml`

## Language
American English throughout. Prefer: organization, behavior, color, canceled, customize, analyze.

## Notifications
Ping via ntfy: `source .claude/ntfy.env && curl -s -d "$MESSAGE" "$NTFY_SERVER/$NTFY_TOPIC"`
If `.claude/ntfy.env` is missing, ask for the topic first.