prizmkit 1.1.154 → 1.1.156

package/bundled/skills/app-planner/references/rules/backend/derivation-rules.md

@@ -13,6 +13,11 @@
 
 ---
 
+## SEMANTIC_FALLBACK_POLICY
+
+Every confirmed option is valid input even when no pre-authored block exists. For an unmatched framework, ORM, datastore, deployment, observability, or permission option, render the complete selected meaning, follow current official and detected project conventions, preserve brownfield behavior unless migration was selected, and import no rules from a recommended alternative. Render `none`, `not required`, deferred, and conditionally skipped decisions as explicit not-applicable or deferred statements; never leave placeholders blank.
+
+Validate active blocks against the decision ledger before rendering. Architecture, API style, authentication, data technology, testing, observability, and AI permissions each have one selected owner; incompatible blocks fail generation.
 
 ## Phase 2 Normalized Semantic Fill Table
 
@@ -124,9 +129,9 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-NODE-02
 **Trigger**: Q1 = Node.js | **Inject into**: `{{ tech_stack_rules }}`
 
-- Package manager locked to `pnpm` (recommended). Commit `pnpm-lock.yaml`.
-- `package.json` declares `"type": "module"`.
-- CI validates `engines` field matches `.nvmrc`.
+- Preserve the package manager and lockfile already selected by the project; do not introduce a different manager as an implicit Node.js default.
+- `package.json` declares the selected module format explicitly when the runtime requires it.
+- Keep runtime declarations used by package metadata, local tooling, and CI consistent.
 
 ### D-PYTHON-01
 **Trigger**: Q1 = Python | **Inject into**: `{{ tech_stack_rules }}`
@@ -354,38 +359,35 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-MONGO-01
 **Trigger**: Q8 = MongoDB | **Inject into**: `{{ data_rules }}`
 
-- MongoDB document model: schema validation via JSON Schema (`$jsonSchema` validator on collections).
-- Indexing strategy for query patterns: create indexes for all query filter fields. Use `explain()` to verify index usage.
-- Aggregation pipeline standards: stages must be documented with purpose comments. Forbid complex pipelines without EXPLAIN.
-- No-SQL injection prevention: validate and sanitize all user input in queries. Use parameterized query operators (`$eq`, `$gt`), forbid `$where` with user input.
-- Collection design with embedded vs. reference trade-offs: embed for read-together data, reference for independently-accessed data.
-- The relational-database-oriented F5 fixed rules (migration files, SELECT syntax, normalization) do NOT apply. Skip F5.1-F5.3 of the fixed rules content.
+- Define collection validation at the database or application boundary and keep it synchronized with the selected model source.
+- Derive indexes from measured query/sort paths and verify expensive operations with `explain()`; do not index every filterable field automatically.
+- Treat field names and query operators as allowlisted input and never evaluate caller-controlled `$where` or executable expressions.
+- Choose embedding versus references from aggregate ownership, update atomicity, document growth, and access patterns.
+- Apply document-model, migration, and query rules only; do not import relational SQL or 3NF rules.
 
 ### D-MYSQL-01
 **Trigger**: Q8 = MySQL | **Inject into**: `{{ data_rules }}`
 
-- MySQL 8.0+ with InnoDB engine default. Use `utf8mb4` charset for all tables.
-- Forbid `utf8mb3` (deprecated). Forbid MyISAM engine (no transaction support).
-- Index types: BTREE for range queries, HASH for exact-match lookups (memory tables only).
-- Connection pool: configure `wait_timeout` and `interactive_timeout` to prevent stale connections.
-- Migration files use the same tooling as PostgreSQL (golang-migrate, Flyway, Alembic). Schema differences documented in README.
+- Use a supported MySQL release and a transactional engine for state requiring atomicity.
+- Use `utf8mb4` for Unicode text and reject deprecated encodings in new structures.
+- Select indexes from query patterns and engine support, and configure client lifetime against server timeouts.
+- Use the migration mechanism selected by the project; do not inherit PostgreSQL syntax or tooling.
 
 ### D-SQLITE-01
 **Trigger**: Q8 = SQLite | **Inject into**: `{{ data_rules }}`
 
-- SQLite for local development and single-instance deployments. WAL mode enabled by default.
-- Forbid SQLite for multi-instance production deployments (no concurrent write support).
-- Forbid concurrent write access across multiple processes. Use a single writer pattern.
-- Migration files still version-controlled. Test with the same SQLite version as production.
-- No connection pool needed (single connection). Close connections explicitly after each operation.
+- Use SQLite only for a workload whose concurrency, durability, and deployment model match its capabilities.
+- Choose journal/WAL mode from the read/write and filesystem constraints and serialize writes when required.
+- Version model changes and test with the supported production SQLite version when SQLite is the deployed store.
+- Follow the selected driver lifecycle; do not impose a server-style connection pool.
 
 ### D-JWT-01
 **Trigger**: Q9 = JWT | **Inject into**: `{{ auth_rules }}`
 
