# Project Constitution: AI-Augmented Ticketing System

## 1. High-Level Principles

**QA-First Development:** Every feature must be designed with "testability" as a primary requirement. No code is considered "done" until it has associated unit tests and an integration test path. New API routes ship with a corresponding `tests/*.integration.test.ts` in the same commit. Modified routes must have their existing tests updated to cover the new behavior — never leave a test exercising stale logic.

**Never disable or hollow out a failing test.** Commenting out assertions, using `.skip`, or gutting a test body to make the suite green is forbidden. A failing test signals a real problem. Fix the application logic to satisfy the test, or update the test to reflect an intentional behavior change and document why in the commit message. If the correct fix is unclear, surface the issue explicitly — do not silently suppress it.

**Fail-Safe AI:** AI components must always have a deterministic fallback. If an agent fails to classify a ticket, the system must default to a "General" queue and alert a human.

**Traceability:** Every automated action taken by an AI agent within the system must be logged with a `reasoning_trace` for auditing purposes.

---

## 2. Tech Stack & Standards

- **Language:** TypeScript (strict mode mandatory; no `any` without explicit justification)
- **Framework:** Next.js (App Router) — full-stack; API routes and UI in one repo
- **Runtime:** Node.js 22+
- **API Architecture:** RESTful for standard CRUD; Server-Sent Events for real-time agent updates
- **Documentation:** Use JSDoc for public interfaces. Every module must have a README explaining its "AI Hook points."
- **Database:** PostgreSQL with pgvector for semantic search; Drizzle ORM for type-safe queries and versioned migrations

---

## 3. Development Workflow

**Commit Messages:** Follow Conventional Commits (e.g., `feat:`, `fix:`, `docs:`, `refactor:`).

**File Modifications:** Before modifying an existing file, the AI must read the entire file to ensure no breaking changes to the existing logic or state machine.

**State Persistence:** Every session must begin by reading `.claude/session_state.md` and end by updating it.

---

## 4. AI & Agentic Guardrails

**Prompt Isolation:** Keep prompt templates in a dedicated `prompts/` directory. Do not hardcode long prompts inside application logic.

**Rate Limit Awareness:** Design services with exponential backoff for all LLM API calls.

**Human-in-the-loop (HITL):** Any AI action with a "High" impact (e.g., deleting a project, re-assigning 50+ tickets) requires an explicit human `approve()` call.

---

## 5. Repository Structure

```
/src          # Application logic
/tests        # Unit and Integration tests
/docs         # System architecture and user guides
/prompts      # LLM prompt templates
/scripts      # Automation and maintenance scripts
.claude/      # Agent-specific instructions and state
```