@RTK.md

# Agent Instructions

This backend owns the DevOps platform API only. Do not edit sibling projects from this directory.

## Hard Boundaries

- Write only inside `devops-platform-api` unless the user explicitly expands the scope.
- Do not write `devops-platform-web`.
- Do not write `devops-platform-docs/devops-platform-implementation-tracker.md`; the coordinating thread owns tracker updates.
- Do not revert unrelated user or worker changes.

## Backend Standards

- Use NestJS modules and dependency injection for all business boundaries.
- Keep controllers thin. Validation, orchestration, and audit decisions belong in services.
- Use Prisma as the default data access layer. Business code must not create mysql2 pools or scatter handwritten SQL.
- If native SQL is unavoidable, place it in a Repository, parameterize it, document why Prisma is insufficient, and keep the method narrow.
- Keep external clients behind integration modules: Jenkins, Gitea, notification providers, and LLM.

## Security Standards

- Never commit real credentials.
- Redact tokens, webhook URLs, cookies, authorization headers, private keys, and long opaque secret-like strings before logging, auditing, returning errors, or passing content to LLMs.
- Store future persisted secrets encrypted server-side only.
- Frontend must never receive Jenkins/Gitea/notification/LLM secret values.

## Audit Standards

- Record actor, resource, action, before/after state summaries, request source, and parameter digests for deploy, cancel, retry, secret change, and agent invocation operations.
- Deploy run status transitions must be idempotent and concurrency-safe when database writes are enabled.

## Agent Standards

- Agent features must be tied to DevOps workflows, not general chat.
- Agent calls are read-only unless a future product decision explicitly changes this.
- Save prompt version, purpose, operator, input digest, output digest, token estimate, and sanitized failure summary for every real invocation.