-- Access token TTL ≤ 15min. Refresh token TTL ≤ 7d.
-- Token payload contains no sensitive info (passwords, phone numbers). Only userId + role.
-- Secret read from environment variables. Forbid hardcoding.
-- Token blacklist (logout/password change invalidation) implemented with Redis.
+- Define issuer, audience, subject, scopes/claims, signing algorithm, access lifetime, refresh/re-issuance, rotation, and revocation from the threat model.
+- Keep sensitive data out of token payloads and validate signature plus temporal and audience claims at every trust boundary.
+- Keep signing material outside source control and support key rotation.
+- Implement revocation through a compatible selected mechanism; JWT does not implicitly authorize Redis.
 
 ### D-OAUTH-01
 **Trigger**: Q9 = OAuth2 | **Inject into**: `{{ auth_rules }}`
@@ -398,19 +400,17 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-SESSION-01
 **Trigger**: Q9 = Session | **Inject into**: `{{ auth_rules }}`
 
-- Session storage uses Redis, not memory (loses data on restart, not shared across instances).
-- Session ID generated with `crypto.randomUUID()`, not auto-increment IDs.
-- Cookie settings: `HttpOnly` + `Secure` (production) + `SameSite=Lax`.
-- Session ID must be rotated after successful login (prevent Session Fixation).
+- Store sessions in a mechanism compatible with the selected deployment and availability topology; an external cache is not implied when Q10 selected no cache.
+- Generate high-entropy opaque session identifiers, rotate them at authentication/privilege changes, and invalidate them on logout.
+- Use `HttpOnly`, production `Secure`, and a SameSite/CSRF policy compatible with confirmed cross-site flows.
 
 ### D-APIKEY-01
 **Trigger**: Q9 = API Key | **Inject into**: `{{ auth_rules }}`
 
-- API keys for service-to-service communication. Not for end-user auth.
-- Keys stored hashed (SHA-256) in database. Plaintext shown once at creation.
-- Key format: `sk_<random_32_bytes_base64url>` with prefix for easy identification in logs.
-- Key validation: constant-time comparison to prevent timing attacks.
-- Keys must have expiration (default 365d). Must be rotatable without downtime.
+- Restrict API keys to named machine or integration principals, not end-user authentication.
+- Generate high-entropy keys, display plaintext only at creation, and store a one-way verifier plus a non-secret lookup prefix.
+- Compare verifiers safely and support scoped authorization, rotation, revocation, ownership, and last-used audit data.
+- Set expiry from integration risk and lifecycle rather than a universal duration.
 
 ### D-REDIS-01
 **Trigger**: Q10 = Redis | **Inject into**: `{{ cache_rules }}`
@@ -462,18 +462,16 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-DOCKER-01
 **Trigger**: Q12 = Docker | **Inject into**: `{{ deploy_rules }}`
 
-- Dockerfile uses multi-stage builds. Final image excludes build tools.
-- Base image uses `-slim` or `-alpine` variants.
-- Health check: `HEALTHCHECK` points to `/health` endpoint.
-- `.dockerignore` excludes node_modules, .git, log files.
+- Use a reproducible build and a minimal runtime image compatible with the selected language/runtime; do not force Alpine when native dependencies make it unsafe.
+- Exclude build-only tools and sensitive/unneeded context from the final image.
+- Connect container health behavior to the selected application liveness/readiness contract rather than assuming one route.
 
 ### D-K8S-01
 **Trigger**: Q12 = Kubernetes | **Inject into**: `{{ deploy_rules }}`
 
-- Must configure liveness and readiness probes (pointing to `/health` and `/health/ready`).
-- Resource limits (requests/limits) must be set.
-- Sensitive config via Secret, non-sensitive via ConfigMap.
-- Pod anti-affinity: same-type pods not scheduled on the same node (high availability).
+- Configure probes against the application's selected liveness/readiness contract and set resource requests/limits from measured behavior.
+- Keep sensitive and non-sensitive configuration in the platform's appropriate boundaries without committing secret values.
+- Replicas, disruption budgets, anti-affinity, and multi-zone placement come from the confirmed availability objective; Kubernetes selection alone does not require them.
 
 ### D-AI-DEP-STRICT-01
 **Trigger**: Q18 = Forbid | **Inject into**: `{{ ai_dependency_rule }}`
@@ -519,10 +517,9 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-OBS-LOG-01
 **Trigger**: Q16 = Structured JSON logging | **Inject into**: `{{ observability_rules }}`
 
