chore(cursor): add cursor rules for project conventions

.cursor/rules/000-execution-context.mdc

@@ -0,0 +1,22 @@
+---
+alwaysApply: true
+---
+
+# Execution Context Rule
+
+- Always assume the project root is the working directory.
+- When generating scripts or tasks, prefix commands with paths relative to the repo root (e.g., `./cmd/foo`, `./internal/...`).
+- Do not hardcode `$HOME` paths; always use relative-to-root.
+- When showing a `make` or `go` command, assume execution from the root:
+  - `make test`
+  - `go run ./cmd/myapp`
+  - `go generate ./...`
+# Execution Context Rule
+
+- Always assume the project root is the working directory.
+- When generating scripts or tasks, prefix commands with paths relative to the repo root (e.g., `./cmd/foo`, `./internal/...`).
+- Do not hardcode `$HOME` paths; always use relative-to-root.
+- When showing a `make` or `go` command, assume execution from the root:
+  - `make test`
+  - `go run ./cmd/myapp`
+  - `go generate ./...`

.cursor/rules/001-task-execution-overrides.mdc

@@ -0,0 +1,9 @@
+# Task Execution Overrides (Project Rule)
+
+## When running `/task` on any item:
+- If the task is a code/config change, **also create**:
+  - A **Unit Test sub-task** with file paths and test names.
+  - An **Integration Test sub-task** (or a short rationale if N/A).
+
+
+

.cursor/rules/002-testing-first-principles.mdc

@@ -0,0 +1,17 @@
+# Planning/Test Culture Overrides (Project Rule)
+
+## Global Planning Requirements
+1) After “Set up development environment & framework”, the **next task MUST be**:
+   **“Set up the test framework & test environment”**.
+   - Pin test runner (e.g., `go test`), structure (`/internal/...`, `/pkg/...`), fixtures folder, golden files, and CI entrypoints.
+
+2) For **every task in the plan that produces code or config**, add two sibling tasks:
+   - **Unit Tests:** “Add/extend unit tests for <task-deliverable>”
+   - **Integration Tests (if feasible):** “Add/extend integration tests for <task-deliverable>”
+   - If integration testing is **not applicable**, add a sub-bullet: “State why integration test is not applicable and what observable we will monitor instead.”
+
+3) Keep tests **in the same PR** as the code unless explicitly labeled `[defer-tests]`.
+
+## Plan Formatting Rules
+- Numbered tasks. Each code task is immediately followed by its test tasks.
+- Each task includes: **Goal**, **Definition of Done**, **Artifacts**, **Owner(optional)**.

.cursor/rules/010-conventional-branch.mdc

@@ -0,0 +1,48 @@
+---
+description: Creating Git branches
+alwaysApply: true
+---
+# Conventional Commits (MDC)
+
+```yaml
+name: conventional-branch
+applies_to: git, commits, pr_titles
+goal: Enforce and auto-draft Conventional Branch v1.0.0 branch names
+author: chatgpt
+version: 1.0.0
+```
+
+# Conventional Branch Naming
+
+**Purpose**: Guides the AI to use the Conventional Branch naming standard for all new Git branches.
+
+**Principle**: All new branches must follow the `type/description` format. The description should be concise and use kebab-case.
+
+**Example Branch Names**:
+
+* `feat/add-new-user-auth`: For new features or enhancements.
+* `bugfix/resolve-login-bug`: For fixing bugs in the code.
+* `hotfix/resolve-production-issue`: For urgent fixes to production issues.
+* `release/v1.2.0`: For preparing and testing new releases.
+* `chore/upgrade-dependencies`: For non-code-related tasks, such as updating dependencies or documentation.
+* `docs/update-readme`: For documentation-related changes.
+* `style/reformat-dbt-yml`: For code style changes that don't affect the logic.
+* `refactor/improve-payment-flow`: For code refactoring without changing functionality.
+
+**Rule Details**:
+- **Type**: Must be one of `feat`, `bugfix`, `hotfix`,`docs`, `chore`, `style`, `refactor`,`release`, `test`, `perf`, or `ci`.
+- **Scope (Optional)**: If the change is limited to a specific part of the codebase, include it as `type(scope)/description`.
+- **Description**: A short, kebab-cased summary of the changes.
+  - Use Lowercase Alphanumerics, Hyphens, and Dots
+  - No Consecutive, Leading, or Trailing Hyphens or Dots
+  - Include Ticket Numbers: : If applicable, include the ticket number from your project management tool to make tracking easier. For example, for a ticket issue-123, the branch name could be feature/issue-123-new-login.
+  - 
+
+**AI Directive**:
+When a new branch is being created, ensure the name conforms to the `type/description` or `type(scope)/description` format. Refer to the Conventional Branch specification and remind the user to follow this standard.
+
+## References
+
+- Conventional Branch v1.0.0 — Summary and rules.  
+
+

.cursor/rules/011-conventional-commits.mdc

