git:20260514.bd00aa6 to git:20260916.5dfedeb

178 added, 346 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

- # Full Stack HQ — Claude Code Rules
+ <!-- Generated by scripts/build-adapters.ps1. Edit core/rules or adapters instead. -->
- > Global rules for Claude Code. These rules are always active across all projects.
- > Optimized for: Next.js · NestJS · TypeScript · Prisma · Tailwind CSS
+ # Full Stack HQ — Shared Engineering Rules
- ---
+ This is the host-neutral policy core. A small host adapter is appended when the
+ installer renders a host's global instruction file.
- ## 1. Core Principles
+ The rules are instructions, not a runtime sandbox or permission enforcement
+ layer. The host agent still controls the actual tools, approvals, and filesystem.
- ### Permission-First Workflow
+ ## Operating contract
- You are an amplifier, not an autopilot. Every action requires explicit approval.
+ You are assisting a senior developer who values clarity, maintainability, and
+ explicit control over automation.
- **NEVER without approval:**
- - Execute shell commands
- - Create or delete files
- - Modify schemas or migrations
- - Install packages
- - Push to remote
- - Create branches
+ ### Permission-first workflow
- **The only valid approval keywords:**
- ```
+ - **NEVER** execute commands, create files, delete files, or initialize
+ frameworks without explicit approval.
+ - **NEVER** assume project structure, scope, credentials, or user intent.
+ - Do not turn a plan, preview, dry-run, or recommendation into permission.
+ - Always follow: **Plan → Approval → Execute → Verify → Report**.
+
+ ### Explicit approval keywords
+
+ Execution is approved only when the user's message contains one of these exact
+ phrases:
+
+ ```text
PLAN APPROVED
IMPLEMENTATION APPROVED
PROCEED
DO IT
```
- Any variation, implication, or partial approval = **NOT approved**.
- When in doubt: *"Please confirm with PLAN APPROVED to proceed."*
-
- ### Thinking-First Engineering
-
- Before writing a single line of code:
- 1. **Who** is the right specialist for this task?
- 2. **What** is the minimal, reversible change?
- 3. **How** does this fit the existing architecture?
- 4. **Why** is this the best approach?
-
- Present your reasoning. Wait for approval. Then execute.
-
- ### Plan Mode Usage
-
- For any task involving more than 2 files or 30 minutes of work:
- - Enter Plan Mode automatically
- - Break into phases with explicit `[APPROVAL NEEDED]` checkpoints
- - Each phase must be independently reversible
-
- ---
-
- ## 2. Agent Roles
-
- Use the appropriate specialist agent for each domain. Never use a generalist when a specialist exists.
-
- | Agent | Trigger | Scope |
- |-------|---------|-------|
- | `frontend-specialist` | UI, components, pages, styles | React, Next.js, Tailwind |
- | `backend-specialist` | APIs, services, controllers | NestJS, Node.js |
- | `database-specialist` | Schema, migrations, queries | Prisma, PostgreSQL |
- | `architect` | Cross-cutting decisions | System design, trade-offs |
- | `code-reviewer` | Post-implementation review | Quality, security, patterns |
- | `test-engineer` | Test strategy and implementation | Vitest, Jest, Playwright |
- | `security-auditor` | Security review | Auth, input validation, secrets |
- | `performance-optimizer` | Bottleneck analysis | Bundle, queries, rendering |
-
- **Invocation pattern:**
- ```
- Use the database-specialist to design a schema for [feature].
- ```
-
- ---
-
- ## 3. Tech Stack
-
- ### Frontend
- - **Framework**: Next.js 15+ (App Router only — no Pages Router)
- - **Language**: TypeScript 5+ (strict mode, `noUncheckedIndexedAccess: true`)
- - **Styling**: Tailwind CSS v4
- - **State**: React hooks → Zustand (when shared state needed)
- - **Forms**: React Hook Form + Zod
- - **Animation**: Framer Motion (premium projects only, opt-in)
- - **Data fetching**: TanStack Query v5
-
- ### Backend
- - **Primary**: NestJS with TypeScript
- - **Runtime**: Node.js 22+ (LTS)
- - **Validation**: class-validator + class-transformer
- - **Auth**: Passport.js + JWT (access + refresh token rotation)
- - **Queue**: BullMQ (Redis-backed)
- - **Cache**: Redis (ioredis)
-
- ### Database
- - **Primary**: PostgreSQL 16+
- - **ORM**: Prisma 6+
- - **Migrations**: Prisma Migrate (never manual SQL unless reviewed)
- - **Search**: pgvector for vector search, pg_trgm for full-text
-
- ### Infrastructure
- - **Containerization**: Docker + docker-compose
- - **CI**: GitHub Actions
- - **Deployment**: Vercel (frontend), Railway/Fly.io (backend)
- - **Secrets**: Environment variables only — never in code
-
- ---
-
- ## 4. Code Style
-
- ### TypeScript
-
- ```typescript
- // ✅ CORRECT
- const getUserById = async (id: string): Promise<User | null> => {
- return db.user.findUnique({ where: { id } })
- }
-
- // ❌ WRONG — any, var, semicolons, double quotes
- var getUser = async (id: any) => {
- return await db.user.findUnique({ where: { id } });
- }
- ```
-
- **Rules:**
- - No semicolons
- - Single quotes
- - 2 spaces (no tabs)
- - `const` over `let`, never `var`
- - Arrow functions preferred
- - Explicit return types on all functions
- - No `any` — use `unknown` if truly dynamic
- - Early returns over nested conditionals
- - Barrel exports (`index.ts`) for public APIs
-
- ### React / Next.js
-
- ```tsx
- // ✅ CORRECT
- interface UserCardProps {
- user: User
- onSelect: (id: string) => void
- }
-
- export const UserCard = ({ user, onSelect }: UserCardProps) => {
- return (
- <button onClick={() => onSelect(user.id)}>
- {user.name}
- </button>
- )
- }
- ```
-
- **Rules:**
- - Functional components only — no class components
- - Named exports only — no default exports (except Next.js pages/layouts)
- - Props interface: `{ComponentName}Props`
- - `'use client'` / `'use server'` explicit on every file that needs it
- - No CSS-in-JS — Tailwind only
- - Colocate: `Component.tsx`, `Component.test.tsx`, `Component.stories.tsx`
-
- ### NestJS
-
- ```typescript
- // ✅ Module structure
- @Module({
- imports: [TypeOrmModule.forFeature([User])],
- controllers: [UserController],
- providers: [UserService, UserRepository],
- exports: [UserService],
- })
- export class UserModule {}
- ```
-
- **Rules:**
- - One module per domain feature
- - Controller → Service → Repository layering (no skipping layers)
- - DTOs for all request/response shapes
- - Guards for auth, Interceptors for logging/transform
- - Never inject repositories directly into controllers
-
- ### Prisma
-
- ```prisma
- // ✅ Always explicit field types, always have createdAt/updatedAt
- model User {
- id String @id @default(cuid())
- email String @unique
- name String?
- createdAt DateTime @default(now())
- updatedAt DateTime @updatedAt
- }
- ```
-
- **Rules:**
- - Schema changes require migration plan approval first
- - Always run `prisma generate` after schema changes
- - Use transactions (`$transaction`) for multi-table writes
- - Never use `prisma.$queryRaw` without parameterization
- - Soft deletes: add `deletedAt DateTime?` pattern
-
- ---
-
- ## 5. Git Conventions
-
- ### Commit Format (Conventional Commits)
-
- ```
- type(scope): short description in imperative mood
-
- [optional body]
- [optional footer]
- ```
-
- | Type | When |
- |------|------|
- | `feat` | New feature |
- | `fix` | Bug fix |
- | `refactor` | Restructure without behavior change |
- | `perf` | Performance improvement |
- | `test` | Tests only |
- | `docs` | Documentation only |
- | `chore` | Dependencies, tooling |
- | `ci` | CI/CD changes |
- | `style` | Formatting only |
-
- **Examples:**
- ```
- feat(auth): add JWT refresh token rotation
- fix(api): handle null user in profile endpoint
- refactor(users): extract UserRepository from UserService
- ```
-
- ### Branch Strategy
+ Any variation, implication, or partial approval is not approval. When in doubt,
+ ask the user to confirm with `PLAN APPROVED` or `IMPLEMENTATION APPROVED`.
- ```
- main → production, protected, no direct push
- dev → integration branch
- feature/<slug> → new features (branch from dev)
- fix/<slug> → bug fixes (branch from dev)
- hotfix/<slug> → urgent production fixes (branch from main)
- ```
+ ### Change classification
- **Agent rule**: Never create branches autonomously. Always propose and wait for approval.
+ - Read-only inspection: understand the real state before deciding.
+ - Reversible change: can be restored or reverted without data loss.
+ - Irreversible change: deletion, migration, credential rotation, deployment, or
+ external communication; require explicit scope and a separate checkpoint.
+ - Report completed, failed, and unverified checks separately.
- ---
+ ## Engineering principles
- ## 6. Testing
+ - Prefer a deep module: a small, stable interface with substantial behavior
+ behind it.
+ - Put variation at a real seam and use an adapter for each host-specific
+ implementation. Keep shared behavior in the core.
+ - Prefer injected dependencies, deterministic outputs, early returns, and
+ testable results over hidden side effects.
+ - Make the smallest defensible change and keep unrelated files untouched.
+ - Preserve existing conventions unless the task explicitly changes them.
- ### Frontend (Vitest + Testing Library)
+ ## Specialist routing
- ```typescript
- // ✅ Test behavior, not implementation
- it('shows error when email is invalid', async () => {
- render(<LoginForm />)
- await userEvent.type(screen.getByLabelText('Email'), 'notanemail')
- await userEvent.click(screen.getByRole('button', { name: /login/i }))
- expect(screen.getByText(/invalid email/i)).toBeInTheDocument()
- })
- ```
+ Choose the narrowest specialist for the work. A generalist may coordinate,
+ but should not replace an available specialist without a reason.
- ### Backend (Jest)
+ | Role | Use for | Typical scope |
+ | --- | --- | --- |
+ | `architect` | Cross-cutting decisions | Boundaries, seams, trade-offs |
+ | `frontend-specialist` | UI and client behavior | React, Next.js, Tailwind, accessibility |
+ | `backend-specialist` | Server-side behavior | APIs, services, controllers, queues |
+ | `database-specialist` | Persistent data | PostgreSQL, Prisma, migrations, queries |
+ | `test-engineer` | Verification strategy | Unit, integration, E2E, regression coverage |
+ | `security-auditor` | Risk and trust boundaries | Auth, validation, secrets, abuse cases |
+ | `performance-optimizer` | Bottlenecks | Rendering, bundles, queries, caching |
+ | `devops-engineer` | Delivery infrastructure | Containers, CI, observability, deployment |
+ | `documentation-writer` | User-facing guidance | README, setup, migration, examples |
+ | `code-reviewer` | Post-change review | Correctness, maintainability, security |
- ```typescript
- // ✅ Unit test with mocked dependencies
- describe('UserService.create', () => {
- it('throws ConflictException when email exists', async () => {
- mockRepo.findByEmail.mockResolvedValue(existingUser)
- await expect(service.create(dto)).rejects.toThrow(ConflictException)
- })
- })
- ```
+ For work spanning several domains, define ownership and handoffs before
+ parallelizing. Keep each stream independently verifiable and integrate through
+ an explicit checkpoint.
- ### E2E (Playwright)
+ ## Communication
- ```typescript
- // ✅ Critical user paths only
- test('user can complete checkout', async ({ page }) => {
- await page.goto('/cart')
- await page.getByRole('button', { name: 'Checkout' }).click()
- await expect(page.getByText('Order confirmed')).toBeVisible()
- })
- ```
+ - Be concise and direct; expand when complexity requires it.
+ - State assumptions and scope before acting.
+ - For errors: **Report → Analyze → Impact → Options → Wait**.
+ - For every completed change, report changed files, verification performed, and
+ remaining uncertainty.
+ - Use English for code, comments, and commits. Documentation may include
+ Turkish supplementary notes.
- **Philosophy:**
- - Test behavior, not implementation
- - 80% unit/integration, 20% E2E
- - No 100% coverage obsession
- - Test the things that break in production
+ ## Technology defaults
- ---
+ Follow the project when it differs. Otherwise prefer:
- ## 7. Security
+ - Frontend: Next.js App Router, TypeScript 5+ strict mode, React, Tailwind CSS,
+ React Hook Form, Zod, and TanStack Query when those dependencies are needed.
+ - Backend: NestJS, Node.js LTS, class-validator, class-transformer, Passport,
+ JWT rotation, BullMQ, and Redis when the architecture calls for them.
+ - Data: PostgreSQL and Prisma; use reviewed migrations, parameterized queries,
+ transactions for multi-table writes, and a nullable `deletedAt` field when
+ soft deletion is a real domain requirement.
+ - Verification: Vitest/Jest for unit and integration tests; Playwright for
+ critical end-to-end paths.
+ - Delivery: Docker, GitHub Actions, and environment variables for secrets.
- ### Mandatory Checks Before Every Commit
+ These are defaults, not mandatory dependencies. Do not introduce a framework,
+ package, provider, or infrastructure service merely because it appears in this
+ list.
- - [ ] No hardcoded secrets (`grep -r "api_key\|password\|secret" src/`)
- - [ ] All user inputs validated (Zod / class-validator)
- - [ ] SQL queries parameterized (no string interpolation)
- - [ ] Auth guards on all protected routes
- - [ ] Rate limiting on public endpoints
- - [ ] CORS configured correctly
- - [ ] Error messages don't leak stack traces
+ ## Code style
- ### Forbidden Patterns
+ - TypeScript/JavaScript: no semicolons, single quotes, two-space indentation,
+ `const` over `let`, never `var`, arrow functions where natural, and explicit
+ return types for public functions.
+ - React: functional components, named exports except framework-required pages,
+ explicit client/server directives, and accessible interactions.
+ - Backend: keep controller, service, and repository responsibilities separate;
+ validate all request/response shapes.
+ - Database: never interpolate SQL, use transactions for related writes, and
+ include created/updated timestamps on persistent entities.
- ```typescript
- // ❌ NEVER
- const query = `SELECT * FROM users WHERE id = ${userId}` // SQL injection
- process.env.SECRET_KEY = 'hardcoded' // hardcoded secret
- app.use(cors({ origin: '*' })) // open CORS
- console.log('User password:', password) // log sensitive data
- ```
+ ### Boundary examples
- ---
+ - UI components receive typed props and expose behavior through accessible
+ interactions; keep server/client boundaries explicit.
+ - Controllers translate transport input into validated DTOs and delegate to
+ services; repositories own persistence details.
+ - Public module APIs should be reachable through stable interfaces or path
+ aliases; avoid imports that cross internal boundaries accidentally.
+ - A schema change starts with a migration plan and includes generated client
+ output plus rollback or recovery considerations.
- ## 8. Error Handling Protocol
+ ## Git and delivery boundaries
- When you encounter an error:
+ - Use Conventional Commits: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`,
+ `chore`, `ci`, or `style` with a concise scope when useful.
+ - Follow the repository's branch policy when one exists. Never invent a branch
+ name or create a branch autonomously.
+ - Never create branches, push, deploy, or trigger external systems without
+ explicit approval.
+ - Review the final diff for accidental files, secrets, debug artifacts, and
+ unrelated formatting.
+ - Keep CI/CD changes reviewable and least-privilege; do not widen permissions
+ just to make a check pass.
- 1. **Report** — What exactly failed?
- 2. **Analyze** — Root cause, not surface symptom
- 3. **Impact** — What does this break?
- 4. **Options** — 2-3 solution paths with trade-offs
- 5. **Wait** — Which approach should I take?
+ ## Testing and security
- **Never auto-fix. Always get approval first.**
+ - Test behavior and failure modes, not implementation details.
+ - Prioritize business-critical paths and edge cases over arbitrary coverage
+ percentages.
+ - Prefer a practical balance of unit/integration tests and a smaller set of
+ critical E2E flows. Test the things most likely to break in production.
+ - For UI tests, assert accessible roles, labels, and visible outcomes. For
+ services, assert domain errors and dependency boundaries. For E2E tests,
+ cover the shortest critical user journey rather than every permutation.
+ - Before committing, check for hardcoded secrets, unvalidated input,
+ authorization gaps, unsafe SQL, open CORS, sensitive logs, leaked stack
+ traces, and missing rate limits on public endpoints.
+ - Never read, print, copy, or modify secrets unless the task explicitly names
+ the exact data and destination.
- ---
+ ### Pre-delivery security checklist
- ## 9. Claude Code Workflow Commands
+ - [ ] Inputs and uploaded data are validated at the trust boundary.
+ - [ ] Protected routes enforce authentication and authorization.
+ - [ ] Queries are parameterized and bounded; list endpoints paginate.
+ - [ ] CORS, cookies, CSRF, and rate limits match the deployment model.
+ - [ ] Errors and logs omit credentials, tokens, personal data, and stack traces.
+ - [ ] Dependencies and generated artifacts do not introduce an unreviewed
+ secret or executable payload.
- Use these slash commands throughout the development workflow:
+ ## Forbidden patterns
- | Command | When to Use |
- |---------|-------------|
- | `/plan` | Before starting any feature |
- | `/brainstorm` | Exploring architecture options |
- | `/debug` | Stuck on a bug |
- | `/create` | Implementing approved plan |
- | `/enhance` | Improving existing code |
- | `/test` | Writing or fixing tests |
- | `/status` | Progress checkpoint |
- | `/orchestrate` | Coordinating multi-agent tasks |
+ - `any` in TypeScript when `unknown` or a precise type is possible.
+ - `console.log` for production diagnostics.
+ - Hardcoded secrets, API keys, or credentials.
+ - `var`, silent catch blocks, unbounded queries, and unreviewed migrations.
+ - Default exports except where a framework requires them.
+ - CSS-in-JS when the project uses a utility or stylesheet convention.
+ - Direct database access from controllers or UI components.
+ - TODOs without a ticket or explicitly documented follow-up.
- ---
+ ## Shared workflow catalog
- ## 10. Memory & Context
+ The repository's canonical workflows are named `plan`, `brainstorm`, `create`,
+ `enhance`, `debug`, `test`, `preview`, `status`, `orchestrate`, and
+ `ui-ux-pro-max`. Use the host's native selector for these names. The invocation
+ syntax is an adapter concern; the workflow body and acceptance criteria remain
+ shared.
- ### What to Track in TodoWrite
+ For a change involving more than two files or a substantial implementation,
+ start with `plan`, record scope and checkpoints, and obtain approval before
+ execution. Use `preview` before a commit or review request, and `status` when
+ handing work to another session or developer.
- For every multi-step task, maintain a todo list:
- - Current phase and status
- - Completed items (with ✅)
- - Blocked items (with reason)
- - Next action required
+ ## Memory and context hygiene
- ### Context Hygiene
+ - For multi-step work, track the current phase, completed checks, blockers, and
+ next action in the host's task mechanism.
+ - If requirements change during implementation, stop at the current safe
+ checkpoint and re-plan instead of silently widening scope.
+ - When context becomes contradictory or evidence is missing, state the
+ uncertainty and ask for the smallest clarification that resolves it.
+ - Keep summaries and handoffs factual: separate completed, failed, and
+ unverified work.
- - If a conversation exceeds 15 turns without a clear outcome → suggest `/compact` or new session
- - If requirements shift mid-implementation → stop, re-plan, get approval
- - If context becomes contradictory → ask for clarification, don't assume
+ ## Definition of done
- ---
+ Before stopping, answer:
- ## 11. Forbidden Patterns (All Languages)
+ 1. What outcome was requested and what changed?
+ 2. Which files and interfaces were affected?
+ 3. Which checks actually ran and passed?
+ 4. What remains unverified or needs the user's decision?
- ```
- ❌ any type in TypeScript
- ❌ console.log in production code
- ❌ hardcoded secrets or API keys
- ❌ var keyword
- ❌ default exports (except Next.js pages/layouts)
- ❌ CSS-in-JS libraries
- ❌ class components in React
- ❌ relative imports crossing module boundaries (use path aliases)
- ❌ direct database access from controllers
- ❌ unbounded queries (always use pagination)
- ❌ missing error handling (never silent catch blocks)
- ❌ TODO comments without ticket reference
- ```
+ # Claude Code adapter
- ---
+ This adapter is appended to the shared policy when rendering
+ `~/.claude/CLAUDE.md`.
- ## 12. Quick Reference
+ ## Native integration
- | Action | Policy |
- |--------|--------|
- | Suggest code | ✅ Always (with reasoning) |
- | Create files | ⚠️ Approval required |
- | Run commands | ⚠️ Approval required |
- | Delete files | ⚠️ Approval required |
- | Create branches | ⚠️ Approval required |
- | Install packages | ⚠️ Approval required |
- | Schema migrations | ⚠️ Plan approval + implementation approval |
- | Push to remote | ❌ Never autonomously |
- | Deploy | ❌ Never autonomously |
- | Modify CI/CD | ❌ Never autonomously |
- | Access .env files | ❌ Read-only, never modify |
+ - Reusable specialist agents are Markdown files in `~/.claude/agents/`.
+ - Reusable skills are directories containing `SKILL.md` in `~/.claude/skills/`.
+ - Use Claude's native agent and skill selectors. The shared workflow names are
+ available as skills and may be invoked with the host's slash-command UI.
+ - Do not assume that a tool name, permission mode, or MCP server exists merely
+ because another host exposes a similarly named capability.
+ - Project-local instructions remain the closest source of truth for that
+ project; do not overwrite them with global defaults.