-- Log format: JSON with fields `timestamp`, `level`, `message`, `traceId`, `userId`, `service`, `path`, `method`, `duration_ms`.
-- Centralized collection via ELK (Elasticsearch + Logstash + Kibana) or Grafana Loki.
-- Log levels: ERROR (requires alert), WARN (requires investigation), INFO (key business events), DEBUG (development only).
-- Forbid logging sensitive data (passwords, tokens, national IDs). Must mask.
+- Emit structured events with timestamp, severity, message, service/operation, and available correlation context; add identity or request fields only when useful and privacy-safe.
+- Send events through the centralized collection boundary selected by the deployment; do not force ELK or Loki.
+- Define severity and alert mappings operationally, and redact credentials, tokens, and sensitive personal data.
 
 ### D-OBS-LOG-02
 **Trigger**: Q16 = local files | **Inject into**: `{{ observability_rules }}`
@@ -543,26 +540,23 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-OBS-METRICS-01
 **Trigger**: Q17 = OpenTelemetry + Prometheus + Grafana | **Inject into**: `{{ observability_rules }}`
 
-- OpenTelemetry SDK auto-instruments HTTP/gRPC/database calls.
-- Custom metrics: request count, request duration (p50/p95/p99), error rate, DB query duration.
-- Prometheus scrapes `/metrics` endpoint. Grafana dashboards for: request latency, error rate, DB connection pool, cache hit rate.
-- Alerting rules: error rate > 5% for 5min triggers alert, p95 latency > 500ms for 5min triggers warning.
+- Instrument applicable transport and dependency boundaries with the selected OpenTelemetry-compatible pipeline.
+- Define service metrics and dashboards from confirmed service objectives and selected dependencies; cache metrics appear only when caching is selected.
+- Expose or export telemetry through the selected collector/platform mechanism and derive alert thresholds from objectives and observed baselines rather than universal percentages.
 
 ### D-TEST-STRATEGY-01
 **Trigger**: Q13 = Unit tests + Integration tests | **Inject into**: `{{ test_rules }}`
 
-- Testing tiers: unit tests (service/repository layers) + integration tests (API endpoints + DB).
-- Unit tests: fast (<100ms each), no external deps. Mock all I/O.
-- Integration tests: use test database or testcontainers. Test realistic scenarios.
-- Coverage targets: service layer >= 80%, controller layer >= 60%.
-- CI runs all tests. Integration tests run against a fresh DB instance each time.
+- Include unit and integration behavior appropriate to the selected architecture and external boundaries.
+- Unit tests isolate owned behavior; integration tests verify real contract boundaries using the separately selected mock/environment strategy.
+- Set numeric coverage or timing thresholds only when the project confirms them. CI runs the enabled tiers in deterministic isolation.
 
 ### D-TEST-STRATEGY-02
 **Trigger**: Q13 = Unit tests only | **Inject into**: `{{ test_rules }}`
 
-- Unit tests only. Coverage target: service layer >= 80%.
-- External deps mocked. No database or network access in tests.
-- Recommend adding integration tests for critical data-access paths before production.
+- Keep the mandatory suite at the unit boundary selected by the project and isolate external dependencies according to Q15.
+- Do not inject an unselected coverage percentage.
+- Record the accepted lack of integration evidence and revisit it when production risk changes.
 
 ### D-TEST-STRATEGY-03
 **Trigger**: Q13 = Critical path integration tests only | **Inject into**: `{{ test_rules }}`
@@ -574,10 +568,9 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-TEST-MOCK-01
 **Trigger**: Q15 = testcontainers | **Inject into**: `{{ test_rules }}`
 
-- External APIs (payment gateways, email services, third-party SDKs): mocked.
-- Database: use testcontainers (dockerized Postgres/MySQL/Redis) for integration tests.
-- Testcontainers lifecycle: start before test suite, stop after. Use singleton container pattern to share across tests.
-- Test data: seeded per test file, cleaned up after each test. Forbid shared mutable test data.
+- Mock external service dependencies at their contract boundary.
+- For datastore integration tests, use a testcontainer or an in-memory implementation only when it faithfully represents the selected datastore behavior; do not start Redis unless caching/session decisions require it.
+- Bound environment lifecycle and isolate mutable test data so tests remain repeatable.
 
 ### D-TEST-MOCK-02
 **Trigger**: Q15 = including database | **Inject into**: `{{ test_rules }}`
@@ -590,10 +583,9 @@ Resolve each selected option or custom reply into the complete semantic value sh
 ### D-TEST-MOCK-03
 **Trigger**: Q15 = real environments | **Inject into**: `{{ test_rules }}`
 