@@ -0,0 +1,179 @@
+---
+description: Enforce and auto-draft Conventional Commits v1.0.0 messages for commits and PRs
+alwaysApply: true
+---
+# Conventional Commits (MDC)
+
+```yaml
+name: conventional-commits
+applies_to: git, commits, pr_titles
+goal: Enforce and auto-draft Conventional Commits v1.0.0 messages
+author: chatgpt
+version: 1.0.0
+```
+
+## Summary (what to do)
+
+- Always format commit headers as:
+  ```
+  <type>(<scope>)!?: <short description>
+  ```
+  - `<type>`: one of `feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert`
+  - Optional `<scope>`: a noun describing the area (e.g., `api`, `db`, `ui`, `auth`, `repo`, or a package name).
+  - Optional `!` right after type/scope indicates a breaking change.
+  - `<short description>` is imperative, concise, no trailing period, ideally ≤ 72 chars.
+- Optional body (wrapped at 72 cols) explains **what** and **why**, not **how**.
+- Optional footer(s) for metadata:
+  - `BREAKING CHANGE: <explanation>` (required if using `!` or if breaking without `!`)
+  - Issue refs: `Closes #123`, `Refs #456`
+  - Co-authors, etc.
+
+## Allowed types (choose the *most* specific)
+
+- `feat`: a new user-visible feature
+- `fix`: a bug fix
+- `docs`: documentation only
+- `style`: code style only (formatting, no logic)
+- `refactor`: code change that neither fixes a bug nor adds a feature
+- `perf`: performance improvement
+- `test`: add/adjust tests only
+- `build`: build system or external dependencies
+- `ci`: CI configuration/scripts
+- `chore`: other tasks (no src/test changes)
+- `revert`: reverts a previous commit (use `revert: <header of reverted commit>` in body)
+
+## Assistant behavior (Cursor)
+
+When asked to generate or review a commit message:
+
+1. **Collect minimal facts** (if missing from the diff or user note):
+   - What changed? (Feature, fix, docs, etc.)
+   - Scope? (package/module/area)
+   - Breaking change? (yes/no; if yes, why + migration notes)
+   - Related issue(s)? (`#id` or links)
+2. **Propose** a header, then a succinct body and optional footers.
+3. **Validate** against rules and fix automatically.
+4. **Offer variants** (e.g., with/without scope; with `!` vs footer).
+
+## Lint rules (hard)
+
+- Header MUST match:
+  ```
+  ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?(!)?: [^\s].+$
+  ```
+- If `!` is present **or** change is breaking → include a `BREAKING CHANGE:` footer describing the impact and migration.
+- Header description ≤ 72 chars (aim); body lines ≤ 72 chars.
+- No trailing period in header.
+- Avoid capitalizing the first word of the description unless a proper noun.
+- Use present/imperative mood (“add”, “fix”, “update”, not “adds/added/fixes/fixed/updated”).
+
+## Commit templates
+
+### Standard change
+```
+<type>(<scope>): <short imperative summary>
+
+<wrapped body explaining what & why; optional>
+
+Refs #<id>
+Closes #<id>
+```
+
+### Breaking change (two equivalent ways)
+
+**A. Exclamation mark in header**
+```
+<type>(<scope>)!: <short imperative summary>
+
+<details about why it's breaking, migration notes>
+
+BREAKING CHANGE: <concise explanation of the breaking aspect and migration>
+Closes #<id>
+```
+
+**B. No `!`, explicit footer**
+```
+<type>(<scope>): <short imperative summary>
+
+<details>
+
+BREAKING CHANGE: <explanation + migration>
+```
+
+### Revert
+```
+revert(<scope>): revert "<original header>"
+
+This reverts commit <hash>.
+```
+
+## Examples (good)
+
+- feat(api): add pagination to listOrders
+- fix(db): handle null warehouse_id in shipment view
+- refactor(core): extract OperationResult to shared module
+- perf(query): reduce N+1 selects in person loader
+- docs(readme): clarify setup for dev containers
+- build(deps): bump neo4j-driver from 5.19 to 5.20
+- ci(actions): cache dbt deps to speed up pipeline
+- chore(repo): normalize .editorconfig for SQL files
+- feat(auth)!: require MFA for admin routes  
+
+```
+Enforce MFA for all endpoints under /admin/*.
+
+BREAKING CHANGE: Admin API clients must obtain TOTP codes. See docs/admin-mfa.md for migration steps.
+Closes #742
+```
+
+## Common mistakes (and fixes)
+
+- **Bad:** Fixed bug in parser  
+  **Good:** fix(parser): avoid infinite loop on empty token
+
+- **Bad:** feat: Added New Endpoint.  
+  **Good:** feat(api): add new /healthz endpoint
+
+- **Bad:** refactor: move stuff  
+  **Good:** refactor(storage): isolate blob client factory
+
+## 🔎 Review checklist (apply automatically)
+
+- [ ] Type is valid and most specific.
+- [ ] Optional scope meaningfully narrows the change.
+- [ ] Header has no trailing period; description is imperative and succinct (≤ 72).
+- [ ] Body explains “why” and notable “what”; no code-dump.
+- [ ] Breaking? `!` or `BREAKING CHANGE:` footer present with migration notes.
+- [ ] Issues referenced with `Closes #id` / `Refs #id`.
+- [ ] No unrelated changes bundled; suggest splitting if necessary.
+
+## Quick classification guide
+
+- New endpoint/flag/CLI option → `feat`
+- Bug fix or regression → `fix`
+- Only docs/readme/specs → `docs`
+- Whitespace, formatting, naming (no behavior) → `style`
+- Internal restructure (no feature/bug) → `refactor`
+- Faster/less memory → `perf`
+- Tests only → `test`
+- Build tooling, deps, Docker, Makefile, Azure Pipelines → `build`
+- CI pipelines, workflows → `ci`
+- Repo maintenance, scripts, housekeeping → `chore`
+- Undo a specific commit → `revert`
+
+## Monorepos & scopes
+
+- Use package/app/folder names as scope: `feat(app-web)`, `fix(pkg-sql)`, `build(dbt)`.
+- For cross-cutting changes, prefer a broad scope like `repo`, `core`, or list the dominant area.
+
+## PR title policy
+
+- Use the same Conventional Commit header as the **PR title**.
+- If a PR contains multiple commit types, title it by the **primary user-visible change** (`feat` beats `fix` beats others). Use labels for the rest.
+
+## References
+
+- Conventional Commits v1.0.0 — Summary and rules.  
+  Types, `!` for breaking, and `BREAKING CHANGE:` footer are derived from the spec.
+
+