-- Prefer real environments over mocking. Tests run against dedicated test infrastructure.
-- Test database is a shared instance (not per-developer).
-- Test data isolation: each test creates its own data and cleans up.
-- Requires CI access to test infrastructure. Tests may be slower but more realistic.
+- Prefer representative real dependencies through dedicated test infrastructure where the selected risk justifies it.
+- Shared infrastructure must still isolate tenants/data and support deterministic cleanup; a shared instance is not automatically required.
+- Document CI access, cost, failure ownership, and any remaining non-production differences.
 
 ---
 

package/bundled/skills/app-planner/references/rules/backend/fixed-rules.md

@@ -1,285 +1,130 @@
-# Fixed Rules — Complete Backend Fixed Rules
-
-> This file is read by the `backend-rules` skill in Phase 1 and injected directly into `backend-rules.md`.
-> These rules are industry consensus / best practices — **do not ask the user**.
-> Every rule includes RATIONALE so the AI understands intent, not just constraints.
-
----
-
-## F1. Project Structure
-
-### F1.1 Layered Architecture (Mandatory)
-
-- **Rule**: Must use one of the following layering patterns, and be consistent across the project:
-  - Classic three-tier: `controller → service → repository`
-  - DDD-style: `handler → usecase → repository` (Go) / `router → service → dao` (Node)
-- **Rule**: Upper layers must not bypass lower layers (controller must not call repository directly).
-- **Rule**: Each layer does only its own job — controller handles request validation and response formatting, service handles business logic, repository handles data access.
-- **RATIONALE**: Mixed layer boundaries are the #1 cause of backend code rot. When AI can't tell which layer does what, business logic scatters into controllers.
-
-### F1.2 Directory Conventions
-
-- **Rule**: The project root structure must clearly reflect the layering.
-- **Rule**: Shared utilities (utils) must be isolated from business code.
-- **Rule**: Config, constants, and type definitions are centrally managed.
-- **Forbidden**: Turning `utils/` into a dumping ground for anything without a clear home.
-- **RATIONALE**: The directory structure is the project's first piece of documentation. A new developer (including AI) should know where a function belongs just by reading it.
-
-### F1.3 Module Boundaries
-
-- **Rule**: Organize by business domain, not by technical layer (types/services/models cross-domain).
-- **Rule**: Modules communicate through explicit interfaces. Do not access another module's internal implementation directly.
-- **Forbidden**: Circular dependencies (module A imports B, B imports A).
-- **RATIONALE**: Technical-layer organization scatters code for a single feature across 4–5 directories. Changing one feature requires jumping across directories.
-- **Note on layering interaction with F1.1**: Organize by business domain at the top level. Within each domain directory, enforce the layering from F1.1 (e.g., user/controller/, user/service/, user/repository/). Do NOT create top-level controllers/, services/, repositories/ directories that span all domains.
-
----
-
-## F2. API Design
-
-### F2.1 REST Contract
-
-- **Rule**: URLs use plural nouns (`/users`, `/orders`), never verbs (forbid `/getUser`, `/createOrder`).
-- **Rule**: HTTP method semantics must be correct:
-  - `GET` — query, must not modify data
-  - `POST` — create
-  - `PUT` — full update
-  - `PATCH` — partial update
-  - `DELETE` — remove
-- **Rule**: Standard pagination params: `page` (1-based), `pageSize` (default 20, max 100).
-- **Rule**: Standard sorting params: `sortBy=field&sortOrder=asc|desc`.
-- **RATIONALE**: The API is a contract between frontend and backend. Inconsistent naming and parameter formats cause bugs in consumers.
-
-### F2.2 Status Codes
-
-- **Rule**: Use HTTP status codes strictly by semantics:
-  - `200` — query success
-  - `201` — create success
-  - `204` — delete success (no body)
-  - `400` — validation failure
-  - `401` — not authenticated
-  - `403` — forbidden
-  - `404` — resource not found
-  - `409` — resource conflict
-  - `422` — valid request format but business logic rejection
-  - `500` — unknown server error
-- **Forbidden**: Returning `200` for all errors with an error code in the body.
-- **RATIONALE**: HTTP status codes are standard signals for infrastructure (load balancers, monitoring, gateways). Bypassing them makes all observability useless.
-
-### F2.3 Error Response Format
-
-- **Rule**: All errors return a unified structure:
-  ```json
-  {
-    "error": {
-      "code": "USER_NOT_FOUND",
-      "message": "User not found",
-      "details": [],
-      "traceId": "abc-123"
-    }
-  }
-  ```
-- **Rule**: `code` uses UPPER_SNAKE_CASE with business semantics (`USER_NOT_FOUND`, not `ERR_001`).
-- **Rule**: `traceId` is generated at request entry and propagated through the entire call chain.
-- **RATIONALE**: A unified error format lets frontends and gateways write one error handler instead of per-endpoint if/else chains.
+# Backend Invariant Rules
 
-### F2.4 API Versioning
+POLICY_CLASS: invariant
 
-- **Rule**: APIs must indicate version in URL or Header (`/api/v1/users` or `Accept: application/vnd.api.v1+json`).
-- **Rule**: Breaking changes require a new version. Old versions must be maintained for at least one release cycle.
-- **RATIONALE**: Unversioned APIs cause widespread mobile/third-party client crashes on release.
+These blocks apply to every backend option exposed by Rules Configuration.
 
----
+**Selected-decision boundary:** language, runtime, framework, architecture, API style, API documentation, data technology, authentication scheme, cache, queue, deployment, testing depth, observability stack, dependency permission, caller analysis, and config permission belong to confirmed decisions and derivation rules. Do not encode one option here as universal behavior.
 
-## F3. Error Handling
+## I1. Structure and Ownership
 
-- **Rule**: All exceptions must be caught by a global exception filter and return a unified error response.
-- **Rule**: Business exceptions vs. system exceptions are separated — business exceptions return 4xx, system exceptions return 500.
-- **Forbidden**: Empty `catch(e) {}` blocks. If ignoring is truly necessary, comment why.
-- **Forbidden**: `catch(e) { throw new Error('something went wrong') }` that swallows the original stack trace.
-- **Rule**: Error logs must include traceId, user identifier, request method, and path.
-- **RATIONALE**: The biggest backend failure isn't "an error occurred" — it's "an error occurred and nobody knows".
+- Every module has an explicit owner and public boundary; internal implementation is not imported as an accidental API.
+- Dependency direction follows the selected architecture and remains free of unplanned cycles.
+- Business behavior has one authoritative implementation rather than duplicated branches across transports or entrypoints.
+- Rationale: ownership and acyclic dependencies are invariant; layer names are not.
 
----
+Inject into `{{ FIXED_RULES_STRUCTURE }}`.
 
-## F4. Security
+## I2. API Contract Integrity
 
-### F4.1 Input Validation (Mandatory)
+- Follow the selected API style consistently and document externally consumed requests, responses, errors, and compatibility expectations.
+- Validate untrusted inputs at the boundary before invoking business behavior.
+- Contract changes identify affected consumers and use the selected compatibility or versioning policy.
+- Do not apply HTTP-specific rules to non-HTTP transports unless an adapter explicitly owns that mapping.
 
-- **Rule**: All external inputs must be validated (body, query params, path params, headers, cookies).
-- **Rule**: Use a validation framework (Joi/Zod/Pydantic/validator), not hand-written if/else.
-- **Rule**: Validation failures return 400 with field-level error details.
-- **Forbidden**: Trusting data from the frontend to be directly stored or executed.
-- **RATIONALE**: Input validation is the first line of defense and the root cause mitigation for multiple OWASP Top 10 attacks.
-
-### F4.2 Authentication & Authorization
-
-- **Rule**: AuthN and AuthZ must be separated — middleware handles authentication, business logic handles authorization.
-- **Rule**: JWT tokens must have expiration (access token ≤ 15min, refresh token ≤ 7d).
-- **Rule**: Sensitive operations (delete, transfer, permission changes) require secondary confirmation.
-- **Forbidden**: Hardcoding tokens/secrets in source code.
-- **RATIONALE**: Separating AuthN and AuthZ allows independent security audits at each layer.
-
-### F4.3 General Protections
-
-- **Rule**: All external links/callback URLs must be validated against a whitelist to prevent Open Redirect.
-- **Rule**: File uploads must validate type (whitelist), size, and content magic bytes.
-- **Rule**: Passwords must use bcrypt/argon2 hashing. Forbid plaintext, MD5, or SHA1.
-- **Forbidden**: Exposing secrets, tokens, or passwords in error messages or logs.
-- **Forbidden**: Returning internal implementation details in responses (stack traces, SQL statements, framework versions).
-- **RATIONALE**: These are the most common security vulnerabilities. Not a question of "should we" — it's "you will be breached if you don't."
+Inject into `{{ FIXED_RULES_API }}`.
 
-### F4.4 Rate Limiting
+## I3. Error Integrity
 
-- **Rule**: All public API endpoints must have rate limiting. Forbid unlimited request rates.
-- **Rule**: Rate limit tiers: authentication endpoints (5 req/min), general API (100 req/min per user/IP), internal/admin endpoints (higher limits).
-- **Rule**: Rate limit headers: include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset in responses.
-- **Rule**: Rate limit exceeded returns 429 Too Many Requests with Retry-After header.
-- **RATIONALE**: Without rate limiting, a single misbehaving client or a simple script-kiddie attack can take down your entire API.
+- Preserve original diagnostic context when translating an internal failure to a public error.
+- Separate expected domain failures from unexpected system failures.
+- Public errors expose no secrets, stack traces, query text, or private implementation details.
+- Never swallow a failure without an explicit, documented recovery path.
 
----
-
-## F5. Database
-
-**Note**: These rules assume a relational database (PostgreSQL/MySQL). If the project uses MongoDB (selected in Q8), some rules (migration files, SELECT syntax) do not apply. Document-specific rules are in the derived rules section.
-
-- **Rule**: Connection pool must be reasonably sized (default ≤ CPU cores × 2). Connections must have timeouts.
-- **Rule**: All migration files must be versioned, reversible, and committed to the repository.
-- **Rule**: Queries must use parameterized queries or ORM-provided safe methods. Forbid string-concatenated SQL.
-- **Rule**: Bulk operations (>1000 rows) must be batched.
-- **Forbidden**: Executing single-row SQL inside loops (use batch insert/update instead).
-- **Forbidden**: SELECT without LIMIT.
-- **Forbidden**: `SELECT *` (specify columns explicitly).
-- **RATIONALE**: The database is the component where a single failure has the largest blast radius in a backend system. One bad query can bring down the entire service.
+Inject into `{{ FIXED_RULES_ERROR }}`.
 
----
+## I4. Security Baseline
 
-## F6. Observability
+- Authenticate and authorize at explicit trust boundaries; do not trust caller-supplied identity or role data.
+- Keep credentials and secrets outside source control and redact sensitive values from logs and errors.
+- Validate callback, redirect, upload, and deserialization boundaries against an allowlisted contract.
+- Store passwords only with a current password-hashing construction.
+- Scheme-specific token, session, OAuth, and API-key rules come from `{{ auth_rules }}`.
 
-- **Rule**: Logs must be structured (JSON format), containing: `timestamp`, `level`, `message`, `traceId`, `userId`, `path`, `method`.
-- **Rule**: Expose at least two endpoints: `GET /health` (liveness) and `GET /health/ready` (readiness).
-- **Rule**: Key business operations must be instrumented (registration, login, payment, order creation, etc.).
-- **Forbidden**: Using `console.log` as a substitute for structured logging.
-- **RATIONALE**: A microservice without structured logging is a black box. Troubleshooting goes from minutes to hours.
+Inject into `{{ FIXED_RULES_SECURITY }}`.
 
-### F6.2 Distributed Tracing
+## I5. Abuse Protection
 
-- **Rule**: Every incoming request must generate or propagate a traceId. traceId is passed in X-Trace-Id header.
-- **Rule**: All downstream calls (database, cache, message queue, external APIs) must carry the traceId.
-- **Rule**: Use W3C Trace Context standard (traceparent header) for cross-service propagation.
-- **Forbidden**: Generating a new traceId mid-request chain (breaks distributed traces).
-- **RATIONALE**: traceId is the thread that ties together every log line and span for a single request across microservices. Without it, troubleshooting distributed systems is guesswork.
+- Identify public or expensive operations that require quotas, backpressure, idempotency, or rate protection.
+- Derive concrete limits from product risk and deployment capacity instead of imposing one universal number.
+- Rejection behavior is observable and does not disclose sensitive internals.
 
-### F6.3 Health Check Endpoints
+Inject into `{{ FIXED_RULES_RATE_LIMITING }}`.
 
-- **Rule**: GET /health (liveness) — returns 200 if the process is alive. No dependency checks.
-- **Rule**: GET /health/ready (readiness) — returns 200 if all critical dependencies are available (database, cache, message queue). Returns 503 if any critical dependency is unreachable.
-- **Rule**: Health checks must be lightweight (< 50ms). Forbid running expensive queries or external API calls.
-- **RATIONALE**: Kubernetes and load balancers use these endpoints to decide whether to route traffic or restart the pod. A slow /health creates cascading failures.
+## I6. Data Access Safety
 
----
+- Use the selected data technology's safe parameter binding or query construction mechanism.
+- Bound potentially unbounded reads and writes or document the controlled batch/stream contract.
+- Keep transactions or equivalent atomic units short and free of unrelated external waits.
+- Relational and document-specific modeling rules belong to the selected data derivation blocks.
 
-## F7. Configuration Management
+Inject into `{{ FIXED_RULES_DATABASE }}`.
 
-- **Rule**: Configuration has three tiers — code defaults < environment variables < config files (by priority).
-- **Forbidden**: Committing any secrets, tokens, or passwords to Git.
-- **Rule**: All environment-specific config (database connections, Redis addresses, third-party API keys) injected via environment variables.
-- **Rule**: Must have a `.env.example` file listing all required environment variables with descriptions (use placeholders for values).
-- **RATIONALE**: Separating config from code is a 12-Factor App principle and a security baseline.
+## I7. Observability Integrity
 
----
+- Errors and key operations carry enough correlation context to diagnose one request, job, or message without logging secrets.
+- Logging format and collection topology follow the selected observability decision.
+- Health signals distinguish process liveness from dependency readiness when the deployment environment consumes both.
 
-## F8. Async & Message Queues
+Inject into `{{ FIXED_RULES_OBSERVABILITY }}`.
 
-- **Rule**: Message handlers must be idempotent — replaying the same message produces no side effects.
-- **Rule**: Async tasks must have timeout handling, retry strategy (exponential backoff), and dead letter queues.
-- **Rule**: Message bodies must contain a unique id (for deduplication) and traceId (for tracing).
-- **Rule**: Retry count and interval must have upper limits (e.g., max 3 retries, intervals 1s/5s/15s).
-- **RATIONALE**: The biggest async system problem isn't "messages got lost" — it's "messages got processed twice and double-charged the customer."
+## I8. Trace Continuity
 
-### F8.4 Message Delivery Semantics
+- Preserve an existing correlation or trace context across supported downstream boundaries.
+- Do not silently replace caller-provided valid trace context mid-operation.
+- Distributed tracing is enabled only when selected or required by the deployment; otherwise preserve local correlation identifiers.
 
-- **Rule**: Explicitly document the delivery guarantee for each queue/topic: at-most-once, at-least-once, or exactly-once.
-- **Rule**: At-least-once (default for most systems): consumers must be idempotent.
-- **Rule**: Dead letter queues (DLQ) must be configured. Failed messages route to DLQ after max retries.
-- **Rule**: DLQ messages must have a replay/inspect mechanism. Forbid silently discarding failed messages.
-- **RATIONALE**: The difference between at-least-once and exactly-once is the difference between "customer charged once" and "customer charged twice."
+Inject into `{{ FIXED_RULES_TRACING }}`.
 
-### F8.5 Graceful Shutdown
+## I9. Configuration Safety
 
-- **Rule**: Application must handle SIGTERM gracefully: stop accepting new requests, finish in-progress requests (with timeout), close database connections, flush logs.
-- **Rule**: Shutdown timeout must be configured (default 30s). Kubernetes terminationGracePeriodSeconds must exceed this.
-- **Rule**: In-flight async tasks must complete or be re-queued before shutdown.
-- **Forbidden**: Hard-exit on SIGTERM (SIGKILL should be the fallback, not the default).
-- **RATIONALE**: Deployments and pod restarts should not cause failed requests or lost data. Graceful shutdown is a basic operational requirement.
+- Separate secrets from non-secret configuration and document required configuration without committing secret values.
+- Validate required configuration before serving work.
+- Config modification permission comes only from `{{ ai_config_rule }}`; this invariant does not forbid an authorized change.
 
----
+Inject into `{{ FIXED_RULES_CONFIG }}`.
 
-## F9. Testing
+## I10. Async Safety
 
-- **Rule**: Testing has three tiers — unit tests (service layer), integration tests (API endpoints + database), E2E (critical business flows).
-- **Rule**: External dependencies (database, Redis, third-party APIs) must be mocked in unit tests.
-- **Rule**: Integration tests use a test database or testcontainers. Test data is cleaned before and after each run.
-- **Rule**: Coverage baseline: service layer ≥ 80%, controller layer ≥ 60%.
-- **Forbidden**: Tests sharing mutable state (global variables / shared database rows).
-- **RATIONALE**: Backend regression risk is far higher than frontend (one data corruption is irreversible). Tests are the only safety net.
+- Every asynchronous side effect defines ownership, timeout/cancellation behavior, and duplicate-delivery handling where applicable.
+- Do not claim queue semantics when no queue was selected.
+- Queue-specific retry, ordering, and dead-letter rules come from `{{ mq_rules }}`.
 
----
+Inject into `{{ FIXED_RULES_ASYNC }}`.
 
-## F10. AI Vibecoding Baseline Constraints (project-agnostic, always active)
+## I11. Message Delivery Integrity
 
-### F10.1 Search First
-- **Rule**: Before generating a new module, AI must search existing code to check for similar functionality.
-- **Rule**: Before writing SQL/migrations, AI must read existing migration files and schema.
+- When messaging is selected, document delivery semantics and make consumers safe for the selected duplicate/retry model.
+- Failed messages remain observable and recoverable according to the selected queue capability.
+- Render an explicit not-applicable statement when messaging is not selected.
 
-### F10.2 Dependency Control
-- **Rule**: AI must not modify `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml` on its own.
-- **Rule**: If a new dependency is truly needed, AI must list: package name, version, reason, alternative comparison.
+Inject into `{{ FIXED_RULES_MESSAGE_DELIVERY }}`.
 
-### F10.3 Breaking Changes
-- **Rule**: Before modifying a shared module/utility/API contract, AI must list all callers.
-- **Rule**: Changing API response field names or types requires assessing frontend impact first.
+## I12. Shutdown Integrity
 
-### F10.4 Config Immutability
-- **Rule**: AI must not modify environment variables, database connection config, docker-compose, or CI/CD configuration on its own.
-- **Rule**: Adding a new environment variable in code must be accompanied by an update to `.env.example`.
-
-### F10.5 SQL Safety
-- **Rule**: All AI-written SQL must be parameterized queries.
-- **Forbidden**: AI generating string-concatenated SQL code.
+- Stop accepting new work before releasing resources.
+- Bound shutdown and preserve or requeue owned in-flight work where the runtime supports it.
+- Apply platform-specific signal and probe details through deployment derivation rules.
 
-### F10.6 Migration Files
-- **Rule**: AI generating a new migration must also produce the corresponding rollback migration.
-- **Forbidden**: Dropping columns or changing types in migrations (add-only, unless a rollback plan exists).
+Inject into `{{ FIXED_RULES_GRACEFUL_SHUTDOWN }}`.
 
-### F10.7 Context Honesty
-- **Rule**: When uncertain, AI must explicitly say "I'm not sure." Forbid inventing API paths, library versions, or database field names.
-- **Rule**: AI must read the latest file contents before modifying. Forbid generating diffs based on guesswork.
+## I13. Verification Integrity
 
----
+- Follow the selected testing depth; do not invent unapproved coverage thresholds or mandatory tiers.
+- Enabled tests are deterministic, isolated from production data, and assert behavior rather than implementation accidents.
+- A `not required yet` choice is recorded explicitly with its accepted risk rather than contradicted by unconditional test requirements.
 
-## Injection Instructions (for the AI executing this skill)
+Inject into `{{ FIXED_RULES_TEST }}`.
 
-Each chapter in this file corresponds to a `{{ FIXED_RULES_* }}` placeholder in the template:
+## I14. AI Change Safety
 
-| Chapter | Inject Into Placeholder | Template Section |
-|---------|------------------------|-------------------|
-| F1 Project Structure | `{{ FIXED_RULES_STRUCTURE }}` | §1 Project Structure |
-| F2 API Design | `{{ FIXED_RULES_API }}` | §2 API Design |
-| F3 Error Handling | `{{ FIXED_RULES_ERROR }}` | §3 Error Handling |
-| F4 Security | `{{ FIXED_RULES_SECURITY }}` | §4 Security (F4.1-F4.3 only; stop before F4.4) |
-| F4.4 Rate Limiting | `{{ FIXED_RULES_RATE_LIMITING }}` | §4 Security (F4.4 only, injected separately) |
-| F5 Database | `{{ FIXED_RULES_DATABASE }}` | §5 Database |
-| F6 Observability | `{{ FIXED_RULES_OBSERVABILITY }}` | §6 Observability (F6 + F6.3 only; stop before F6.2) |
-| F6.2 Distributed Tracing | `{{ FIXED_RULES_TRACING }}` | §6 Observability (F6.2 only, injected separately) |
-| F7 Configuration | `{{ FIXED_RULES_CONFIG }}` | §7 Configuration |
-| F8 Async & Queues | `{{ FIXED_RULES_ASYNC }}` | §8 Async & Queues |
-| F8.4 Message Delivery | `{{ FIXED_RULES_MESSAGE_DELIVERY }}` | §8 Async & Queues |
-| F8.5 Graceful Shutdown | `{{ FIXED_RULES_GRACEFUL_SHUTDOWN }}` | §8 Async & Queues |
-| F9 Testing | `{{ FIXED_RULES_TEST }}` | §9 Testing |
-| F10 AI Constraints | `{{ FIXED_RULES_AI_BASE }}` | §10 AI Behavior Constraints |
+- Read current code and search for existing ownership before creating duplicate modules or contracts.
+- Keep changes inside the requested scope and report uncertainty rather than inventing endpoints, fields, versions, or infrastructure.
+- Never expose secrets, weaken authorization, or bypass data safety merely to make a check pass.
+- Dependency, caller-analysis, and config permissions come only from their selected rule blocks.
 
-**Rendering rules**:
-1. Copy each chapter's full body (including RATIONALE) directly into the corresponding placeholder.
-2. RATIONALE must be preserved — it lets AI understand intent rather than follow mechanically.
-3. Keep the original markdown list structure. Do not rewrite as prose paragraphs.
+Inject into `{{ FIXED_RULES_AI_BASE }}`.
+
+## Injection Contract
+
+Copy each invariant block only into its named placeholder. If any invariant conflicts with a selected decision, fail generation and move the policy to a derivation block; never render both.